freeswan/klips/doc/klips2-design-api.txt

   1 1#  -*- mode: Outline -*-
   2 #
   3 #  klips2-design-api.txt
   4 #       Richard Guy Briggs <rgb@conscoop.ottawa.on.ca>
   5 #
   6 #  RCSID $Id: klips2-design-api.txt,v 1.21 2001/06/26 20:29:25 rgb Exp $
   7 #
   8
   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
  12
  13         C-c C-d         Hide THIS item and subitems (subtree)
  14         C-c C-s         Show THIS item and subitems (subtree)
  15
  16         C-c C-c         Hide ONE item
  17         C-c C-e         Show ONE item
  18
  19 * Introduction
  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.
  26
  27 ** Interface:
  28         interface description, listing origin and destination
  29         entities, separated by an ">->" with diagram label, if it
  30         exists within double quotes ``"''
  31
  32 ** Label:
  33         diagram label
  34
  35 ** Name:
  36         the name of the function used and a very brief description
  37
  38 ** Synopsis:
  39         function form, argument position, type and return type
  40
  41 ** Arguments:
  42         description of each argument
  43
  44 ** Description:
  45         description of interface and function
  46
  47 ** Implementation notes:
  48         caveats and side effects
  49
  50 ** Return value:
  51         function return values
  52
  53 ** Example:
  54         usage example
  55
  56 ** See also:
  57         related documentation or further explanation
  58
  59
  60
  61 * Generic Iptables interfaces
  62
  63 ** iptables(8) >-> generic match iptables(8) library
  64 ** ip6tables(8) >-> generic match ip6tables(8) library
  65
  66         Interface:
  67
  68                 iptables(8) >-> generic match iptables(8) library
  69                 ip6tables(8) >-> generic match ip6tables(8) library
  70
  71         Label:
  72
  73         Name:
  74
  75                 (*generic_parse) - parse, convert and check generic options
  76
  77         Synopsis:
  78
  79                 static int
  80                 generic_parse(
  81                         int c,
  82                         char **argv,
  83                         int invert,
  84                         unsigned int *flags,
  85                         const struct ipt_entry *entry,
  86                         unsigned int *nfcache,
  87                         struct ipt_entry_match **match
  88                 )
  89
  90         Arguments:
  91
  92                 c
  93                         argument count
  94
  95                 argv
  96                         text arguments to be parsed by this match
  97
  98                 invert
  99                         invert this match?
 100
 101                 flags
 102                         bitmap to indicate which arguments have been processed
 103
 104                 entry
 105                         pointer to table entry associated with match
 106
 107                 nfcache
 108                         bitmap of skb parts examined by this match
 109
 110                 match
 111                         match data -- customised match data is contained in
 112                         "data" member
 113
 114         Description:
 115
 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
 119                 module.
 120
 121                 Input is expected to be in the form of a text string
 122                 specifying a "generic" characteristic associated with the
 123                 packet.
 124
 125         Implementation notes:
 126
 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.
 131
 132         Return value:
 133
 134                 1 if an option was eaten, 0 if not.
 135
 136         Example:
 137
 138                 static int
 139                 generic_parse(
 140                         int c,
 141                         char **argv,
 142                         int invert,
 143                         unsigned int *flags,
 144                         const struct ipt_entry *entry,
 145                         unsigned int *nfcache,
 146                         struct ipt_entry_match **match
 147                 ) {
 148                         struct ipt_generic_info *info = (struct ipt_generic_info*)(*match)->data;
 149
 150                         /* parse option arguments */
 151                         ...
 152                         return 1;
 153                 }
 154
 155                 struct iptables_match generic_match_lib = {
 156                         NULL,
 157                         "generic",
 158                         NETFILTER_VERSION,
 159                         IPT_ALIGN(sizeof(struct ipt_generic_info)),
 160                         IPT_ALIGN(sizeof(struct ipt_generic_info)),
 161                         &generic_help,
 162                         &generic_init,
 163                         &generic_parse,
 164                         &generic_final_check,
 165                         &generic_print,
 166                         &generic_save,
 167                         generic_opts
 168                 };
 169
 170                 void
 171                 _init(void)
 172                 {
 173                         register_match(&generic_match_lib);
 174                 }
 175
 176         See also:
 177
 178
 179
 180 ** iptables(8) >-> GENERIC target iptables(8) library
 181 ** ip6tables(8) >-> GENERIC target ip6tables(8) library
 182
 183         Interface:
 184
 185                 iptables(8) >-> GENERIC target iptables(8) library
 186                 ip6tables(8) >-> GENERIC target ip6tables(8) library
 187
 188         Label:
 189
 190         Name:
 191
 192         Synopsis:
 193
 194                 static int generic_parse(
 195                         int c,
 196                         char **argv,
 197                         int invert,
 198                         unsigned int *flags,
 199                         const struct ipt_entry *entry,
 200                         struct ipt_entry_target **target
 201                 )
 202
 203         Arguments:
 204
 205                 c
 206                         argument count
 207
 208                 argv
 209                         text arguments to be parsed by this target
 210
 211                 invert
 212                         invert flag (doesn't make sense for targets)
 213
 214                 flags
 215                         bitmap to indicate which arguments have been processed
 216
 217                 entry
 218                         pointer to table entry associated with target
 219
 220                 target
 221                         target data -- customised target data is contained in
 222                         "data" member
 223
 224         Description:
 225
 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
 229                 module.
 230
 231                 Input is expected to be in the form of a text string
 232                 specifying a "generic" characteristic to be applied to the
 233                 packet.
 234
 235         Implementation notes:
 236
 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.
 242
 243         Return value:
 244
 245                 1 if an option was eaten, 0 if not.
 246
 247         Example:
 248
 249                 static int
 250                 generic_parse(
 251                         int c,
 252                         char **argv,
 253                         int invert,
 254                         unsigned int *flags,
 255                         const struct ipt_entry *entry,
 256                         struct ipt_entry_target **target
 257                 ) {
 258                         struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)(*target)->data;
 259
 260                         /* parse option arguments */
 261                         ...
 262                         return 1;
 263                 }
 264
 265                 struct iptables_target generic_target_lib = {
 266                         NULL,
 267                         "GENERIC",
 268                         NETFILTER_VERSION,
 269                         IPT_ALIGN(sizeof(struct ipt_generic_target_info)),
 270                         IPT_ALIGN(sizeof(struct ipt_generic_target_info)),
 271                         &generic_help,
 272                         &generic_init,
 273                         &generic_parse,
 274                         &generic_final_check,
 275                         &generic_print,
 276                         &generic_save,
 277                         generic_opts
 278                 };
 279
 280                 void
 281                 _init(void)
 282                 {
 283                         register_target(&generic_target_lib);
 284                 }
 285
 286         See also:
 287
 288                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 289
 290
 291
 292 ** NetFilter >-> generic match NetFilter kernel module
 293
 294         Interface:
 295
 296                 NetFilter >-> generic match NetFilter kernel module
 297
 298         Label:
 299
 300         Name:
 301
 302                 (*generic_match) - does the packet match the generic
 303                 specifications?
 304
 305         Synopsis:
 306
 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,
 312                         int offset,
 313                         const void *hdr,
 314                         u_int16_t datalen,
 315                         int *hotdrop
 316                 )
 317
 318         Arguments:
 319
 320                 skb
 321                         skb to test for match
 322
 323                 in
 324                         incoming network interface
 325
 326                 out
 327                         outgoing network interface
 328
 329                 matchinfo
 330                         match information
 331
 332                 offset
 333                         packet offset
 334
 335                 hdr
 336                         transport layer header pointer
 337
 338                 datalen
 339                         length of skb
 340
 341                 hotdrop
 342                         flag to immediately drop packet
 343
 344         Description:
 345
 346                 This function checks if the skb supplied matches
 347                 the generic packet characteristics specified in
 348                 matchinfo.
 349
 350         Implementation notes:
 351
 352                 Replace ipt_generic_info with the customised data
 353                 structure.
 354
 355         Return value:
 356
 357                 It returns true (1) for match, false (0) for no match.
 358
 359         Example:
 360
 361                 static int
 362                 generic_match(
 363                         const struct sk_buff *skb,
 364                         const struct net_device *in,
 365                         const struct net_device *out,
 366                         const void *matchinfo,
 367                         int offset,
 368                         const void *hdr,
 369                         u_int16_t datalen,
 370                         int *hotdrop
 371                 ) {
 372                         struct ipt_generic_info *info = (struct ipt_generic_info*)matchinfo;
 373
 374                         if(/* test skb for match to matchinfo data */) {
 375                                 return 1;
 376                         }
 377                         return 0;
 378                 }
 379
 380                 static struct ipt_match generic_match_mod = {
 381                         { NULL, NULL },
 382                         "generic",
 383                         &generic_match,
 384                         &generic_checkentry,
 385                         NULL,
 386                         THIS_MODULE
 387                 };
 388
 389                 static int __init
 390                 init(void)
 391                 {
 392                         return ipt_register_match(&generic_match_mod);
 393                 }
 394
 395                 static void __exit
 396                 fini(void)
 397                 {
 398                         ipt_unregister_match(&generic_match_mod);
 399                 }
 400
 401         See also:
 402
 403                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 404
 405
 406
 407 ** NetFilter >-> GENERIC target NetFilter kernel module
 408
 409         Interface:
 410
 411                 NetFilter >-> GENERIC target NetFilter kernel module
 412
 413         Label:
 414
 415         Name:
 416
 417                 (*generic_target) - process outgoing packet with
 418                 "generic" information supplied
 419
 420         Synopsis:
 421
 422                 static unsigned int
 423                 generic_target(
 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,
 429                         void *userinfo
 430                 )
 431
 432         Arguments:
 433
 434                 pskb
 435                         skb to be processed by target
 436
 437                 hooknum
 438                         which hook from which it was called
 439
 440                 in
 441                         network device it came from
 442
 443                 out
 444                         network device to which it is headed
 445
 446                 targinfo
 447                         data used by target for processing
 448
 449                 userinfo
 450                         optional user data passed in from mainline
 451                         hook
 452
 453         Description:
 454
 455                 This is a NetFilter target.  It applies the generic
 456                 information supplied with the target to the outgoing
 457                 packet.
 458
 459         Implementation notes:
 460
 461                 Replace ipt_generic_target_info with the customised data
 462                 structure, if there is one.
 463
 464         Return value:
 465
 466                It returns <verdict>.
 467
 468         Example:
 469
 470                 File net/ipv4/netfilter/ipt_GENERIC.c:
 471                 #include <linux/netfilter_ipv4/ip_tables.h>
 472
 473                 static unsigned int
 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,
 479                         void *userinfo)
 480                 {
 481                         struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)targinfo;
 482                         /* do target processing */
 483                         return <verdict>;
 484                 }
 485
 486                 static struct ipt_target generic_target_mod = {
 487                         { NULL, NULL },
 488                         "GENERIC",
 489                         generic_target,
 490                         generic_checkentry,
 491                         NULL,
 492                         THIS_MODULE
 493                 };
 494
 495                 static int __init init(void)
 496                 {
 497                         if (ipt_register_target(&generic_target_mod))
 498                                 return -EINVAL;
 499                         return 0;
 500                 }
 501
 502                 static void __exit fini(void)
 503                 {
 504                         ipt_unregister_target(&generic_target_mod);
 505                 }
 506
 507         See also:
 508
 509                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 510
 511
 512
 513 * KLIPS2 Interfaces
 514
 515 ** KMd >-> iptables(8) "Policy"
 516 ** KMd >-> ip6tables(8) "Policy"
 517
 518         Interface:
 519
 520                 KMd >-> iptables(8)
 521                 KMd >-> ip6tables(8)
 522
 523         Label:
 524
 525                 "Policy"
 526
 527         Name:
 528
 529                 system(3) call to iptables(8) - execute a shell
 530                 command to do IP packet filter administration to set
 531                 ipsec policy
 532
 533         Synopsis:
 534
 535                 #include <stdlib.h>
 536
 537                 int system(const char * "iptables \
 538                         --table ipsec \
 539                         --new-table chain ");
 540                 int system(const char * "iptables \
 541                         --table ipsec \
 542                         --policy chain target");
 543                 int system(const char * "iptables \
 544                         --table ipsec \
 545                         --{append,delete,insert,replace} chain \
 546                         --protocol protocol \
 547                         --source src \
 548                         --destination dst \
 549                         --jump target \
 550                         --in-interface IPSECdev \
 551                         --out-interface IPSECdev \
 552                         --source-port SPORT \
 553                         --destination-port DPORT \
 554                         --uid-owner UID \
 555                         --gid-owner GID \
 556                         --pid-owner PID \
 557                         --sid-owner SID \
 558                         --espspi SPI \
 559                         --seclev seclevstr \
 560                         --salist SAList \
 561                 ");
 562
 563         Arguments:
 564
 565                 --table ipsec
 566                         specify ipsec SPDB NetFilter kernel table
 567
 568                 --new-chain chain
 569                         create new chain in ipsec SPDB
 570
 571                 --policy chain target
 572                         set default target for specified chain
 573
 574                 --{append,delete,insert,replace} chain
 575                         manipulate a rule in the specified chain
 576
 577                 --protocol protocol
 578                         protocol for the matching rule
 579
 580                 --source src
 581                         source address for the matching rule
 582
 583                 --destination dst
 584                         destination address for the matching rule
 585
 586                 --in-interface IPSECdev
 587                         incoming ipsec device for the matching rule
 588
 589                 --out-interface IPSECdev
 590                         outgoing ipsec device for the matching rule
 591
 592                 --source-port SPORT
 593                         source port for the matching rule (tcp or udp)
 594
 595                 --destination-port DPORT
 596                         destination port for the matching rule (tcp or udp)
 597
 598                 --uid-owner UID
 599                         user ID for the matching rule
 600
 601                 --espspi SPI
 602                         Encapsulation Security Payload Security Parameters
 603                         Index for the matching rule
 604
 605                 --seclev seclevstr
 606                         security or sensitivity level or label for the
 607                         matching rule
 608
 609                 --salist SAList
 610                         Security Association IDentifier list for the matching
 611                         rule
 612
 613                 --jump target
 614                         target for a matching packet
 615
 616         Description:
 617
 618                 This is the SPDB (or as yet undefined PF_POLICY)
 619                 interface from the key management daemons to the
 620                 kernel via netfilter.
 621
 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.
 626
 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.
 635
 636                 Rules are appended, inserted, deleted or replaced to
 637                 set the IPSec policy.
 638
 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
 647                 --jump option.
 648
 649         Implementation notes:
 650
 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.)
 655
 656                 An alternative may be to have the KMd link directly
 657                 with iptables.o rather than invoking system(3) to call
 658                 iptables(8).
 659
 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.
 666
 667         Return value:
 668
 669                 system(3) returns:
 670                 The value returned is 127 if the execve() call for
 671                 /bin/sh fails, -1 if there was another error.
 672
 673                 iptables(8) returns:
 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.
 679
 680         Example:
 681
 682                 #include <stdlib.h>
 683                 int return;
 684
 685                 ...
 686
 687                 if((return = system("iptables \
 688                         --table ipsec \
 689                         --insert out \
 690                         --source this-subnet.example.com \
 691                         --destination that-subnet.example.com \
 692                         --jump IPSEC \
 693                         --use-salist esp.12345678@that-sg.example.com \
 694                         "))){
 695                         fprintf(stderr, "error $d calling iptables\n");
 696                         exit 1;
 697                 }
 698
 699         See also:
 700
 701                 system(3), iptables(8)
 702
 703
 704
 705 ** iptables(8) >-> seclev match iptables(8) library
 706 ** ip6tables(8) >-> seclev match ip6tables(8) library
 707
 708         Interface:
 709
 710                 iptables(8) >-> seclev match iptables(8) library
 711                 ip6tables(8) >-> seclev match ip6tables(8) library
 712
 713         Label:
 714
 715         Name:
 716
 717                 (*seclev_parse) - parse, convert and check security level options
 718
 719         Synopsis:
 720
 721                 see: iptables(8) >-> generic match iptables(8) library
 722
 723         Arguments:
 724
 725                 see: iptables(8) >-> generic match iptables(8) library
 726
 727         Description:
 728
 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
 732                 module.
 733
 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
 737                 packet.
 738
 739         Implementation notes:
 740
 741                 I don't actually what form security level data takes,
 742                 but that can be sorted out later.
 743
 744                 Use the data structure ipt_seclev_info.
 745
 746         Return value:
 747
 748                 see: iptables(8) >-> generic match iptables(8) library
 749
 750         Example:
 751
 752                 see: iptables(8) >-> generic match iptables(8) library
 753
 754         See also:
 755
 756                 iptables(8) >-> generic match iptables(8) library
 757
 758
 759
 760 ** iptables(8) >-> salist match iptables(8) library
 761 ** ip6tables(8) >-> salist match ip6tables(8) library
 762
 763         Interface:
 764
 765                 iptables(8) >-> salist match iptables(8) library
 766                 ip6tables(8) >-> salist match ip6tables(8) library
 767
 768         Label:
 769
 770         Name:
 771
 772                 (*salist_parse) - parse, convert and check security
 773                 association list options
 774
 775         Synopsis:
 776
 777                 see: iptables(8) >-> generic match iptables(8) library
 778
 779         Arguments:
 780
 781                 see: iptables(8) >-> generic match iptables(8) library
 782
 783         Description:
 784
 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.
 789
 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.
 793
 794         Implementation notes:
 795
 796                 Use the data structure ipt_salist_info.
 797
 798         Return value:
 799
 800                 see: iptables(8) >-> generic match iptables(8) library
 801
 802         Example:
 803
 804                 see: iptables(8) >-> generic match iptables(8) library
 805
 806         See also:
 807
 808                 iptables(8) >-> generic match iptables(8) library
 809                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 810
 811
 812
 813 ** iptables(8) >-> TRAP target iptables(8) library
 814 ** ip6tables(8) >-> TRAP target ip6tables(8) library
 815
 816         Interface:
 817
 818                 iptables(8) >-> TRAP target iptables(8) library
 819                 ip6tables(8) >-> TRAP target ip6tables(8) library
 820
 821         Label:
 822
 823         Name:
 824
 825                 (*trap_parse) - parse, convert and check TRAP options
 826
 827         Synopsis:
 828
 829                 see: iptables(8) >-> GENERIC target iptables(8) library
 830
 831         Arguments:
 832
 833                 see: iptables(8) >-> GENERIC target iptables(8) library
 834
 835         Description:
 836
 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
 840                 module.
 841
 842                 No input is expected.
 843
 844         Implementation notes:
 845
 846         Return value:
 847
 848                 see: iptables(8) >-> GENERIC target iptables(8) library
 849
 850         Example:
 851
 852                 see: iptables(8) >-> GENERIC target iptables(8) library
 853
 854         See also:
 855
 856                 iptables(8) >-> GENERIC target iptables(8) library
 857                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 858
 859
 860
 861 ** iptables(8) >-> HOLD target iptables(8) library
 862 ** ip6tables(8) >-> HOLD target ip6tables(8) library
 863
 864         Interface:
 865
 866                 iptables(8) >-> HOLD target iptables(8) library
 867                 ip6tables(8) >-> HOLD target ip6tables(8) library
 868
 869         Label:
 870
 871         Name:
 872
 873         Synopsis:
 874
 875                 see: iptables(8) >-> GENERIC target iptables(8) library
 876
 877         Arguments:
 878
 879                 see: iptables(8) >-> GENERIC target iptables(8) library
 880
 881         Description:
 882
 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
 886                 module.
 887
 888                 No input is expected.
 889
 890         Implementation notes:
 891
 892         Return value:
 893
 894                 see: iptables(8) >-> GENERIC target iptables(8) library
 895
 896         Example:
 897
 898                 see: iptables(8) >-> GENERIC target iptables(8) library
 899
 900         See also:
 901
 902                 iptables(8) >-> GENERIC target iptables(8) library
 903                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 904
 905
 906
 907 ** iptables(8) >-> PEEK target iptables(8) library
 908 ** ip6tables(8) >-> PEEK target ip6tables(8) library
 909
 910         Interface:
 911
 912                 iptables(8) >-> PEEK target iptables(8) library
 913                 ip6tables(8) >-> PEEK target ip6tables(8) library
 914
 915         Label:
 916
 917         Name:
 918
 919         Synopsis:
 920
 921                 see: iptables(8) >-> GENERIC target iptables(8) library
 922
 923         Arguments:
 924
 925                 see: iptables(8) >-> GENERIC target iptables(8) library
 926
 927         Description:
 928
 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
 932                 module.
 933
 934                 No input is expected.
 935
 936         Implementation notes:
 937
 938         Return value:
 939
 940                 see: iptables(8) >-> GENERIC target iptables(8) library
 941
 942         Example:
 943
 944                 see: iptables(8) >-> GENERIC target iptables(8) library
 945
 946         See also:
 947
 948                 iptables(8) >-> GENERIC target iptables(8) library
 949                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 950
 951
 952
 953 ** iptables(8) >-> IPSEC target iptables(8) library
 954 ** ip6tables(8) >-> IPSEC target ip6tables(8) library
 955
 956         Interface:
 957
 958                 iptables(8) >-> IPSEC target iptables(8) library
 959                 ip6tables(8) >-> IPSEC target ip6tables(8) library
 960
 961         Label:
 962
 963         Name:
 964
 965         Synopsis:
 966
 967                 see: iptables(8) >-> GENERIC target iptables(8) library
 968
 969         Arguments:
 970
 971                 see: iptables(8) >-> GENERIC target iptables(8) library
 972
 973         Description:
 974
 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.
 978
 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.
 982
 983         Implementation notes:
 984
 985                 Use the data structure ipt_ipsec_target_info.
 986
 987         Return value:
 988
 989                 see: iptables(8) >-> GENERIC target iptables(8) library
 990
 991         Example:
 992
 993                 see: iptables(8) >-> GENERIC target iptables(8) library
 994
 995         See also:
 996
 997                 iptables(8) >-> GENERIC target iptables(8) library
 998                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
 999
