1 1# -*- mode: Outline -*-
3 # klips2-design-api.txt
4 # Richard Guy Briggs <rgb@conscoop.ottawa.on.ca>
6 # RCSID $Id: klips2-design-api.txt,v 1.21 2001/06/26 20:29:25 rgb Exp $
9 * Outline Commands cheat sheet (C-c C-s to see this)
10 C-c C-t Hide EVERYTHING in buffer
11 C-c C-a Show EVERYTHING in buffer
13 C-c C-d Hide THIS item and subitems (subtree)
14 C-c C-s Show THIS item and subitems (subtree)
20 This document describes all the APIs used in this design.
21 Please see klips2-design.txt for an overview of the
22 architecture. This document is divided into an emacs outline
23 mode cheat sheet, Introduction, Generic Iptables
24 interfaces, KLIPS2 Interfaces, Definitions and Data structures
25 used, and document version.
28 interface description, listing origin and destination
29 entities, separated by an ">->" with diagram label, if it
30 exists within double quotes ``"''
36 the name of the function used and a very brief description
39 function form, argument position, type and return type
42 description of each argument
45 description of interface and function
47 ** Implementation notes:
48 caveats and side effects
51 function return values
57 related documentation or further explanation
61 * Generic Iptables interfaces
63 ** iptables(8) >-> generic match iptables(8) library
64 ** ip6tables(8) >-> generic match ip6tables(8) library
68 iptables(8) >-> generic match iptables(8) library
69 ip6tables(8) >-> generic match ip6tables(8) library
75 (*generic_parse) - parse, convert and check generic options
85 const struct ipt_entry *entry,
86 unsigned int *nfcache,
87 struct ipt_entry_match **match
96 text arguments to be parsed by this match
102 bitmap to indicate which arguments have been processed
105 pointer to table entry associated with match
108 bitmap of skb parts examined by this match
111 match data -- customised match data is contained in
116 This function parses, converts and checks iptables(8)
117 and ip6tables(8) command line "generic" text
118 arguments for use by the "generic" match NetFilter kernel
121 Input is expected to be in the form of a text string
122 specifying a "generic" characteristic associated with the
125 Implementation notes:
127 A data structure to store parsed and converted
128 arguments in a form consumable by the corresponding
129 kernel module is pointed to by match->data. Replace
130 ipt_generic_info with the customised data structure.
134 1 if an option was eaten, 0 if not.
144 const struct ipt_entry *entry,
145 unsigned int *nfcache,
146 struct ipt_entry_match **match
148 struct ipt_generic_info *info = (struct ipt_generic_info*)(*match)->data;
150 /* parse option arguments */
155 struct iptables_match generic_match_lib = {
159 IPT_ALIGN(sizeof(struct ipt_generic_info)),
160 IPT_ALIGN(sizeof(struct ipt_generic_info)),
164 &generic_final_check,
173 register_match(&generic_match_lib);
180 ** iptables(8) >-> GENERIC target iptables(8) library
181 ** ip6tables(8) >-> GENERIC target ip6tables(8) library
185 iptables(8) >-> GENERIC target iptables(8) library
186 ip6tables(8) >-> GENERIC target ip6tables(8) library
194 static int generic_parse(
199 const struct ipt_entry *entry,
200 struct ipt_entry_target **target
209 text arguments to be parsed by this target
212 invert flag (doesn't make sense for targets)
215 bitmap to indicate which arguments have been processed
218 pointer to table entry associated with target
221 target data -- customised target data is contained in
226 This function parses, converts and checks iptables(8)
227 and ip6tables(8) command line "GENERIC" text
228 arguments for use by the "GENERIC" target NetFilter kernel
231 Input is expected to be in the form of a text string
232 specifying a "generic" characteristic to be applied to the
235 Implementation notes:
237 A data structure to store parsed and converted
238 arguments in a form consumable by the corresponding
239 kernel module is pointed to by target->data. Replace
240 ipt_generic_target_info with the customised data
241 structure, if there is any.
245 1 if an option was eaten, 0 if not.
255 const struct ipt_entry *entry,
256 struct ipt_entry_target **target
258 struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)(*target)->data;
260 /* parse option arguments */
265 struct iptables_target generic_target_lib = {
269 IPT_ALIGN(sizeof(struct ipt_generic_target_info)),
270 IPT_ALIGN(sizeof(struct ipt_generic_target_info)),
274 &generic_final_check,
283 register_target(&generic_target_lib);
288 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
292 ** NetFilter >-> generic match NetFilter kernel module
296 NetFilter >-> generic match NetFilter kernel module
302 (*generic_match) - does the packet match the generic
307 static int generic_match(
308 const struct sk_buff *skb,
309 const struct net_device *in,
310 const struct net_device *out,
311 const void *matchinfo,
321 skb to test for match
324 incoming network interface
327 outgoing network interface
336 transport layer header pointer
342 flag to immediately drop packet
346 This function checks if the skb supplied matches
347 the generic packet characteristics specified in
350 Implementation notes:
352 Replace ipt_generic_info with the customised data
357 It returns true (1) for match, false (0) for no match.
363 const struct sk_buff *skb,
364 const struct net_device *in,
365 const struct net_device *out,
366 const void *matchinfo,
372 struct ipt_generic_info *info = (struct ipt_generic_info*)matchinfo;
374 if(/* test skb for match to matchinfo data */) {
380 static struct ipt_match generic_match_mod = {
392 return ipt_register_match(&generic_match_mod);
398 ipt_unregister_match(&generic_match_mod);
403 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
407 ** NetFilter >-> GENERIC target NetFilter kernel module
411 NetFilter >-> GENERIC target NetFilter kernel module
417 (*generic_target) - process outgoing packet with
418 "generic" information supplied
424 struct sk_buff **pskb,
425 unsigned int hooknum,
426 const struct net_device *in,
427 const struct net_device *out,
428 const void *targinfo,
435 skb to be processed by target
438 which hook from which it was called
441 network device it came from
444 network device to which it is headed
447 data used by target for processing
450 optional user data passed in from mainline
455 This is a NetFilter target. It applies the generic
456 information supplied with the target to the outgoing
459 Implementation notes:
461 Replace ipt_generic_target_info with the customised data
462 structure, if there is one.
466 It returns <verdict>.
470 File net/ipv4/netfilter/ipt_GENERIC.c:
471 #include <linux/netfilter_ipv4/ip_tables.h>
474 generic_target(struct sk_buff **pskb,
475 unsigned int hooknum,
476 const struct net_device *in,
477 const struct net_device *out,
478 const void *targinfo,
481 struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)targinfo;
482 /* do target processing */
486 static struct ipt_target generic_target_mod = {
495 static int __init init(void)
497 if (ipt_register_target(&generic_target_mod))
502 static void __exit fini(void)
504 ipt_unregister_target(&generic_target_mod);
509 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
515 ** KMd >-> iptables(8) "Policy"
516 ** KMd >-> ip6tables(8) "Policy"
529 system(3) call to iptables(8) - execute a shell
530 command to do IP packet filter administration to set
537 int system(const char * "iptables \
539 --new-table chain ");
540 int system(const char * "iptables \
542 --policy chain target");
543 int system(const char * "iptables \
545 --{append,delete,insert,replace} chain \
546 --protocol protocol \
550 --in-interface IPSECdev \
551 --out-interface IPSECdev \
552 --source-port SPORT \
553 --destination-port DPORT \
566 specify ipsec SPDB NetFilter kernel table
569 create new chain in ipsec SPDB
571 --policy chain target
572 set default target for specified chain
574 --{append,delete,insert,replace} chain
575 manipulate a rule in the specified chain
578 protocol for the matching rule
581 source address for the matching rule
584 destination address for the matching rule
586 --in-interface IPSECdev
587 incoming ipsec device for the matching rule
589 --out-interface IPSECdev
590 outgoing ipsec device for the matching rule
593 source port for the matching rule (tcp or udp)
595 --destination-port DPORT
596 destination port for the matching rule (tcp or udp)
599 user ID for the matching rule
602 Encapsulation Security Payload Security Parameters
603 Index for the matching rule
606 security or sensitivity level or label for the
610 Security Association IDentifier list for the matching
614 target for a matching packet
618 This is the SPDB (or as yet undefined PF_POLICY)
619 interface from the key management daemons to the
620 kernel via netfilter.
622 The default chains of in and out are created when the
623 table is created. Additional chains can be created as
624 needed with the iptables --new-chain command and can
625 be listed as targets to match entries.
627 The default policy of each chain can be changed from
628 the initialised value of DROP (TRAP?) with the
629 iptables --policy command. The default policy of each
630 chain is one of the standard NetFilter targets of
631 ACCEPT, DROP, REJECT. IPSec adds the targets TRAP,
632 HOLD (internal), PEEK and IPSEC. Only the IPSEC
633 target takes any arguments, which consists of a list
634 of SAs to be used for processing.
636 Rules are appended, inserted, deleted or replaced to
637 set the IPSec policy.
639 Packets can be matched on IP transport protocol,
640 source or destination address, incoming or outgoing
641 ipsec device, source or destination port for tcp or
642 udp, user ID, Encapsulation Security Payload or
643 Authentication Header Security Parameters Index,
644 security or sensitivity level or label, Security
645 Association IDentifier list. A target must be
646 specified for each matching rule using the iptables
649 Implementation notes:
651 If the in and out chains don't yet exist, they must be
652 created with the iptables --new-chain command. (These
653 will most likely be created by loading the module and
654 so this paragraph may disappear.)
656 An alternative may be to have the KMd link directly
657 with iptables.o rather than invoking system(3) to call
660 It looks like it may be possible to call the libipt
661 functions directly, which will be a big help in
662 speeding things up since text conversion and parsing
663 won't have to be done. This will change most of the
664 char fields to binary fields and change the calling
665 function and return codes.
670 The value returned is 127 if the execve() call for
671 /bin/sh fails, -1 if there was another error.
674 Various error messages are printed to standard error.
675 The exit code is 0 for correct functioning. Errors
676 which appear to be caused by invalid or abused command
677 line parameters cause an exit code of 2, and other
678 errors cause an exit code of 1.
687 if((return = system("iptables \
690 --source this-subnet.example.com \
691 --destination that-subnet.example.com \
693 --use-salist esp.12345678@that-sg.example.com \
695 fprintf(stderr, "error $d calling iptables\n");
701 system(3), iptables(8)
705 ** iptables(8) >-> seclev match iptables(8) library
706 ** ip6tables(8) >-> seclev match ip6tables(8) library
710 iptables(8) >-> seclev match iptables(8) library
711 ip6tables(8) >-> seclev match ip6tables(8) library
717 (*seclev_parse) - parse, convert and check security level options
721 see: iptables(8) >-> generic match iptables(8) library
725 see: iptables(8) >-> generic match iptables(8) library
729 This function parses, converts and checks iptables(8)
730 and ip6tables(8) command line security level text
731 arguments for use by the seclev match NetFilter kernel
734 Input is expected to be in the form of "--seclev
735 seclevstr" where seclevstr is the security (or
736 sensitivity) level (or label) associated with the
739 Implementation notes:
741 I don't actually what form security level data takes,
742 but that can be sorted out later.
744 Use the data structure ipt_seclev_info.
748 see: iptables(8) >-> generic match iptables(8) library
752 see: iptables(8) >-> generic match iptables(8) library
756 iptables(8) >-> generic match iptables(8) library
760 ** iptables(8) >-> salist match iptables(8) library
761 ** ip6tables(8) >-> salist match ip6tables(8) library
765 iptables(8) >-> salist match iptables(8) library
766 ip6tables(8) >-> salist match ip6tables(8) library
772 (*salist_parse) - parse, convert and check security
773 association list options
777 see: iptables(8) >-> generic match iptables(8) library
781 see: iptables(8) >-> generic match iptables(8) library
785 This function parses, converts and checks iptables(8)
786 and ip6tables(8) command line security association
787 list level text arguments for use by the salist match
788 NetFilter kernel module.
790 Input is expected to be in the form of "--salist
791 SAList" where SAList is the security association list
792 associated with the packet.
794 Implementation notes:
796 Use the data structure ipt_salist_info.
800 see: iptables(8) >-> generic match iptables(8) library
804 see: iptables(8) >-> generic match iptables(8) library
808 iptables(8) >-> generic match iptables(8) library
809 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
813 ** iptables(8) >-> TRAP target iptables(8) library
814 ** ip6tables(8) >-> TRAP target ip6tables(8) library
818 iptables(8) >-> TRAP target iptables(8) library
819 ip6tables(8) >-> TRAP target ip6tables(8) library
825 (*trap_parse) - parse, convert and check TRAP options
829 see: iptables(8) >-> GENERIC target iptables(8) library
833 see: iptables(8) >-> GENERIC target iptables(8) library
837 This function parses, converts and checks iptables(8)
838 and ip6tables(8) command line TRAP text
839 arguments for use by the TRAP target NetFilter kernel
842 No input is expected.
844 Implementation notes:
848 see: iptables(8) >-> GENERIC target iptables(8) library
852 see: iptables(8) >-> GENERIC target iptables(8) library
856 iptables(8) >-> GENERIC target iptables(8) library
857 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
861 ** iptables(8) >-> HOLD target iptables(8) library
862 ** ip6tables(8) >-> HOLD target ip6tables(8) library
866 iptables(8) >-> HOLD target iptables(8) library
867 ip6tables(8) >-> HOLD target ip6tables(8) library
875 see: iptables(8) >-> GENERIC target iptables(8) library
879 see: iptables(8) >-> GENERIC target iptables(8) library
883 This function parses, converts and checks iptables(8)
884 and ip6tables(8) command line HOLD text
885 arguments for use by the HOLD target NetFilter kernel
888 No input is expected.
890 Implementation notes:
894 see: iptables(8) >-> GENERIC target iptables(8) library
898 see: iptables(8) >-> GENERIC target iptables(8) library
902 iptables(8) >-> GENERIC target iptables(8) library
903 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
907 ** iptables(8) >-> PEEK target iptables(8) library
908 ** ip6tables(8) >-> PEEK target ip6tables(8) library
912 iptables(8) >-> PEEK target iptables(8) library
913 ip6tables(8) >-> PEEK target ip6tables(8) library
921 see: iptables(8) >-> GENERIC target iptables(8) library
925 see: iptables(8) >-> GENERIC target iptables(8) library
929 This function parses, converts and checks iptables(8)
930 and ip6tables(8) command line PEEK text
931 arguments for use by the PEEK target NetFilter kernel
934 No input is expected.
936 Implementation notes:
940 see: iptables(8) >-> GENERIC target iptables(8) library
944 see: iptables(8) >-> GENERIC target iptables(8) library
948 iptables(8) >-> GENERIC target iptables(8) library
949 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
953 ** iptables(8) >-> IPSEC target iptables(8) library
954 ** ip6tables(8) >-> IPSEC target ip6tables(8) library
958 iptables(8) >-> IPSEC target iptables(8) library
959 ip6tables(8) >-> IPSEC target ip6tables(8) library
967 see: iptables(8) >-> GENERIC target iptables(8) library
971 see: iptables(8) >-> GENERIC target iptables(8) library
975 This function parses, converts and checks iptables(8)
976 and ip6tables(8) command line IPSEC text arguments for
977 use by the IPSEC target NetFilter kernel module.
979 Input is expected to be in the form of "--salist
980 SAList" where SAList is the security association list
981 to be applied to packets sent to the IPSEC target.
983 Implementation notes:
985 Use the data structure ipt_ipsec_target_info.
989 see: iptables(8) >-> GENERIC target iptables(8) library
993 see: iptables(8) >-> GENERIC target iptables(8) library
997 iptables(8) >-> GENERIC target iptables(8) library
998 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1002 ** iptables(8) >-> NetFilter
1003 ** ip6tables(8) >-> NetFilter
1007 iptables(8) >-> NetFilter
1008 ip6tables(8) >-> NetFilter
1018 match->data = struct ipt_seclev_info
1019 match->data = struct ipt_salist_info
1020 target->data = struct ipt_ipsec_target_info
1024 This I/F is already defined in NetFilter using
1025 get/set_sockopt(). We don't call it directly. In
1026 addition, it will need structures to pass the
1027 arguments above. This interface provides a mechanism
1028 for iptables to update the kernel netfilter tables.
1030 Implementation notes:
1038 iptables-1.2.2/libiptc/
1042 ** NetFilter >-> seclev match NetFilter kernel module
1046 NetFilter >-> seclev match NetFilter kernel module
1052 (*seclev_match) - does the packet match Security
1057 see: NetFilter >-> generic match NetFilter kernel module
1061 see: NetFilter >-> generic match NetFilter kernel module
1065 This function checks if the skb supplied matches
1066 the security level specified in matchinfo.
1068 Implementation notes:
1070 Use the data structure ipt_seclev_info.
1074 see: NetFilter >-> generic match NetFilter kernel module
1078 see: NetFilter >-> generic match NetFilter kernel module
1082 NetFilter >-> seclev match NetFilter kernel module
1083 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1087 ** NetFilter >-> salist match NetFilter kernel module
1091 NetFilter >-> salist match NetFilter kernel module
1097 (*salist_match) - does the packet match the Security
1102 see: NetFilter >-> generic match NetFilter kernel module
1106 see: NetFilter >-> generic match NetFilter kernel module
1110 This function checks if the skb supplied matches
1111 the Security Association list specified in matchinfo.
1113 Implementation notes:
1115 Use the data structure ipt_salist_info.
1119 see: NetFilter >-> generic match NetFilter kernel module
1123 see: NetFilter >-> generic match NetFilter kernel module
1127 NetFilter >-> generic match NetFilter kernel module
1128 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1132 ** NetFilter >-> TRAP target NetFilter kernel module
1136 NetFilter >-> TRAP target NetFilter kernel module
1144 (*trap_target) - TRAP outgoing packets to initiate
1149 see: NetFilter >-> GENERIC target NetFilter kernel module
1153 see: NetFilter >-> GENERIC target NetFilter kernel module
1157 This is a NetFilter target. It TRAPs packets to notify the
1158 key management daemons to acquire a new set of
1159 Security Associations and to set up a HOLD to save it
1160 until the acquire has succeeded.
1162 Implementation notes:
1166 It returns NF_STOLEN.
1170 see: NetFilter >-> GENERIC target NetFilter kernel module
1174 NetFilter >-> GENERIC target NetFilter kernel module
1175 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1179 ** TRAP target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1183 TRAP target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1187 see RFC2367, PF_KEYv2 ACQUIRE
1191 see RFC2367, PF_KEYv2 ACQUIRE
1195 see RFC2367, PF_KEYv2 ACQUIRE
1199 see RFC2367, PF_KEYv2 ACQUIRE
1203 This interface is used to make requests from the
1204 kernel to key management daemons for a set of Security
1205 Associations to cover the specified traffic named to a
1208 Implementation notes:
1212 see RFC2367, PF_KEYv2 ACQUIRE
1220 ** TRAP target NetFilter kernel module >-> NetFilter
1224 TRAP target NetFilter kernel module >-> NetFilter
1238 This interface is used by the NetFilter TRAP target
1239 kernel module to set up a HOLD to save outgoing
1240 packets until the acquire has succeeded, limiting the
1241 demand on the PF_KEYv2 ACQUIRE interface.
1243 Implementation notes:
1245 At present, this looks really ugly. The table can
1246 only be modified from userspace by reading the entire
1247 table and then replacing the entire table atomically.
1249 It will have to use the get/set_sockopt() interface
1250 similar to what userspace uses, except from
1251 kernelspace, duplicating some of the libiptc code,
1252 taking a copy of the entire table and atomically
1253 replacing all of the copies on all the CPUs.
1255 There is talk about iptables being rewritten so that
1256 the table is updated more gracefully.
1258 There have been suggestions of using ippool, but this
1259 appears to take a huge amount of memory for what we
1260 need to be able to do.
1262 Queue to userspace has also been suggested, but we
1263 don't want to send the packet to userspace. We are
1264 trying to avoid that by doing a HOLD.
1266 After the HOLD is in place, the packet would be
1277 ** NetFilter >-> HOLD target NetFilter kernel module
1281 NetFilter >-> HOLD target NetFilter kernel module
1287 (*hold_target) - HOLD packets to prevent key
1288 management daemon flooding
1292 see: NetFilter >-> GENERIC target NetFilter kernel module
1296 see: NetFilter >-> GENERIC target NetFilter kernel module
1300 This is a NetFilter target. It discards the
1301 previous held packet and holds onto the
1302 last packet packet pending replacement by an SPDB
1303 change that deletes this HOLD and releases the packet.
1305 Implementation notes:
1307 There sound like there will be problems with this
1308 because of the atomic complete replacement of the
1309 table at which point any data stored with the target
1314 It returns NF_STOLEN.
1318 see: NetFilter >-> GENERIC target NetFilter kernel module
1322 NetFilter >-> GENERIC target NetFilter kernel module
1323 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1327 ** KMd >-> SADB "PF_KEYv2 ADD/UPDATE"
1331 KMd >-> SADB "PF_KEYv2 ADD/UPDATE"
1335 see RFC2367, PF_KEYv2 ADD/UPDATE
1339 see RFC2367, PF_KEYv2 ADD/UPDATE
1343 see RFC2367, PF_KEYv2 ADD/UPDATE
1347 see RFC2367, PF_KEYv2 ADD/UPDATE
1351 This interface is used by key management daemons to
1352 set incoming or outgoing Security Associations in the
1353 kernel to/from a remote host.
1355 Implementation notes:
1359 see RFC2367, PF_KEYv2 ADD/UPDATE
1367 ** HOLD target NetFilter kernel module >-> NetFilter
1371 HOLD target NetFilter kernel module >-> NetFilter
1377 ip_finish_output - re-submit the packet to the output
1378 queue, now that the HOLD has been cleared.
1380 NF_HOOK(PF_INET, NF_IP_POST_ROUTING, skb, NULL, rt->u.dst.dev, ip_finish_output2);
1392 packet to be re-submitted
1396 This interface provides a method for previously held
1397 packets to be released and re-submitted once the
1398 HOLD SPDB entry has been replaced or deleted, usually
1399 pointing to newly created Security Associations that
1400 were aquired to cover that packet stream.
1402 The packet is re-submitted just before
1405 Implementation notes:
1407 I don't know the best way to show this on the diagram,
1408 since the skb is stored with the eroute and not the
1409 HOLD target module. The best way to implement this
1410 might be when the table gets replaced, release all
1411 held packets and let them be re-caught by the table.
1413 int ip_finish_output(struct sk_buff *skb) is a good
1414 possibility since all it does is call
1415 NF_IP_POST_ROUTING hook and that is where the packet
1416 would have been HOLD'ed.
1420 0 if everything worked out, -ENOMEM if the kernel ran
1421 out of buffers, -EPERM if a verdicet of NF_DROP was
1422 returned because the firewall refused to let it pass.
1423 Other errors are possible from other output functions
1424 associated with firewall targets.
1428 ip_finish_output(skb);
1434 ** NetFilter >-> IPSEC target NetFilter kernel module
1438 NetFilter >-> IPSEC target NetFilter kernel module
1444 (*ipsec_target) - process outgoing packet with
1445 specified Security Associations
1449 see: NetFilter >-> GENERIC target NetFilter kernel module
1453 see: NetFilter >-> GENERIC target NetFilter kernel module
1457 This is a NetFilter target. It looks up the Security
1458 Associations listed as an argument, in the Security
1459 Association DataBase, and applies them in sequence to
1460 the outgoing packet.
1462 Implementation notes:
1464 Use the data structure ipt_ipsec_target_info.
1468 It returns NF_STOLEN.
1472 see: NetFilter >-> GENERIC target NetFilter kernel module
1476 NetFilter >-> GENERIC target NetFilter kernel module
1477 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1481 ** IPSEC target NetFilter kernel module >-> SADB "SAID"
1485 IPSEC target NetFilter kernel module >-> SADB
1493 ipsec_getsa - get an SA from the SADB by SAID
1497 #include <ipsec_sadb.h>
1501 struct ipsec_said asaid
1507 Security Association IDentifier to try to
1513 Retrieve a Security Association from the system
1514 Security Association DataBase that matches the
1515 supplied Security Association IDentifier.
1517 The Security Association IDentifier must be supplied
1518 as a completely filled struct ipsec_said. ipsec_getsa() attempts
1519 to exactly match the SAID structure of an SA
1520 entry in the global SADB hash table ipsec_sadb with
1521 the SAID argument. If this succeeds,
1522 a pointer to the matching SA is returned.
1524 Implementation notes:
1526 The reference count of the matching SA is atomically
1527 incremented by ipsec_getsa() and must be atomically
1528 decremented when the caller of ipsec_getsa() has
1529 finished with the SA.
1531 The global SADB hash table struct
1532 ipsec_sa*ipsec_sadb[] is locked by ipsec_getsa()
1537 A pointer to a valid Security Association is returned
1538 if a match was found, otherwise NULL is returned.
1542 struct ipsec_sa *sa;
1543 struct ipsec_said said;
1545 sa = ipsec_getsa(said);
1547 if(atomic_dec_and_test(sa->refcount)) {
1555 ** IPSEC target NetFilter kernel module >-> NetFilter
1559 IPSEC target NetFilter kernel module >-> NetFilter
1565 ip_queue_xmit - re-submit the packet to the output
1566 queue, now that the packet has been IPSec pocessed.
1568 NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_queue_xmit2);
1570 NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_send);
1582 socket buffer to be sent
1586 This interface is to re-inject packets before
1587 NF_IP_LOCAL_OUT after the packet has been processed.
1589 Implementation notes:
1591 int ip_queue_xmit(struct sk_buff *skb) is another possibility...
1595 0 if everything worked out. -ENOMEM if the kernel ran
1596 out of buffers. -EPERM if a verdicet of NF_DROP was
1597 returned because the firewall refused to let it pass.
1598 -EHOSTUNREACH if routing failed.
1599 Other errors are possible from other output functions
1600 associated with firewall targets.
1612 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1616 ** SADB >-> KMd "PF_KEYv2 EXPIRE"
1620 SADB >-> KMd "PF_KEYv2 EXPIRE"
1624 see RFC2367, PF_KEYv2 EXPIRE
1628 see RFC2367, PF_KEYv2 EXPIRE
1632 see RFC2367, PF_KEYv2 EXPIRE
1636 see RFC2367, PF_KEYv2 EXPIRE
1640 This interface is used by the kernel to notify key
1641 management daemons that a security association has
1642 either soft or hard expired and to negotiate a
1645 Implementation notes:
1649 see RFC2367, PF_KEYv2 EXPIRE
1656 ** Routing Table >-> IPSEC target NetFilter kernel module "IPSECdev"
1660 Routing Table >-> IPSEC target NetFilter kernel module
1674 This interface provides a way of routing packets
1675 through a specific IPSec virtual tunnel. This is
1676 standard linux network routing.
1678 Implementation notes:
1688 ** KMd >-> Routing Table "Routing"
1692 KMd >-> Routing Table
1700 system(3) call to route(8) - execute a shell
1701 command to do IP packet routing administration to set
1710 const char * "route \
1711 {add,del} -{host,net} \
1712 {<host>,<net>[/mask]} \
1720 add an entry to the routing table
1723 delete an entry from the routing table
1726 add or delete a host
1729 add or delete a network
1732 host FQDN or IPv4 or IPv6 address
1735 network FQDN or IPv4 or IPv6 address with netmask
1738 nexthop gateway address
1743 unsigned char exit_code
1747 This is an interface from the key management daemon to
1748 explicitly route traffic through an IPSEC virtual
1749 device which is defined by a pair of IPSEC tunnel
1750 endpoints and a set of Security Associations.
1752 Implementation notes:
1754 currently done by system(3) calls to _updown.
1762 system(3), route(8), iproute2(8)
1766 ** Transport Layer De-mux >-> IPSec DECRYPT kernel module
1770 Transport Layer De-mux >-> IPSec DECRYPT kernel module
1776 ipsec_rcv - process an incoming IPSec packet
1779 #include <ipsec_rcv.h>
1783 struct sk_buff *skb,
1793 length of skb buffer
1797 This interface is to call the IPSEC ESP transport
1798 layer protocol handler to process (decrypt) an
1801 The packet is freed, being re-injected before the
1802 NF_IP_PRE_ROUTING hook.
1804 Implementation notes:
1808 ipsec_rcv() returns zero (0).
1816 ** IPSec DECRYPT kernel module >-> SADB "SAID"
1820 IPSec DECRYPT kernel module >-> SADB
1828 ipsec_getsa - get an SA from the SADB by SAID
1832 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1836 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1840 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1842 Implementation notes:
1844 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1848 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1852 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1856 IPSEC target NetFilter kernel module >-> SADB "SAID"
1859 ** IPSec DECRYPT kernel module >-> NetFilter
1863 IPSec DECRYPT kernel module >-> NetFilter
1869 int netif_rx(struct sk_buff *skb) - post buffer to the network code, always succeeds
1871 ip_rcv - receive an IP packet for input processing
1873 NF_HOOK(PF_INET, NF_IP_PRE_ROUTING, skb, dev, NULL, ip_rcv_finish);
1879 struct sk_buff *skb,
1880 struct net_device *dev,
1881 struct packet_type *pt
1887 packet to be re-injected
1890 incoming device, virtual if there is one.
1893 packet type (not used)
1898 This interface is to re-start the packet input
1899 processing procedure once an IPSec layer has been
1900 peeled away. The packet is made available to the
1901 input stream before NF_IP_PRE_ROUTE to check policy
1902 with processed (decrypted) connection information.
1904 Implementation notes:
1908 0 if everything worked out, -ENOMEM if the kernel ran
1909 out of buffers, -EPERM if a verdicet of NF_DROP was
1910 returned because the firewall refused to let it pass.
1911 Other errors are possible from other output functions
1912 associated with firewall targets.
1920 ip_rcv(skb, skb->dev, NULL)
1926 ** NetFilter >-> PEEK target NetFilter kernel module
1930 NetFilter >-> PEEK target NetFilter kernel module
1936 (*peek_target) - PEEK at packets to initiate opportunism
1940 see: NetFilter >-> GENERIC target NetFilter kernel module
1944 see: NetFilter >-> GENERIC target NetFilter kernel module
1948 This interface is used by the kernel netfilter table
1949 as a target for packets to be PEEKed at to notify the
1950 key management daemons to acquire a new set of
1951 Security Associations and to set up an ACCEPT to allow
1952 packets in and avoid overloading the KMds.
1954 Implementation notes:
1958 It returns NF_ACCEPT.
1962 see: NetFilter >-> GENERIC target NetFilter kernel module
1966 NetFilter >-> GENERIC target NetFilter kernel module
1967 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1971 ** PEEK target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1975 PEEK target NetFilter kernel module >-> KMds
1983 see RFC2367, PF_KEYv2 ACQUIRE
1987 see RFC2367, PF_KEYv2 ACQUIRE
1991 see RFC2367, PF_KEYv2 ACQUIRE
1995 This interface is used to make requests from the
1996 kernel to key management daemons for a set of Security
1997 Associations to cover the specified traffic named to a
2000 Implementation notes:
2004 see RFC2367, PF_KEYv2 ACQUIRE
2010 see RFC2367, PF_KEYv2 ACQUIRE
2014 ** New I/F section template
2028 Implementation notes:
2038 * Definitions and Data structures used
2040 SAList := <SAID>[,<SAID>[,<SAID>[,<SAID>]]]
2042 <SAID> := <proto><PF><spi>@<dstaddr>
2044 <proto> := ah | esp | comp | tun
2046 <PF> := . | : (indicates IPv4 or IPv6 respectively)
2048 <spi> := <8-digit hexadecimal string>
2050 <dstaddr> := <any valid FQDN or IP address of the appropriate family>
2053 const struct ipt_entry is already defined in netfilter.
2055 struct ipt_entry_match is already defined in netfilter.
2057 struct ipsec_seclev remains to be defined.
2059 struct ipt_seclev_info {
2060 struct ipsec_seclev; /* Security Level data */
2061 u_int8_t invert; /* Invert match */
2064 struct ipsec_salist {
2065 struct ipsec_said said1;
2066 struct ipsec_said said2;
2067 struct ipsec_said said3;
2068 struct ipsec_said said4;
2071 struct ipt_salist_info {
2072 struct ipsec_salist salist; /* Security Association List data */
2073 u_int8_t invert; /* Invert match */
2076 struct ipt_ipsec_target_info {
2077 struct ipsec_said said1;
2078 struct ipsec_said said2;
2079 struct ipsec_said said3;
2080 struct ipsec_said said4;
2083 struct ipsec_said{ /* to identify an SA, we need: */
2084 ip_address dst; /* A. destination host */
2085 ipsec_spi_t spi; /* B. 32-bit SPI, assigned by dest. host */
2086 # define SPI_PASS 256 /* magic values... */
2087 # define SPI_DROP 257 /* ...for use... */
2088 # define SPI_REJECT 258 /* ...with SA_INT */
2089 # define SPI_HOLD 259
2090 # define SPI_TRAP 260
2091 int proto; /* C. protocol */
2092 # define SA_ESP 50 /* IPPROTO_ESP */
2093 # define SA_AH 51 /* IPPROTO_AH */
2094 # define SA_IPIP 4 /* IPPROTO_IPIP */
2095 # define SA_COMP 108 /* IPPROTO_COMP */
2096 # define SA_INT 61 /* IANA reserved for internal use */
2101 struct sockaddr_in v4;
2102 struct sockaddr_in6 v6;
2107 /* copy most from struct tdb */
2111 struct ipt_entry_target t;
2112 struct ipt_ipsec_target_info salist;
2116 struct ipt_entry_target t;
2120 struct ipt_entry_target t;
2124 struct ipt_entry_target t;
2129 $Id: klips2-design-api.txt,v 1.21 2001/06/26 20:29:25 rgb Exp $