1 # -*- mode: Outline; fill-column: 78; fill-prefix: " " -*-
3 # klips2-design-api-trips.txt
4 # Richard Guy Briggs <rgb@conscoop.ottawa.on.ca>
6 # RCSID $Id: klips2-design-api-trips.txt,v 1.8 2001/05/30 08:00:14 rgb Exp $
9 # This document outlines various trips that are made through the
10 # various APIs for different scenarios. Please see klips2-design.txt
13 # Several scenario titles are listed. Under each scenario title is
14 # listed point form text to describe what action is happenning and/or
15 # the reason for the following calls. Following the descriptive text
16 # is a origin and destination entity interface description. Within
17 # each interface description is a list of specific arguments used or
18 # that need to be added to accomplish the action.
20 Opportunistic encryption:
21 - put a trap in place from KMd
22 KMd -> iptables(8) system(3) call (Policy)
23 KMd -> ip6tables(8) system(3) call (Policy)
28 char[] --protocol PROTO
31 char[] --uid-owner UID
32 char[] --seclev seclevstr
35 unsigned char exit_code
37 iptables(8) -> seclev match iptables(8) library
38 ip6tables(8) -> seclev match ip6tables(8) library
40 char[] --seclev seclevstr
44 iptables(8) -> NetFilter
45 ip6tables(8) -> NetFilter
46 I/F is already defined in NetFilter. In addition, it will
47 need structures to pass the following:
53 NetFilter -> seclev match NetFilter kernel module
60 NetFilter -> sa match NetFilter kernel module
63 struct ip_said SA[,...]
68 NetFilter -> TRAP target NetFilter kernel module
72 unsigned int = NF_STOLEN
75 TRAP target NetFilter kernel module -> KMds (PF_KEYv2 ACQUIRE)
76 see RFC2367, PF_KEYv2 ACQUIRE
78 - create HOLD target with skb info and store the first packet
79 TRAP target NetFilter kernel module -> NetFilter
85 - next packet comes in while KMd is negotiating SAs.
86 NetFilter -> seclev match NetFilter kernel module
93 NetFilter -> sa match NetFilter kernel module
96 struct ip_said SA[,...]
100 - packet matches HOLD so discard previous skb (packet) and store this one
101 NetFilter -> HOLD target NetFilter kernel module
105 unsigned int = NF_STOLEN
107 - put the new SAs in place once the negotiations have succeeded
108 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
109 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
111 - add ENCRYPT target with specific SAs to use
112 KMd -> iptables(8) system(3) call (Policy)
113 KMd -> ip6tables(8) system(3) call (Policy)
116 char[] -s SADDR/SMASK
117 char[] -d DADDR/DMASK
118 char[] --protocol PROTO
121 char[] --uid-owner UID
122 char[] --seclev seclev
124 char[] --salist SAList
126 unsigned char exit_code
128 iptables(8) -> seclev match iptables(8) library
129 ip6tables(8) -> seclev match ip6tables(8) library
131 char[] --seclev seclevstr
135 iptables(8) -> ENCRYPT target iptables(8) library
136 ip6tables(8) -> ENCRYPT target ip6tables(8) library
138 char[] --salist SAList
140 struct ip_said SA[, ...]
142 iptables(8) -> NetFilter
143 ip6tables(8) -> NetFilter
144 I/F is already defined in NetFilter. In addition, it will
145 need structures to pass the following:
149 struct ip_said SA[, ...]
151 - add ACCEPT target for once the packet is processed
152 KMd -> iptables(8) system(3) call (Policy)
153 KMd -> ip6tables(8) system(3) call (Policy)
156 char[] -s SADDR/SMASK (local SG)
157 char[] -d DADDR/DMASK (remote SG)
159 char[] --salist SAList
163 unsigned char exit_code
165 iptables(8) -> seclev match iptables(8) library
166 ip6tables(8) -> seclev match ip6tables(8) library
168 char[] --seclev seclevstr
172 iptables(8) -> sa match iptables(8) library
173 ip6tables(8) -> sa match ip6tables(8) library
175 char[] --salist SAList
177 struct ip_said SA[, ...]
179 iptables(8) -> NetFilter
180 ip6tables(8) -> NetFilter
181 I/F is already defined in NetFilter. In addition, it will
182 need structures to pass the following:
185 struct ip_said SA[, ...]
187 - replace HOLD target with ENCRYPT target, releasing skb
188 HOLD target NetFilter kernel module -> NetFilter
189 (I don't know the best way to show this
190 on the diagram, since the skb is
191 stored with the eroute and not the HOLD
196 - send released packet through newly created ENCRYPT target and SAs
197 NetFilter -> ENCRYPT target NetFilter kernel module
200 struct ip_said SA[, ...]
202 unsigned int = NF_STOLEN
204 - fetch SAs specified in NetFilter table entry with ENCRYPT args
205 ENCRYPT target NetFilter kernel module -> SADB (SAID)
211 - send skb (packet) back into NF_IP_POST_ROUTE
212 ENCRYPT target NetFilter kernel module -> NetFilter
215 struct ip_said SA[,...]
217 - expire SA if a limit is reached
218 SADB -> KMd (PF_KEYv2 EXPIRE)
219 see RFC2367, PF_KEYv2 EXPIRE
221 Outgoing w/existing connection specifying SAs
222 - put the new SAs in place once negotiations have succeeded
223 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
224 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
226 - put in a rule to match packets for that set of SAs
227 KMd -> iptables(8) system(3) call (Policy)
228 KMd -> ip6tables(8) system(3) call (Policy)
231 char[] -s SADDR/SMASK
232 char[] -d DADDR/DMASK
233 char[] --protocol PROTO
236 char[] --uid-owner UID
237 char[] --seclev seclev
239 char[] --salist SAList
241 unsigned char exit_code
243 iptables(8) -> seclev match iptables(8) library
244 ip6tables(8) -> seclev match ip6tables(8) library
246 char[] --seclev seclevstr
250 iptables(8) -> ENCRYPT target iptables(8) library
251 ip6tables(8) -> ENCRYPT target ip6tables(8) library
253 char[] --salist SAList
255 struct ip_said SA[, ...]
257 iptables(8) -> NetFilter
258 ip6tables(8) -> NetFilter
259 I/F is already defined in NetFilter. In addition, it will
260 need structures to pass the following:
264 struct ip_said SA[, ...]
266 - add ACCEPT for once the packet is processed
267 KMd -> iptables(8) system(3) call (Policy)
268 KMd -> ip6tables(8) system(3) call (Policy)
271 char[] -s SADDR/SMASK (local SG)
272 char[] -d DADDR/DMASK (remote SG)
274 char[] --salist SAList
278 unsigned char exit_code
280 iptables(8) -> seclev match iptables(8) library
281 ip6tables(8) -> seclev match ip6tables(8) library
283 char[] --seclev seclevstr
287 iptables(8) -> sa match iptables(8) library
288 ip6tables(8) -> sa match ip6tables(8) library
290 char[] --salist SAList
292 struct ip_said SA[, ...]
294 iptables(8) -> NetFilter
295 I/F is already defined in NetFilter. In addition, it will
296 need structures to pass the following:
299 struct ip_said SA[, ...]
302 - outgoing packet is tested on selectors
303 NetFilter -> seclev match NetFilter kernel module
310 NetFilter -> sa match NetFilter kernel module
313 struct ip_said SA[,...]
317 - matching packet is sent to ENCRYPT target with SAList
318 NetFilter -> ENCRYPT target NetFilter kernel module
321 struct ip_said SA[, ...]
323 unsigned int = NF_STOLEN
325 - fetch SAs specified in NetFilter table entry with ENCRYPT args
326 ENCRYPT target NetFilter kernel module -> SADB (SAID)
332 - send skb (packet) back into NF_IP_POST_ROUTE
333 ENCRYPT target NetFilter kernel module -> NetFilter
336 struct ip_said SA[,...]
338 - outgoing processed packet is tested on selectors and ACCEPTed
339 NetFilter -> seclev match NetFilter kernel module
346 NetFilter -> sa match NetFilter kernel module
349 struct ip_said SA[,...]
353 - expire SA if a limit is reached
354 SADB -> KMd (PF_KEYv2 EXPIRE)
355 see RFC2367, PF_KEYv2 EXPIRE
357 Outgoing w/existing connection routing through IPSec device
358 - put the new SAs in place once negotiations have succeeded
359 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
360 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
362 - put in a rule to match packets for that set of SAs
363 KMd -> iptables(8) system(3) call (Policy)
364 KMd -> ip6tables(8) system(3) call (Policy)
367 char[] -s SADDR/SMASK
368 char[] -d DADDR/DMASK
369 char[] --protocol PROTO
372 char[] --uid-owner UID
373 char[] --seclev seclev
374 char[] --out-interface IPSECdev
376 char[] --salist SAList
378 unsigned char exit_code
380 iptables(8) -> seclev match iptables(8) library
381 ip6tables(8) -> seclev match ip6tables(8) library
383 char[] --seclev seclevstr
387 iptables(8) -> ENCRYPT target iptables(8) library
388 ip6tables(8) -> ENCRYPT target ip6tables(8) library
390 char[] --salist SAList
392 struct ip_said SA[, ...]
394 iptables(8) -> NetFilter
395 ip6tables(8) -> NetFilter
396 I/F is already defined in NetFilter. In addition, it will
397 need structures to pass the following:
401 struct ip_said SA[, ...]
403 KMd -> Routing Table (Routing)
404 see route(8) or iproute2(8), currently done by
405 system(3) calls to _updown.
409 unsigned char exit_code
411 - add ACCEPT for once the packet is processed
412 KMd -> iptables(8) system(3) call (Policy)
413 KMd -> ip6tables(8) system(3) call (Policy)
416 char[] -s SADDR/SMASK (local SG)
417 char[] -d DADDR/DMASK (remote SG)
420 char[] --salist SAList
423 unsigned char exit_code
425 iptables(8) -> seclev match iptables(8) library
426 ip6tables(8) -> seclev match ip6tables(8) library
428 char[] --seclev seclevstr
432 iptables(8) -> sa match iptables(8) library
433 ip6tables(8) -> sa match ip6tables(8) library
435 char[] --salist SAList
437 struct ip_said SA[, ...]
439 iptables(8) -> NetFilter
440 ip6tables(8) -> NetFilter
441 I/F is already defined in NetFilter. In addition, it will
442 need structures to pass the following:
445 struct ip_said SA[, ...]
447 - outgoing packet is tested on match modules
448 NetFilter -> seclev match NetFilter kernel module
455 NetFilter -> sa match NetFilter kernel module
458 struct ip_said SA[,...]
462 - outgoing packet matches IPSECdev and is sent to ENCRYPT target with SAList
463 NetFilter -> ENCRYPT target NetFilter kernel module
466 struct ip_said SA[, ...]
468 unsigned int = NF_STOLEN
470 - fetch SAs specified in NetFilter table entry with ENCRYPT args
471 ENCRYPT target NetFilter kernel module -> SADB (SAID)
477 - send skb (packet) back into NF_IP_POST_ROUTE
478 ENCRYPT target NetFilter kernel module -> NetFilter
481 struct ip_said SA[,...]
483 - processed packet is tested on match modules and ACCEPTed
484 NetFilter -> seclev match NetFilter kernel module
491 NetFilter -> sa match NetFilter kernel module
494 struct ip_said SA[,...]
498 - expire SA if a limit is reached
499 SADB -> KMd (PF_KEYv2 EXPIRE)
500 see RFC2367, PF_KEYv2 EXPIRE
502 Incoming w/existing connection specifying SAs
503 - put in the new SAs in place once the negotiations have succeeded
504 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
505 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
507 - put in a blocking entry to prevent unprotected packets entering
508 KMd -> iptables(8) system(3) call (Policy)
509 KMd -> ip6tables(8) system(3) call (Policy)
512 char[] -s SADDR/SMASK
513 char[] -d DADDR/DMASK
514 char[] --protocol PROTO
517 char[] --uid-owner UID
518 char[] --seclev seclev
519 char[] -J DROP (or PEEK)
521 unsigned char exit_code
523 iptables(8) -> seclev match iptables(8) library
524 ip6tables(8) -> seclev match ip6tables(8) library
526 char[] --seclev seclevstr
530 iptables(8) -> NetFilter
531 ip6tables(8) -> NetFilter
532 I/F is already defined in NetFilter. In addition, it will
533 need structures to pass the following:
536 target DROP (or PEEK)
538 - allow properly processed packets in
539 KMd -> iptables(8) system(3) call (Policy)
540 KMd -> ip6tables(8) system(3) call (Policy)
543 char[] -s SADDR/SMASK
544 char[] -d DADDR/DMASK
545 char[] --protocol PROTO
548 char[] --uid-owner UID
549 char[] --seclev seclev
550 char[] --salist SAList
553 unsigned char exit_code
555 iptables(8) -> seclev match iptables(8) library
556 ip6tables(8) -> seclev match ip6tables(8) library
558 char[] --seclev seclevstr
562 iptables(8) -> sa match iptables(8) library
563 ip6tables(8) -> sa match ip6tables(8) library
565 char[] --salist SAList
567 struct ip_said SA[, ...]
569 iptables(8) -> NetFilter
570 ip6tables(8) -> NetFilter
571 I/F is already defined in NetFilter. In addition, it will
572 need structures to pass the following:
575 struct ip_said SA[, ...]
577 - allow unprocessed packets from IPSec peer in
578 KMd -> iptables(8) system(3) call (Policy)
579 KMd -> ip6tables(8) system(3) call (Policy)
582 char[] -s SADDR/SMASK (remote SG)
583 char[] -d DADDR/DMASK (local SG)
588 unsigned char exit_code
590 iptables(8) -> seclev match iptables(8) library
591 ip6tables(8) -> seclev match ip6tables(8) library
593 char[] --seclev seclevstr
597 iptables(8) -> NetFilter
598 ip6tables(8) -> NetFilter
599 I/F is already defined in NetFilter. In addition, it will
600 need structures to pass the following:
604 - incoming packet is tested on match modules
605 NetFilter -> seclev match NetFilter kernel module
612 NetFilter -> sa match NetFilter kernel module
615 struct ip_said SA[,...]
619 - packet arrives via transport layer demux to DECRYPT
620 Transport Layer De-mux -> IPSec DECRYPT kernel module
624 - fetch SAs specified by packet in skb
625 IPSec DECRYPT kernel module -> SADB (SAID)
631 - send skb (packet) back into NF_IP_PRE_ROUTE
632 IPSec DECRYPT kernel module -> NetFilter
635 struct ip_said SA[,...]
637 - processed packet is tested on match modules and ACCEPTED
638 NetFilter -> seclev match NetFilter kernel module
645 NetFilter -> sa match NetFilter kernel module
648 struct ip_said SA[,...]
652 - expire SA if a limit is reached
653 SADB -> KMd (PF_KEYv2 EXPIRE)
654 see RFC2367, PF_KEYv2 EXPIRE
656 Incoming w/existing connection specifying IPSec device
657 - put in the new SAs in place once the negotiations have succeeded
658 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
659 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
661 - put in a blocking entry to prevent unprotected packets entering
662 KMd -> iptables(8) system(3) call (Policy)
663 KMd -> ip6tables(8) system(3) call (Policy)
666 char[] -s SADDR/SMASK
667 char[] -d DADDR/DMASK
668 char[] --protocol PROTO
671 char[] --uid-owner UID
672 char[] --seclev seclev
673 char[] -J DROP (or PEEK)
675 unsigned char exit_code
677 iptables(8) -> seclev match iptables(8) library
678 ip6tables(8) -> seclev match ip6tables(8) library
680 char[] --seclev seclevstr
684 iptables(8) -> NetFilter
685 ip6tables(8) -> NetFilter
686 I/F is already defined in NetFilter. In addition, it will
687 need structures to pass the following:
690 target DROP (or PEEK)
692 - allow properly processed packets in
693 KMd -> iptables(8) system(3) call (Policy)
694 KMd -> ip6tables(8) system(3) call (Policy)
697 char[] -s SADDR/SMASK
698 char[] -d DADDR/DMASK
699 char[] --protocol PROTO
702 char[] --uid-owner UID
703 char[] --in-interface IPSECdev
704 char[] --seclev seclev
705 char[] --salist SAList
706 (can we set an --in-interface IPSECdev
707 from this so we can just test
708 in-interface? This may need two
709 entries, including a target SETDEV)
712 unsigned char exit_code
714 iptables(8) -> seclev match iptables(8) library
715 ip6tables(8) -> seclev match ip6tables(8) library
717 char[] --seclev seclevstr
721 iptables(8) -> sa match iptables(8) library
722 ip6tables(8) -> sa match ip6tables(8) library
724 char[] --salist SAList
726 struct ip_said SA[, ...]
728 iptables(8) -> NetFilter
729 ip6tables(8) -> NetFilter
730 I/F is already defined in NetFilter. In addition, it will
731 need structures to pass the following:
734 struct ip_said SA[, ...]
736 - allow unprocessed packets from IPSec peer in
737 KMd -> iptables(8) system(3) call (Policy)
738 KMd -> ip6tables(8) system(3) call (Policy)
741 char[] -s SADDR/SMASK (remote SG)
742 char[] -d DADDR/DMASK (local SG)
747 unsigned char exit_code
749 iptables(8) -> seclev match iptables(8) library
750 ip6tables(8) -> seclev match ip6tables(8) library
752 char[] --seclev seclevstr
756 iptables(8) -> NetFilter
757 ip6tables(8) -> NetFilter
758 I/F is already defined in NetFilter. In addition, it will
759 need structures to pass the following:
763 - incoming packet is tested on match modules
764 NetFilter -> seclev match NetFilter kernel module
771 NetFilter -> sa match NetFilter kernel module
774 struct ip_said SA[,...]
778 - packet arrives via transport layer demux to DECRYPT
779 Transport Layer De-mux -> IPSec DECRYPT kernel module
783 - fetch SAs specified by packet in skb
784 IPSec DECRYPT kernel module -> SADB (SAID)
790 - send skb (packet) back into NF_IP_PRE_ROUTE
791 IPSec DECRYPT kernel module -> NetFilter
794 struct ip_said SA[,...]
796 - processed packet is tested on match modules and ACCEPTED
797 NetFilter -> seclev match NetFilter kernel module
804 NetFilter -> sa match NetFilter kernel module
807 struct ip_said SA[,...]
811 - expire SA if a limit is reached
812 SADB -> KMd (PF_KEYv2 EXPIRE)
813 see RFC2367, PF_KEYv2 EXPIRE
815 Incoming no connection
816 - set target for PEEKing at (or TRAPing) incoming packets with no connection
817 KMd -> iptables(8) system(3) call (Policy)
818 KMd -> ip6tables(8) system(3) call (Policy)
821 char[] -s SADDR/SMASK
822 char[] -d DADDR/DMASK
823 char[] --protocol PROTO
826 char[] --uid-owner UID
827 char[] --seclev seclev
828 char[] -J PEEK (or TRAP)
830 unsigned char exit_code
832 iptables(8) -> seclev match iptables(8) library
833 ip6tables(8) -> seclev match ip6tables(8) library
835 char[] --seclev seclevstr
839 iptables(8) -> NetFilter
840 ip6tables(8) -> NetFilter
841 I/F is already defined in NetFilter. In addition, it will
842 need structures to pass the following:
845 target PEEK (or TRAP)
847 - packet comes in and gets tested by match modules
848 NetFilter -> seclev match NetFilter kernel module
855 NetFilter -> sa match NetFilter kernel module
858 struct ip_said SA[,...]
862 - packet matches and gets sent to PEEK target
863 NetFilter -> PEEK (or TRAP) target NetFilter kernel module
867 unsigned int = NF_ACCEPT (or NF_STOLEN)
870 PEEK (or TRAP) target NetFilter kernel module -> KMds (PF_KEYv2 ACQUIRE)
871 see RFC2367, PF_KEYv2 ACQUIRE
873 - create ACCEPT (or HOLD) target with skb info to prevent KMd overload
874 PEEK (or HOLD) target NetFilter kernel module -> NetFilter
880 - next packet comes in while KMd is negotiating SAs.
881 NetFilter -> seclev match NetFilter kernel module
888 NetFilter -> sa match NetFilter kernel module
891 struct ip_said SA[,...]
895 - put the new SAs in place once the negotiations have succeeded
896 KMd -> SADB (PF_KEYv2 ADD/UPDATE)
897 see RFC2367, PF_KEYv2 ADD/UPDATE message for each SA
899 - put in a blocking entry to prevent unprotected packets entering
900 KMd -> iptables(8) system(3) call (Policy)
901 KMd -> ip6tables(8) system(3) call (Policy)
904 char[] -s SADDR/SMASK
905 char[] -d DADDR/DMASK
906 char[] --protocol PROTO
909 char[] --uid-owner UID
910 char[] --seclev seclev
911 char[] -J DROP (or PEEK)
913 unsigned char exit_code
915 iptables(8) -> seclev match iptables(8) library
916 ip6tables(8) -> seclev match ip6tables(8) library
918 char[] --seclev seclevstr
922 iptables(8) -> NetFilter
923 ip6tables(8) -> NetFilter
924 I/F is already defined in NetFilter. In addition, it will
925 need structures to pass the following:
930 - allow properly processed packets in
931 KMd -> iptables(8) system(3) call (Policy)
932 KMd -> ip6tables(8) system(3) call (Policy)
935 char[] -s SADDR/SMASK
936 char[] -d DADDR/DMASK
937 char[] --protocol PROTO
940 char[] --uid-owner UID
941 char[] --seclev seclev
942 char[] --salist SAList
945 unsigned char exit_code
947 iptables(8) -> seclev match iptables(8) library
948 ip6tables(8) -> seclev match ip6tables(8) library
950 char[] --seclev seclevstr
954 iptables(8) -> sa match iptables(8) library
955 ip6tables(8) -> sa match ip6tables(8) library
957 char[] --salist SAList
959 struct ip_said SA[, ...]
961 iptables(8) -> NetFilter
962 ip6tables(8) -> NetFilter
963 I/F is already defined in NetFilter. In addition, it will
964 need structures to pass the following:
967 struct ip_said SA[, ...]
969 - incoming packet is tested on match modules
970 NetFilter -> seclev match NetFilter kernel module
977 NetFilter -> sa match NetFilter kernel module
980 struct ip_said SA[,...]
984 - packet arrives via transport layer demux to DECRYPT
985 Transport Layer De-mux -> IPSec DECRYPT kernel module
989 - fetch SAs specified by packet in skb
990 IPSec DECRYPT kernel module -> SADB (SAID)
996 - send skb (packet) back into NF_IP_PRE_ROUTE
997 IPSec DECRYPT kernel module -> NetFilter
1000 struct ip_said SA[,...]
1002 - processed packet is tested on match modules and ACCEPTed
1003 NetFilter -> seclev match NetFilter kernel module
1010 NetFilter -> sa match NetFilter kernel module
1013 struct ip_said SA[,...]
1017 - expire SA if a limit is reached
1018 SADB -> KMd (PF_KEYv2 EXPIRE)
1019 see RFC2367, PF_KEYv2 EXPIRE
1023 Packet w/no route? how to get to kmd? default route to IPSECdev which calls TRAP?
1024 Nested tunnels, IKE recursion api trip
1025 how to know when to stop decapsulating nested tunnels?
1026 DHR's routing problem
1027 mutli-layer routing environments that both touch and denker need.
1028 nail down function calls and/or globals for each I/F, c-like function syntax
1029 better api block comments
1030 interface, function, args, block comment