1000
1001
1002 ** iptables(8) >-> NetFilter
1003 ** ip6tables(8) >-> NetFilter
1004
1005         Interface:
1006
1007                 iptables(8) >-> NetFilter
1008                 ip6tables(8) >-> NetFilter
1009
1010         Label:
1011
1012         Name:
1013
1014         Synopsis:
1015
1016         Arguments:
1017
1018                 match->data = struct ipt_seclev_info
1019                 match->data = struct ipt_salist_info
1020                 target->data = struct ipt_ipsec_target_info
1021
1022         Description:
1023
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.
1029
1030         Implementation notes:
1031
1032         Return value:
1033
1034         Example:
1035
1036         See also:
1037
1038                 iptables-1.2.2/libiptc/
1039
1040
1041
1042 ** NetFilter >-> seclev match NetFilter kernel module
1043
1044         Interface:
1045
1046                 NetFilter >-> seclev match NetFilter kernel module
1047
1048         Label:
1049
1050         Name:
1051
1052                 (*seclev_match) - does the packet match Security
1053                 Level?
1054
1055         Synopsis:
1056
1057                 see: NetFilter >-> generic match NetFilter kernel module
1058
1059         Arguments:
1060
1061                 see: NetFilter >-> generic match NetFilter kernel module
1062
1063         Description:
1064
1065                 This function checks if the skb supplied matches
1066                 the security level specified in matchinfo.
1067
1068         Implementation notes:
1069
1070                 Use the data structure ipt_seclev_info.
1071
1072         Return value:
1073
1074                 see: NetFilter >-> generic match NetFilter kernel module
1075
1076         Example:
1077
1078                 see: NetFilter >-> generic match NetFilter kernel module
1079
1080         See also:
1081
1082                 NetFilter >-> seclev match NetFilter kernel module
1083                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1084
1085
1086
1087 ** NetFilter >-> salist match NetFilter kernel module
1088
1089         Interface:
1090
1091                 NetFilter >-> salist match NetFilter kernel module
1092
1093         Label:
1094
1095         Name:
1096
1097                 (*salist_match) - does the packet match the Security
1098                 Association List?
1099
1100         Synopsis:
1101
1102                 see: NetFilter >-> generic match NetFilter kernel module
1103
1104         Arguments:
1105
1106                 see: NetFilter >-> generic match NetFilter kernel module
1107
1108         Description:
1109
1110                 This function checks if the skb supplied matches
1111                 the Security Association list specified in matchinfo.
1112
1113         Implementation notes:
1114
1115                 Use the data structure ipt_salist_info.
1116
1117         Return value:
1118
1119                 see: NetFilter >-> generic match NetFilter kernel module
1120
1121         Example:
1122
1123                 see: NetFilter >-> generic match NetFilter kernel module
1124
1125         See also:
1126
1127                 NetFilter >-> generic match NetFilter kernel module
1128                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1129
1130
1131
1132 ** NetFilter >-> TRAP target NetFilter kernel module
1133
1134         Interface:
1135
1136                 NetFilter >-> TRAP target NetFilter kernel module
1137
1138         Label:
1139
1140                 TRAP
1141
1142         Name:
1143
1144                 (*trap_target) - TRAP outgoing packets to initiate
1145                 opportunism
1146
1147         Synopsis:
1148
1149                 see: NetFilter >-> GENERIC target NetFilter kernel module
1150
1151         Arguments:
1152
1153                 see: NetFilter >-> GENERIC target NetFilter kernel module
1154
1155         Description:
1156
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.
1161
1162         Implementation notes:
1163
1164         Return value:
1165
1166                 It returns NF_STOLEN.
1167
1168         Example:
1169
1170                 see: NetFilter >-> GENERIC target NetFilter kernel module
1171
1172         See also:
1173
1174                 NetFilter >-> GENERIC target NetFilter kernel module
1175                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1176
1177
1178
1179 ** TRAP target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1180
1181         Interface:
1182
1183                 TRAP target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1184
1185         Label:
1186
1187                 see RFC2367, PF_KEYv2 ACQUIRE
1188
1189         Name:
1190
1191                 see RFC2367, PF_KEYv2 ACQUIRE
1192
1193         Synopsis:
1194
1195                 see RFC2367, PF_KEYv2 ACQUIRE
1196
1197         Arguments:
1198
1199                 see RFC2367, PF_KEYv2 ACQUIRE
1200
1201         Description:
1202
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
1206                 remote host.
1207
1208         Implementation notes:
1209
1210         Return value:
1211
1212                 see RFC2367, PF_KEYv2 ACQUIRE
1213
1214         Example:
1215
1216         See also:
1217
1218
1219
1220 ** TRAP target NetFilter kernel module >-> NetFilter
1221
1222         Interface:
1223
1224                 TRAP target NetFilter kernel module >-> NetFilter
1225
1226         Label:
1227
1228         Name:
1229
1230         Synopsis:
1231
1232         Arguments:
1233
1234                 struct sk_buff *skb
1235
1236         Description:
1237
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.
1242
1243         Implementation notes:
1244
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.
1248
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.
1254
1255                 There is talk about iptables being rewritten so that
1256                 the table is updated more gracefully.
1257
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.
1261
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.
1265
1266                 After the HOLD is in place, the packet would be
1267                 re-injected.
1268
1269         Return value:
1270
1271         Example:
1272
1273         See also:
1274
1275
1276
1277 ** NetFilter >-> HOLD target NetFilter kernel module
1278
1279         Interface:
1280
1281                 NetFilter >-> HOLD target NetFilter kernel module
1282
1283         Label:
1284
1285         Name:
1286
1287                 (*hold_target) - HOLD packets to prevent key
1288                 management daemon flooding
1289
1290         Synopsis:
1291
1292                 see: NetFilter >-> GENERIC target NetFilter kernel module
1293
1294         Arguments:
1295
1296                 see: NetFilter >-> GENERIC target NetFilter kernel module
1297
1298         Description:
1299
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.
1304
1305         Implementation notes:
1306
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
1310                 will be lost.
1311
1312         Return value:
1313
1314                 It returns NF_STOLEN.
1315
1316         Example:
1317
1318                 see: NetFilter >-> GENERIC target NetFilter kernel module
1319
1320         See also:
1321
1322                 NetFilter >-> GENERIC target NetFilter kernel module
1323                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1324
1325
1326
1327 ** KMd >-> SADB "PF_KEYv2 ADD/UPDATE"
1328
1329         Interface:
1330
1331                 KMd >-> SADB "PF_KEYv2 ADD/UPDATE"
1332
1333         Label:
1334
1335                 see RFC2367, PF_KEYv2 ADD/UPDATE
1336
1337         Name:
1338
1339                 see RFC2367, PF_KEYv2 ADD/UPDATE
1340
1341         Synopsis:
1342
1343                 see RFC2367, PF_KEYv2 ADD/UPDATE
1344
1345         Arguments:
1346
1347                 see RFC2367, PF_KEYv2 ADD/UPDATE
1348
1349         Description:
1350
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.
1354
1355         Implementation notes:
1356
1357         Return value:
1358
1359                 see RFC2367, PF_KEYv2 ADD/UPDATE
1360
1361         Example:
1362
1363         See also:
1364
1365
1366
1367 ** HOLD target NetFilter kernel module >-> NetFilter
1368
1369         Interface:
1370
1371                 HOLD target NetFilter kernel module >-> NetFilter
1372
1373         Label:
1374
1375         Name:
1376
1377                 ip_finish_output - re-submit the packet to the output
1378                 queue, now that the HOLD has been cleared.
1379
1380                 NF_HOOK(PF_INET, NF_IP_POST_ROUTING, skb, NULL, rt->u.dst.dev, ip_finish_output2);
1381
1382         Synopsis:
1383
1384                 int
1385                 ip_finish_output(
1386                         struct sk_buff *skb
1387                 )
1388
1389         Arguments:
1390
1391                 skb
1392                         packet to be re-submitted
1393
1394         Description:
1395
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.
1401
1402                 The packet is re-submitted just before
1403                 NF_IP_POST_ROUTING.
1404
1405         Implementation notes:
1406
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.
1412
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.
1417
1418         Return value:
1419
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.
1425
1426         Example:
1427
1428                 ip_finish_output(skb);
1429
1430         See also:
1431
1432
1433
1434 ** NetFilter >-> IPSEC target NetFilter kernel module
1435
1436         Interface:
1437
1438                 NetFilter >-> IPSEC target NetFilter kernel module
1439
1440         Label:
1441
1442         Name:
1443
1444                 (*ipsec_target) - process outgoing packet with
1445                 specified Security Associations
1446
1447         Synopsis:
1448
1449                 see: NetFilter >-> GENERIC target NetFilter kernel module
1450
1451         Arguments:
1452
1453                 see: NetFilter >-> GENERIC target NetFilter kernel module
1454
1455         Description:
1456
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.
1461
1462         Implementation notes:
1463
1464                 Use the data structure ipt_ipsec_target_info.
1465
1466         Return value:
1467
1468                It returns NF_STOLEN.
1469
1470         Example:
1471
1472                 see: NetFilter >-> GENERIC target NetFilter kernel module
1473
1474         See also:
1475
1476                 NetFilter >-> GENERIC target NetFilter kernel module
1477                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1478
1479
1480
1481 ** IPSEC target NetFilter kernel module >-> SADB "SAID"
1482
1483         Interface:
1484
1485                 IPSEC target NetFilter kernel module >-> SADB
1486
1487         Label:
1488
1489                 SAID
1490
1491         Name:
1492
1493                 ipsec_getsa - get an SA from the SADB by SAID
1494
1495         Synopsis:
1496
1497                 #include <ipsec_sadb.h>
1498
1499                 struct ipsec_sa *
1500                 ipsec_getsa(
1501                         struct ipsec_said asaid
1502                 );
1503
1504         Arguments:
1505
1506                 asaid
1507                         Security Association IDentifier to try to
1508                         match in SADB
1509
1510
1511         Description:
1512
1513                 Retrieve a Security Association from the system
1514                 Security Association DataBase that matches the
1515                 supplied Security Association IDentifier.
1516
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.
1523
1524         Implementation notes:
1525
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.
1530
1531                 The global SADB hash table struct
1532                 ipsec_sa*ipsec_sadb[] is locked by ipsec_getsa()
1533                 during lookup.
1534
1535         Return values:
1536
1537                 A pointer to a valid Security Association is returned
1538                 if a match was found, otherwise NULL is returned.
1539
1540         Example:
1541
1542                 struct ipsec_sa *sa;
1543                 struct ipsec_said said;
1544                 ...
1545                 sa = ipsec_getsa(said);
1546                 ...
1547                 if(atomic_dec_and_test(sa->refcount)) {
1548                         ipsec_sa_free(sa);
1549                 }
1550
1551         See also:
1552
1553
1554
1555 ** IPSEC target NetFilter kernel module >-> NetFilter
1556
1557         Interface:
1558
1559                 IPSEC target NetFilter kernel module >-> NetFilter
1560
1561         Label:
1562
1563         Name:
1564
1565                 ip_queue_xmit - re-submit the packet to the output
1566                 queue, now that the packet has been IPSec pocessed.
1567
1568                 NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_queue_xmit2);
1569
1570                 NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_send);
1571
1572         Synopsis:
1573
1574                 int
1575                 ip_queue_xmit(
1576                         struct sk_buff *skb
1577                 )
1578
1579         Arguments:
1580
1581                 skb
1582                         socket buffer to be sent
1583
1584         Description:
1585
1586                 This interface is to re-inject packets before
1587                 NF_IP_LOCAL_OUT after the packet has been processed.
1588
1589         Implementation notes:
1590
1591                 int ip_queue_xmit(struct sk_buff *skb) is another possibility...
1592
1593         Return value:
1594
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.
1601
1602         Example:
1603
1604                 struct salist SAs;
1605                 ...
1606
1607                 skb->salist = SAs;
1608                 ip_queue_xmit(skb);
1609
1610         See also:
1611
1612                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1613
1614
1615
1616 ** SADB >-> KMd "PF_KEYv2 EXPIRE"
1617
1618         Interface:
1619
1620                 SADB >-> KMd "PF_KEYv2 EXPIRE"
1621
1622         Label:
1623
1624                 see RFC2367, PF_KEYv2 EXPIRE
1625
1626         Name:
1627
1628                 see RFC2367, PF_KEYv2 EXPIRE
1629
1630         Synopsis:
1631
1632                 see RFC2367, PF_KEYv2 EXPIRE
1633
1634         Arguments:
1635
1636                 see RFC2367, PF_KEYv2 EXPIRE
1637
1638         Description:
1639
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
1643                 replacement.
1644
1645         Implementation notes:
1646
1647         Return value:
1648
1649                 see RFC2367, PF_KEYv2 EXPIRE
1650
1651         Example:
1652
1653         See also:
1654
1655
1656 ** Routing Table >-> IPSEC target NetFilter kernel module "IPSECdev"
1657
1658         Interface:
1659
1660                 Routing Table >-> IPSEC target NetFilter kernel module
1661
1662         Label:
1663
1664                  "IPSECdev"
1665
1666         Name:
1667
1668         Synopsis:
1669
1670         Arguments:
1671
1672         Description:
1673
1674                 This interface provides a way of routing packets
1675                 through a specific IPSec virtual tunnel.  This is
1676                 standard linux network routing.
1677
1678         Implementation notes:
1679
1680         Return value:
1681
1682         Example:
1683
1684         See also:
1685
1686
1687
1688 ** KMd >-> Routing Table "Routing"
1689
1690         Interface:
1691
1692                 KMd >-> Routing Table
1693
1694         Label:
1695
1696                 "Routing"
1697
1698         Name:
1699
1700                 system(3) call to route(8) - execute a shell
1701                 command to do IP packet routing administration to set
1702                 ipsec policy
1703
1704         Synopsis:
1705
1706                 #include <stdlib.h>
1707
1708                 int
1709                 system(
1710                         const char * "route \
1711                         {add,del} -{host,net} \
1712                         {<host>,<net>[/mask]} \
1713                         gw <gateway> \
1714                         dev <device> \
1715                 ");
1716
1717         Arguments:
1718
1719                 add
1720                         add an entry to the routing table
1721
1722                 del
1723                         delete an entry from the routing table
1724
1725                 -host
1726                         add or delete a host
1727
1728                 -net
1729                         add or delete a network
1730
1731                 <host>
1732                         host FQDN or IPv4 or IPv6 address
1733
1734                 <net>[/mask]
1735                         network FQDN or IPv4 or IPv6 address with netmask
1736
1737                 gw <gateway>
1738                         nexthop gateway address
1739
1740                 dev <device>
1741
1742                 char[] IPSECdev
1743                 unsigned char exit_code
1744
1745         Description:
1746
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.
1751
1752         Implementation notes:
1753
1754                 currently done by system(3) calls to _updown.
1755
1756         Return value:
1757
1758         Example:
1759
1760         See also:
1761
1762                 system(3), route(8), iproute2(8)
1763
1764
1765
1766 ** Transport Layer De-mux >-> IPSec DECRYPT kernel module
1767
1768         Interface:
1769
1770                 Transport Layer De-mux >-> IPSec DECRYPT kernel module
1771
1772         Label:
1773
1774         Name:
1775
1776                 ipsec_rcv - process an incoming IPSec packet
1777         Synopsis:
1778
1779                 #include <ipsec_rcv.h>
1780
1781                 int
1782                 ipsec_rcv(
1783                         struct sk_buff *skb,
1784                         unsigned short xlen
1785                 )
1786
1787         Arguments:
1788
1789                 skb
1790                         skb to be processed
1791
1792                 xlen
1793                         length of skb buffer
1794
1795         Description:
1796
1797                 This interface is to call the IPSEC ESP transport
1798                 layer protocol handler to process (decrypt) an
1799                 incoming packet.
1800
1801                 The packet is freed, being re-injected before the
1802                 NF_IP_PRE_ROUTING hook.
1803
1804         Implementation notes:
1805
1806         Return value:
1807
1808                ipsec_rcv() returns zero (0).
1809
1810         Example:
1811
1812         See also:
1813
1814
1815
1816 ** IPSec DECRYPT kernel module >-> SADB "SAID"
1817
1818         Interface:
1819
1820                 IPSec DECRYPT kernel module >-> SADB
1821
1822         Label:
1823
1824                 see "SAID"
1825
1826         Name:
1827
1828                 ipsec_getsa - get an SA from the SADB by SAID
1829
1830         Synopsis:
1831
1832                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1833
1834         Arguments:
1835
1836                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1837
1838         Description:
1839
1840                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1841
1842         Implementation notes:
1843
1844                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1845
1846         Return value:
1847
1848                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1849
1850         Example:
1851
1852                 see: IPSEC target NetFilter kernel module >-> SADB "SAID"
1853
1854         See also:
1855
1856                 IPSEC target NetFilter kernel module >-> SADB "SAID"
1857
1858
1859 ** IPSec DECRYPT kernel module >-> NetFilter
1860
1861         Interface:
1862
1863                 IPSec DECRYPT kernel module >-> NetFilter
1864
1865         Label:
1866
1867         Name:
1868
1869                 int netif_rx(struct sk_buff *skb) - post  buffer to the network code, always succeeds
1870
1871                 ip_rcv - receive an IP packet for input processing
1872
1873                 NF_HOOK(PF_INET, NF_IP_PRE_ROUTING, skb, dev, NULL, ip_rcv_finish);
1874
1875         Synopsis:
1876
1877                 int
1878                 ip_rcv(
1879                         struct sk_buff *skb,
1880                         struct net_device *dev,
1881                         struct packet_type *pt
1882                 )
1883
1884         Arguments:
1885
1886                 skb
1887                         packet to be re-injected
1888
1889                 dev
1890                         incoming device, virtual if there is one.
1891
1892                 pt
1893                         packet type (not used)
1894
1895
1896         Description:
1897
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.
1903
1904         Implementation notes:
1905
1906         Return value:
1907
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.
1913
1914         Example:
1915
1916                 struct salist SAs;
1917                 ...
1918
1919                 skb->salist = SAs;
1920                 ip_rcv(skb, skb->dev, NULL)
1921
1922         See also:
1923
1924
1925
1926 ** NetFilter >-> PEEK target NetFilter kernel module
1927
1928         Interface:
1929
1930                 NetFilter >-> PEEK target NetFilter kernel module
1931
1932         Label:
1933
1934         Name:
1935
1936                 (*peek_target) - PEEK at packets to initiate opportunism
1937
1938         Synopsis:
1939
1940                 see: NetFilter >-> GENERIC target NetFilter kernel module
1941
1942         Arguments:
1943
1944                 see: NetFilter >-> GENERIC target NetFilter kernel module
1945
1946         Description:
1947
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.
1953
1954         Implementation notes:
1955
1956         Return value:
1957
1958                 It returns NF_ACCEPT.
1959
1960         Example:
1961
1962                 see: NetFilter >-> GENERIC target NetFilter kernel module
1963
1964         See also:
1965
1966                 NetFilter >-> GENERIC target NetFilter kernel module
1967                 http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html
1968
1969
1970
1971 ** PEEK target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"
1972
1973         Interface:
1974
1975                 PEEK target NetFilter kernel module >-> KMds
1976
1977         Label:
1978
1979                 "PF_KEYv2 ACQUIRE"
1980
1981         Name:
1982
1983                 see RFC2367, PF_KEYv2 ACQUIRE
1984
1985         Synopsis:
1986
1987                 see RFC2367, PF_KEYv2 ACQUIRE
1988
1989         Arguments:
1990
1991                 see RFC2367, PF_KEYv2 ACQUIRE
1992
1993         Description:
1994
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
1998                 remote host.
1999
2000         Implementation notes:
2001
2002         Return value:
2003
2004                 see RFC2367, PF_KEYv2 ACQUIRE
2005
2006         Example:
2007
2008         See also:
2009
2010                 see RFC2367, PF_KEYv2 ACQUIRE
2011
2012
2013
2014 ** New I/F section template
2015
2016         Interface:
2017
2018         Label:
2019
2020         Name:
2021
2022         Synopsis:
2023
2024         Arguments:
2025
2026         Description:
2027
2028         Implementation notes:
2029
2030         Return value:
2031
2032         Example:
2033
2034         See also:
2035
2036
2037
2038 * Definitions and Data structures used
2039
2040 SAList := <SAID>[,<SAID>[,<SAID>[,<SAID>]]]
2041
2042 <SAID> := <proto><PF><spi>@<dstaddr>
2043
2044 <proto> := ah | esp | comp | tun
2045
2046 <PF> := . | : (indicates IPv4 or IPv6 respectively)
2047
2048 <spi> := <8-digit hexadecimal string>
2049
2050 <dstaddr> := <any valid FQDN or IP address of the appropriate family>
2051
2052
2053 const struct ipt_entry is already defined in netfilter.
2054
2055 struct ipt_entry_match is already defined in netfilter.
2056
2057 struct ipsec_seclev remains to be defined.
2058
2059 struct ipt_seclev_info {
2060         struct ipsec_seclev;            /* Security Level data */
2061         u_int8_t  invert;       /* Invert match */
2062 };
2063
2064 struct ipsec_salist {
2065         struct ipsec_said said1;
2066         struct ipsec_said said2;
2067         struct ipsec_said said3;
2068         struct ipsec_said said4;
2069 }
2070
2071 struct ipt_salist_info {
2072         struct ipsec_salist salist;     /* Security Association List data */
2073         u_int8_t  invert;       /* Invert match */
2074 };
2075
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;
2081 };
2082
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 */
2097 };
2098
2099 typedef struct {
2100         union {
2101                 struct sockaddr_in v4;
2102                 struct sockaddr_in6 v6;
2103         } u;
2104 } ip_address;
2105
2106 struct ipsec_sa {
2107         /* copy most from struct tdb */
2108 };
2109
2110 struct ipsecinfo {
2111         struct ipt_entry_target t;
2112         struct ipt_ipsec_target_info salist;
2113 };
2114
2115 struct trapinfo {
2116         struct ipt_entry_target t;
2117 };
2118
2119 struct peekinfo {
2120         struct ipt_entry_target t;
2121 };
2122
2123 struct holdinfo {
2124         struct ipt_entry_target t;
2125 };
2126
2127 * Version:
2128
2129         $Id: klips2-design-api.txt,v 1.21 2001/06/26 20:29:25 rgb Exp $