tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 2367


PF_KEY Key Management API, Version 2

Part 3 of 3, p. 45 to 68
Prev RFC Part


prevText      Top      Up      ToC       Page 45 
4 Future Directions

   While the current specification for the Sensitivity and Integrity
   Labels is believed to be general enough, if a case should arise that
   can't work with the current specification then this might cause a
   change in a future version of PF_KEY.

   Similarly, PF_KEY might need extensions to work with other kinds of
   Security Associations in future.  It is strongly desirable for such
   extensions to be made in a backwards-compatible manner should they be

   When more experience is gained with certificate management, it is
   possible that the IDENTITY extension will have to be revisited to
   allow a finer grained selection of certificate identities.

5. Examples

   The following examples illustrate how PF_KEY is used.  The first
   example is an IP Security example, where the consumer of the security
   associations is inside an operating system kernel. The second example
   is an OSPF Security example, which illustrates a user-level consumer
   of security associations.  The third example covers things not
   mentioned by the first two examples.  A real system may closely
   conform to one of these examples, or take parts of them.  These
   examples are purely illustrative, and are not intended to mandate a

Top      Up      ToC       Page 46 
   particular implementation method.

5.1 Simple IP Security Example

                     +---------------+    +-------------+
                     |Key Mgmt Daemon|    | Application |
                     +---------------+    +-------------+
                       |           |     /
                       |           |    /
                       |           |    |              Applications
                       |           |    |              OS Kernel
               +------------+   +-----------------+
               | Key Engine |   | TCP/IP,         |
               |  or  SADB  |---| including IPsec |
               +------------+   |                 |

   When the Key Management daemon (KMd) begins.  It must tell PF_KEY
   that it is willing to accept message for the two IPsec services, AH
   and ESP.  It does this by sending down two SADB_REGISTER messages.

     KMd->Kernel:         SADB_REGISTER for ESP
     Kernel->Registered:  SADB_REGISTER for ESP, Supported Algorithms
     KMd->Kernel:         SADB_REGISTER for AH
     Kernel->Registered:  SADB_REGISTER for AH, Supported Algorithms

   Each REGISTER message will cause a reply to go to all PF_KEY sockets
   registered for ESP and AH respectively (including the requester).

   Assume that no security associations currently exist for IPsec to
   use.  Consider when a network application begins transmitting data
   (e.g. a TCP SYN).  Because of policy, or the application's request,
   the kernel IPsec module needs an AH security association for this
   data.  Since there is not one present, the following message is

     Kernel->Registered:  SADB_ACQUIRE for AH, addrs, ID, sens,

   The KMd reads the ACQUIRE message, especially the sadb_msg_seq
   number.  Before it begins the negotiation, it sends down an
   SADB_GETSPI message with the sadb_msg_seq number equal to the one
   received in the ACQUIRE.  The kernel returns the results of the
   GETSPI to all listening sockets.

     KMd->Kernel:         SADB_GETSPI for AH, addr, SPI range
     Kernel->All:         SADB_GETSPI for AH, assoc, addrs

Top      Up      ToC       Page 47 
   The KMd may perform a second GETSPI operation if it needs both
   directions of IPsec SPI values.  Now that the KMd has an SPI for at
   least one of the security associations, it begins negotiation.  After
   deriving keying material, and negotiating other parameters, it sends
   down one (or more) SADB_UPDATE messages with the same value in

   If a KMd has any error at all during its negotiation, it can send

     KMd->Kernel:         SADB_ACQUIRE for AH, assoc (with an error)
     Kernel->All:         SADB_ACQUIRE for AH, assoc (same error)

   but if it succeeds, it can instead:

     KMd->Kernel:         SADB_UPDATE for AH, assoc, addrs, keys,
     Kernel->All:         SADB_UPDATE for AH, assoc, addrs, <etc.>

   The results of the UPDATE (minus the actual keys) are sent to all
   listening sockets.  If only one SPI value was determined locally, the
   other SPI (since IPsec SAs are unidirectional) must be added with an
   SADB_ADD message.

     KMd->Kernel:         SADB_ADD for AH, assoc, addrs, keys, <etc.>
     Kernel->All:         SADB_ADD for AH, assoc, addrs, <etc.>

   If one of the extensions passed down was a Lifetime extension, it is
   possible at some point an SADB_EXPIRE message will arrive when one of
   the lifetimes has expired.

     Kernel->All:         SADB_EXPIRE for AH, assoc, addrs,
                          Hard or Soft, Current, <etc.>

   The KMd can use this as a clue to begin negotiation, or, if it has
   some say in policy, send an SADB_UPDATE down with a lifetime

5.2 Proxy IP Security Example

   Many people are interested in using IP Security in a "proxy" or
   "firewall" configuration in which an intermediate system provides
   security services for "inside" hosts.  In these environments, the
   intermediate systems can use PF_KEY to communicate with key
   management applications almost exactly as they would if they were the
   actual endpoints. The messaging behavior of PF_KEY in these cases is
   exactly the same as the previous example, but the address information
   is slightly different.

Top      Up      ToC       Page 48 
     Consider this case:

                     A ========= B --------- C

               A           "outside" host that implements IPsec
               B           "firewall" that implements IPsec
               C           "inside" host that does not implement IPsec

               ===         IP_{A<->B} ESP [ IP_{A<->C} ULP ]
               ---         IP_{A<->C} ULP

   A is a single system that wishes to communicate with the "inside"
   system C.  B is a "firewall" between C and the outside world that
   will do ESP and tunneling on C's behalf.  A discovers that it needs
   to send traffic to C via B through methods not described here (Use of
   the DNS' KX record might be one method for discovering this).

   For packets that flow from left to right, A and B need an IPsec
   Security Association with:

           SA type of ESP tunnel-mode
           Source Identity that dominates A (e.g. A's address)
           Destination Identity that dominates B (e.g. B's address)
           Source Address of A
           Destination Address of B

   For packets to flow from right to left, A and B need an IPsec
   Security Association with:

           SA type of ESP tunnel-mode
           Source Identity that dominates C
           Destination Identity that dominates A
           Source Address of B
           Destination Address of A
           Proxy Address of C

   For this second SA (for packets flowing from C towards A), node A
   MUST verify that the inner source address is dominated by the Source
   Identity for the SA used with those packets.  If node A does not do
   this, an adversary could forge packets with an arbitrary Source
   Identity and defeat the packet origin protections provided by IPsec.

     Now consider a slightly more complex case:

               A_1 --|                  |-- D_1
                     |--- B ====== C ---|
               A_2 --|                  |-- D_2

Top      Up      ToC       Page 49 
               A_n     "inside" host on net 1 that does not do IPsec.
               B       "firewall" for net 1 that supports IPsec.
               C       "firewall" for net 2 that supports IPsec.
               D_n     "inside" host on net 2 that does not do IPsec.
               ===     IP_{B<->C} ESP [ IP_{A<->C} ULP ]
               ---     IP_{A<->C} ULP

           For A_1 to send a packet to D_1, B and C need an SA with:

                   SA Type of ESP
                   Source Identity that dominates A_1
                   Destination Identity that dominates C
                   Source Address of B
                   Destination Address of C
                   Proxy Address of A_1

           For D_1 to send a packet to A_1, C and B need an SA with:
                   SA Type of ESP Tunnel-mode
                   Source Identity that dominates D_1
                   Destination Identity that dominates B
                   Source Address of C
                   Destination Address of B
                   Proxy Address of D_1

   Note that A_2 and D_2 could be substituted for A_1 and D_1
   (respectively) here; the association of an SA with a particular pair
   of ends or group of those pairs is a policy decision on B and/or C
   and not necessarily a function of key management.  The same check of
   the Source Identity against the inner source IP address MUST also be
   performed in this case for the same reason.

   For a more detailed discussion of the use of IP Security in complex
   cases, please see [Atk97].

     NOTE: The notion of identity domination might be unfamiliar.  Let H
     represent some node. Let Hn represent H's fully qualified domain
     name. Let Ha represent the IP address of H. Let Hs represent the IP
     subnet containing Ha. Let Hd represent a fully qualified domain
     name that is a parent of the fully qualified domain name of H. Let
     M be a UserFQDN identity that whose right-hand part is Hn or Ha.

     Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the
     example above. Hs dominates any node having an IP address within
     the IP address range represented by Hs. Hd dominates any node
     having a fully qualified domain name within underneath Hd.

Top      Up      ToC       Page 50 
5.3 OSPF Security Example

           +---------------+    +-------------+
           |Key Mgmt Daemon|    | OSPF daemon |
           +---------------+    +-------------+
             |           |     /    /        |
             |    /------|----+    /         |
             |   /       |    +---+          |           Applications
             |           |    |              |           OS Kernel
     +------------+   +-----------------+  +---------+
     | Key Engine |   | TCP/IP,         |  | Routing |
     |  or  SADB  |---| including IPsec |--| Table   |
     +------------+   |                 |  +---------+

   As in the previous examples, the KMd registers itself with the Key
   Engine via PF_KEY.  Even though the consumer of the security
   associations is in user-space, the PF_KEY and Key Engine
   implementation knows enough to store SAs and to relay messages.

   When the OSPF daemon needs to communicate securely with its peers, it
   would perform an SADB_GET message and retrieve the appropriate

     OSPFd->Kernel:       SADB_GET of OSPF, assoc, addrs
     Kernel->OSPFd:       SADB_GET of OSPF, assoc, addrs, keys, <etc.>

   If this GET fails, the OSPFd may need to acquire a new security
   association.  This interaction is as follows:

     OSPFd->Kernel:       SADB_ACQUIRE of OSPF, addrs, <ID, sens,>
     Kernel->Registered:  SADB_ACQUIRE of OSPF, <same as sent message>

   The KMd sees this and performs actions similar to the previous
   example.  One difference, however, is that when the UPDATE message
   comes back, the OSPFd will then perform a GET of the updated SA to
   retrieve all of its parameters.

5.4 Miscellaneous

   Some messages work well only in system maintenance programs, for
   debugging, or for auditing.  In a system panic situation, such as a
   detected compromise, an SADB_FLUSH message should be issued for a
   particular SA type, or for ALL SA types.

Top      Up      ToC       Page 51 
     Program->Kernel:     SADB_FLUSH for ALL
     <Kernel then flushes all internal SAs>
     Kernel->All:         SADB_FLUSH for ALL

   Some SAs may need to be explicitly deleted, either by a KMd, or by a
   system maintenance program.

     Program->Kernel:     SADB_DELETE for AH, association, addrs
     Kernel->All:         SADB_DELETE for AH, association, addrs

   Common usage of the SADB_DUMP message is discouraged.  For debugging
   purposes, however, it can be quite useful.  The output of a DUMP
   message should be read quickly, in order to avoid socket buffer

     Program->Kernel:     SADB_DUMP for ESP
     Kernel->Program:     SADB_DUMP for ESP, association, <all fields>
     Kernel->Program:     SADB_DUMP for ESP, association, <all fields>
     Kernel->Program:     SADB_DUMP for ESP, association, <all fields>
     <ad nauseam...>

6 Security Considerations

   This memo discusses a method for creating, reading, modifying, and
   deleting Security Associations from an operating system.  Only
   trusted, privileged users and processes should be able to perform any
   of these operations.  It is unclear whether this mechanism provides
   any security when used with operating systems not having the concept
   of a trusted, privileged user.

   If an unprivileged user is able to perform any of these operations,
   then the operating system cannot actually provide the related
   security services.  If an adversary knows the keys and algorithms in
   use, then cryptography cannot provide any form of protection.

   This mechanism is not a panacea, but it does provide an important
   operating system component that can be useful in creating a secure

   Users need to understand that the quality of the security provided by
   an implementation of this specification depends completely upon the
   overall security of the operating system, the correctness of the
   PF_KEY implementation, and upon the security and correctness of the
   applications that connect to PF_KEY.  It is appropriate to use high
   assurance development techniques when implementing PF_KEY and the
   related security association components of the operating system.

Top      Up      ToC       Page 52 

   The authors of this document are listed primarily in alphabetical
   order.  Randall Atkinson and Ron Lee provided useful feedback on
   earlier versions of this document.

   At one time or other, all of the authors worked at the Center for
   High Assurance Computer Systems at the U.S.  Naval Research
   Laboratory. This work was sponsored by the Information Security
   Program Office (PMW-161), U.S.  Space and Naval Warfare Systems
   Command (SPAWAR) and the Computing Systems Technology Office, Defense
   Advanced Research Projects Agency (DARPA/CSTO). We really appreciate
   their sponsorship of our efforts and their continued support of
   PF_KEY development. Without that support, PF_KEY would not exist.

   The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST98].

   Finally, the authors would like to thank those who sent in comments
   and questions on the various iterations of this document. This
   specification and implementations of it are discussed on the PF_KEY
   mailing list. If you would like to be added to this list, send a note
   to <>.


   [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig
   W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite
   BSD", Proceedings of the 1996 USENIX Conference, San Diego, CA,
   January 1996, USENIX Association.

   [Atk95a] Atkinson, R., "IP Security Architecture", RFC 1825, August

   [Atk95b] Atkinson, R., "IP Authentication Header", RFC 1826, August

   [Atk95c] Atkinson, R., "IP Encapsulating Security Payload", RFC 1827,
   August 1995.

   [Atk97] Atkinson, R., "Key Exchange Delegation Record for the Domain
   Name System", RFC 2230, October 1997.

   [BA97] Baker, F., and R. Atkinson, "RIP-2 MD5 Authentication", RFC
   2082, January 1997.

   [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer
   Systems", MTR-3153, The MITRE Corporation, June 1975; ESD-TR-76-372,
   April 1977.

Top      Up      ToC       Page 53 
   [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer
   Systems: Unified Exposition and Multics Interpretation", MTR 2997,
   The MITRE Corporation, April 1974. (AD/A 020 445)

   [Bra97] Bradner, S., "Key words for use in RFCs to Indicate
   Requirement Levels", BCP 14, RFC 2119, March 1997.

   [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial and
   Military Computer Security Policies", Proceedings of the 1987
   Symposium on Security and Privacy, pp. 184-195, IEEE Computer
   Society, Washington, D.C., 1987.

   [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode
   Workstation Specification", Technical Report DDS-2600-6243-87.

   [GK98] Glenn, R., and S. Kent, "The NULL Encryption Algorithm and Its
   Use with IPsec", Work in Progress.

   [HM97a] Harney, H., and C. Muckenhirn, "Group Key Management Protocol
   (GKMP) Specification", RFC 2093, July 1997.

   [HM97b] Harney, H., and C. Muckenhirn, "Group Key Management Protocol
   (GKMP) Architecture", RFC 2094, July 1997.

   [MD98] Madsen, C., and N. Doraswamy, "The ESP DES-CBC Cipher
   Algorithm With Explicit IV", Work in Progress.

   [MG98a] Madsen, C., and R. Glenn, "The Use of HMAC-MD5-96 within ESP
   and AH", Work in Progress.

   [MG98b] Madsen, C., and R. Glenn, "The Use of HMAC-SHA-1-96 within
   ESP and AH", Work in Progress.

   [MSST98] Maughan, D., Schertler, M., Schneider, M., and J. Turner,
   "Internet Security Association and Key Management Protocol (ISAKMP)",
   Work in Progress.

   [Moy98] Moy, J., "OSPF Version 2", STD 54, RFC 2328, April 1998.

   [Per97] Perkins, C., "IP Mobility Support", RFC 2002, October 1996.

   [Pip98] Piper, D., "The Internet IP Security Domain of Interpretation
   for ISAKMP", Work in Progress.

   [Sch96] Bruce Schneier, Applied Cryptography, p. 360, John Wiley &
   Sons, Inc., 1996.

Top      Up      ToC       Page 54 
   [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for
   Berkeley UNIX", Proceedings of the Winter 1991 USENIX Conference,
   Dallas, TX, USENIX Association. 1991.  pp. 93-103.


   The views and specification here are those of the editors and are not
   necessarily those of their employers.  The employers have not passed
   judgment on the merits, if any, of this work.  The editors and their
   employers specifically disclaim responsibility for any problems
   arising from correct or incorrect implementation or use of this

Authors' Addresses

   Daniel L. McDonald
   Sun Microsystems, Inc.
   901 San Antonio Road, MS UMPK17-202
   Palo Alto, CA 94303

   Phone: +1 650 786 6815

   Craig Metz
   (for Code 5544)
   U.S. Naval Research Laboratory
   4555 Overlook Ave. SW
   Washington, DC 20375

   Phone: (DSN) 754-8590

   Bao G. Phan
   U. S. Naval Research Laboratory


Top      Up      ToC       Page 55 
Appendix A: Promiscuous Send/Receive Message Type

   A kernel supporting PF_KEY MAY implement the following extension for
   development and debugging purposes. If it does, it MUST implement the
   extension as specified here. An implementation MAY require an
   application to have additional privileges to perform promiscuous send
   and/or receive operations.

   The SADB_X_PROMISC message allows an application to send and receive
   messages in a "promiscuous mode." There are two forms of this
   message: control and data. The control form consists of only a
   message header.  This message is used to toggle the promiscuous-
   receive function. A value of one in the sadb_msg_satype field enables
   promiscuous message reception for this socket, while a value of zero
   in that field disables it.

   The second form of this message is the data form. This is used to
   send or receive messages in their raw form. Messages in the data form
   consist of a message header followed by an entire new message.  There
   will be two message headers in a row: one for the SADB_X_PROMISC
   message, and one for the payload message.

   Data messages sent from the application are sent to either the PF_KEY
   socket of a single process identified by a nonzero sadb_msg_seq or to
   all PF_KEY sockets if sadb_msg_seq is zero.  These messages are sent
   without any processing of their contents by the PF_KEY interface
   (including sanity checking).  This promiscuous-send capability allows
   an application to send messages as if it were the kernel. This also
   allows it to send erroneous messages.

   If the promiscuous-receive function has been enabled, a copy of any
   message sent via PF_KEY by another application or by the kernel is
   sent to the promiscuous application.  This is done before any
   processing of the message's contents by the PF_KEY interface (again,
   including sanity checking).  This promiscuous-receive capability
   allows an application to receive all messages sent by other parties
   using PF_KEY.

     The messaging behavior of the SADB_X_PROMISC message is:

         Send a control-form SADB_X_PROMISC message from a user process
         to the kernel.


         The kernel returns the SADB_X_PROMISC message to all listening

Top      Up      ToC       Page 56 

         Send a data-form SADB_X_PROMISC message from a user process to
         the kernel.

         <base, base(, others)>

         The kernel sends the encapsulated message to the target

         <base(, others)>

         If promiscuous-receive is enabled, the kernel will encapsulate
         and send copies of all messages sent via the PF_KEY interface.

         <base, base(, others)>

         EPERM Additional privileges are required to perform the
               requested operations.
         ESRCH (Data form, sending) The target process in sadb_msg_seq
               does not exist or does not have an open PF_KEY Version 2

Top      Up      ToC       Page 57 
Appendix B: Passive Change Message Type

   The SADB_X_PCHANGE message is a passive-side (aka.  the "listener" or
   "receiver") counterpart to the SADB_ACQUIRE message.  It is useful
   for when key management applications wish to more effectively handle
   incoming key management requests for passive-side sessions that
   deviate from systemwide default security services.  If a passive
   session requests that only certain levels of security service be
   allowed, the SADB_X_PCHANGE message expresses this change to any
   registered PF_KEY sockets.  Unlike SADB_ACQUIRE, this message is
   purely informational, and demands no other PF_KEY interaction.

   The SADB_X_PCHANGE message is typically triggered by either a change
   in an endpoint's requested security services, or when an endpoint
   that made a special request disappears.  In the former case, an
   SADB_X_PCHANGE looks like an SADB_ACQUIRE, complete with an
   sadb_proposal extension indicating the preferred algorithms,
   lifetimes, and other attributes.  When a passive session either
   disappears, or reverts to a default behavior, an SADB_X_PCHANGE will
   be issued with _no_ sadb_proposal extension, indicating that the
   exception to systemwide default behavior has disappeared.

   There are two messaging behaviors for SADB_X_PCHANGE.  The first is
   the kernel-originated case:

        The kernel sends an SADB_X_PCHANGE message to registered

        <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>

        NOTE:  The address(SD) extensions MUST have the port fields
               filled in with the port numbers of the session
               requiring keys if appropriate.

   The second is for a user-level consumer of SAs.

        Send an SADB_X_PCHANGE message from a user process to the

        <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>

        The kernel returns an SADB_X_PCHANGE message to registered

        <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>

Top      Up      ToC       Page 58 
Appendix C: Key Management Private Data Extension

   The Key Management Private Data extension is attached to either an
   SADB_ADD or an SADB_UPDATE message.  It attaches a single piece of
   arbitrary data to a security association.  It may be useful for key
   managment applications that could use an SADB_DUMP or SADB_GET
   message to obtain additional state if it needs to restart or recover
   after a crash.  The format of this extension is:

           #define SADB_X_EXT_KMPRIVATE 17

           struct sadb_x_kmprivate {
                   uint16_t sadb_x_kmprivate_len;
                   uint16_t sadb_x_kmprivate_exttype;
                   uint32_t sadb_x_kmprivate_reserved;
           /* sizeof(struct sadb_x_kmprivate) == 8 */

           /* followed by arbitrary data */

   The data following the sadb_x_kmprivate extension can be anything.
   It will be stored with the actual security association in the kernel.
   Like all data, it must be padded to an eight byte boundary.

Top      Up      ToC       Page 59 
Appendix D: Sample Header File

   This file defines structures and symbols for the PF_KEY Version 2
   key management interface. It was written at the U.S. Naval Research
   Laboratory. This file is in the public domain. The authors ask that
   you leave this credit intact on any copies of this file.
   #ifndef __PFKEY_V2_H
   #define __PFKEY_V2_H 1

   #define PF_KEY_V2 2
   #define PFKEYV2_REVISION        199806L

   #define SADB_RESERVED    0
   #define SADB_GETSPI      1
   #define SADB_UPDATE      2
   #define SADB_ADD         3
   #define SADB_DELETE      4
   #define SADB_GET         5
   #define SADB_ACQUIRE     6
   #define SADB_REGISTER    7
   #define SADB_EXPIRE      8
   #define SADB_FLUSH       9
   #define SADB_DUMP        10
   #define SADB_X_PROMISC   11
   #define SADB_X_PCHANGE   12
   #define SADB_MAX         12

   struct sadb_msg {
     uint8_t sadb_msg_version;
     uint8_t sadb_msg_type;
     uint8_t sadb_msg_errno;
     uint8_t sadb_msg_satype;
     uint16_t sadb_msg_len;
     uint16_t sadb_msg_reserved;
     uint32_t sadb_msg_seq;
     uint32_t sadb_msg_pid;

   struct sadb_ext {
     uint16_t sadb_ext_len;
     uint16_t sadb_ext_type;

   struct sadb_sa {
     uint16_t sadb_sa_len;
     uint16_t sadb_sa_exttype;

Top      Up      ToC       Page 60 
     uint32_t sadb_sa_spi;
     uint8_t sadb_sa_replay;
     uint8_t sadb_sa_state;
     uint8_t sadb_sa_auth;
     uint8_t sadb_sa_encrypt;
     uint32_t sadb_sa_flags;

   struct sadb_lifetime {
     uint16_t sadb_lifetime_len;
     uint16_t sadb_lifetime_exttype;
     uint32_t sadb_lifetime_allocations;
     uint64_t sadb_lifetime_bytes;
     uint64_t sadb_lifetime_addtime;
     uint64_t sadb_lifetime_usetime;

   struct sadb_address {
     uint16_t sadb_address_len;
     uint16_t sadb_address_exttype;
     uint8_t sadb_address_proto;
     uint8_t sadb_address_prefixlen;
     uint16_t sadb_address_reserved;

   struct sadb_key {
     uint16_t sadb_key_len;
     uint16_t sadb_key_exttype;
     uint16_t sadb_key_bits;
     uint16_t sadb_key_reserved;

   struct sadb_ident {
     uint16_t sadb_ident_len;
     uint16_t sadb_ident_exttype;
     uint16_t sadb_ident_type;
     uint16_t sadb_ident_reserved;
     uint64_t sadb_ident_id;

   struct sadb_sens {
     uint16_t sadb_sens_len;
     uint16_t sadb_sens_exttype;
     uint32_t sadb_sens_dpd;
     uint8_t sadb_sens_sens_level;
     uint8_t sadb_sens_sens_len;
     uint8_t sadb_sens_integ_level;
     uint8_t sadb_sens_integ_len;

Top      Up      ToC       Page 61 
     uint32_t sadb_sens_reserved;

   struct sadb_prop {
     uint16_t sadb_prop_len;
     uint16_t sadb_prop_exttype;
     uint8_t sadb_prop_replay;
     uint8_t sadb_prop_reserved[3];

   struct sadb_comb {
     uint8_t sadb_comb_auth;
     uint8_t sadb_comb_encrypt;
     uint16_t sadb_comb_flags;
     uint16_t sadb_comb_auth_minbits;
     uint16_t sadb_comb_auth_maxbits;
     uint16_t sadb_comb_encrypt_minbits;
     uint16_t sadb_comb_encrypt_maxbits;
     uint32_t sadb_comb_reserved;
     uint32_t sadb_comb_soft_allocations;
     uint32_t sadb_comb_hard_allocations;
     uint64_t sadb_comb_soft_bytes;
     uint64_t sadb_comb_hard_bytes;
     uint64_t sadb_comb_soft_addtime;
     uint64_t sadb_comb_hard_addtime;
     uint64_t sadb_comb_soft_usetime;
     uint64_t sadb_comb_hard_usetime;

   struct sadb_supported {
     uint16_t sadb_supported_len;
     uint16_t sadb_supported_exttype;
     uint32_t sadb_supported_reserved;

   struct sadb_alg {
     uint8_t sadb_alg_id;
     uint8_t sadb_alg_ivlen;
     uint16_t sadb_alg_minbits;
     uint16_t sadb_alg_maxbits;
     uint16_t sadb_alg_reserved;

   struct sadb_spirange {
     uint16_t sadb_spirange_len;
     uint16_t sadb_spirange_exttype;
     uint32_t sadb_spirange_min;
     uint32_t sadb_spirange_max;

Top      Up      ToC       Page 62 
     uint32_t sadb_spirange_reserved;

   struct sadb_x_kmprivate {
     uint16_t sadb_x_kmprivate_len;
     uint16_t sadb_x_kmprivate_exttype;
     uint32_t sadb_x_kmprivate_reserved;

   #define SADB_EXT_RESERVED             0
   #define SADB_EXT_SA                   1
   #define SADB_EXT_LIFETIME_HARD        3
   #define SADB_EXT_LIFETIME_SOFT        4
   #define SADB_EXT_ADDRESS_SRC          5
   #define SADB_EXT_ADDRESS_DST          6
   #define SADB_EXT_ADDRESS_PROXY        7
   #define SADB_EXT_KEY_AUTH             8
   #define SADB_EXT_KEY_ENCRYPT          9
   #define SADB_EXT_IDENTITY_SRC         10
   #define SADB_EXT_IDENTITY_DST         11
   #define SADB_EXT_SENSITIVITY          12
   #define SADB_EXT_PROPOSAL             13
   #define SADB_EXT_SUPPORTED_AUTH       14
   #define SADB_EXT_SPIRANGE             16
   #define SADB_X_EXT_KMPRIVATE          17
   #define SADB_EXT_MAX                  17
   #define SADB_SATYPE_UNSPEC    0
   #define SADB_SATYPE_AH        2
   #define SADB_SATYPE_ESP       3
   #define SADB_SATYPE_RSVP      5
   #define SADB_SATYPE_OSPFV2    6
   #define SADB_SATYPE_RIPV2     7
   #define SADB_SATYPE_MIP       8
   #define SADB_SATYPE_MAX       8

   #define SADB_SASTATE_LARVAL   0
   #define SADB_SASTATE_MATURE   1
   #define SADB_SASTATE_DYING    2
   #define SADB_SASTATE_DEAD     3
   #define SADB_SASTATE_MAX      3

   #define SADB_SAFLAGS_PFS      1

   #define SADB_AALG_NONE        0
   #define SADB_AALG_MD5HMAC     2
   #define SADB_AALG_SHA1HMAC    3

Top      Up      ToC       Page 63 
   #define SADB_AALG_MAX         3

   #define SADB_EALG_NONE        0
   #define SADB_EALG_DESCBC      2
   #define SADB_EALG_3DESCBC     3
   #define SADB_EALG_NULL        11
   #define SADB_EALG_MAX         11

   #define SADB_IDENTTYPE_PREFIX     1
   #define SADB_IDENTTYPE_FQDN       2
   #define SADB_IDENTTYPE_MAX        3

   #define SADB_KEY_FLAGS_MAX 0
   #endif /* __PFKEY_V2_H */

Top      Up      ToC       Page 64 
Appendix E: Change Log

   The following changes were made between 05 and 06:

   * Last change before becoming an informational RFC.  Removed all
     Internet-Draft references.  Also standardized citation strings.
     Now cite RFC 2119 for MUST, etc.

   * New appendix on optional KM private data extension.

   * Fixed example to indicate the ACQUIRE messages with errno mean
     KM failure.

   * Added SADB_EALG_NULL.

   * Clarified proxy examples to match definition of PROXY address being
     the inner packet's source address.  (Basically a sign-flip.  The
     example still shows how to protect against policy vulnerabilities
     in tunnel endpoints.)

   * Loosened definition of a destination address to include broadcast.

   * Recommended that LARVAL security associations have implicit short

   The following changes were made between 04 and 05:

   * New appendix on Passive Change message.

   * New sadb_address_prefixlen field.

   * Small clarifications on sadb_ident_id usage.

   * New PFKEYV2_REVISION value.

   * Small clarification on what a PROXY address is.

   * Corrected sadb_spirange_{min,max} language.

   * In ADD messages that are in response to an ACQUIRE, the
     sadb_msg_seq MUST be the same as that of the originating ACQUIRE.

   * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up
     PROXY addresses when it needs them.

   * Clarification on SADB_EXPIRE and user-level security protocols.

   The following changes were made between 03 and 04:

Top      Up      ToC       Page 65 
   * Stronger language about manual keying.


   * Put in language about sockaddr ports in ACQUIRE messages.

   * Mention of asymmetric algorithms.

   * New sadb_ident_id field for easier construction of USER_FQDN
     identity strings.

   * Caveat about source addresses not always used for collision
     detection. (e.g. IPsec)

   The following changes were made between 02 and 03:

   * Formatting changes.

   * Many editorial cleanups, rewordings, clarifications.

   * Restrictions that prevent many strange and invalid cases.

   * Added definitions section.

   * Removed connection identity type (this will reappear when it is
     more clear what it should look like).

   * Removed 5.2.1 (Why involve the kernel?).

   * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed
     from src, dst, and proxy and you had to anyway for sanity checking.

   * Removed REPLAY flag; sadb_sa_replay==0 means the same thing.

   * Renamed bit lengths to "bits" to avoid potential confusion.

   * Explicitly listed lengths for structures.

   * Reworked identities to always use a string format.

   * Removed requirements for support of shutdown() and SO_USELOOPBACK.

   * 64 bit alignment and 64 bit lengths instead of 32 bit.

   * time_t replaced with uint64 in lifetimes.

Top      Up      ToC       Page 66 
   * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER

   * Explicit error if PF_KEY_V2 not set at socket() call.

   * More text on SO_USELOOPBACK.

   * Made fields names and symbol names more consistent.

   * Explicit error if PF_KEY_V2 is not in sadb_msg_version field.

   * Bytes lifetime field now a 64-bit quantity.

   * Explicit len/exttype wording.

   * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.)

   * UI example (0x123 == 0x1230 or 0x0123).

   * Cleaned up and fixed some message behavior examples.

   The following changes were made between 01 and 02:

   * Mentioned that people COULD use these same messages between user
     progs. (Also mentioned why you still might want to use the actual

   * Various wordsmithing changes.

   * Took out netkey/ directory, and make net/pfkeyv2.h

   * Inserted PF_KEY_V2 proto argument per C. Metz.

   * Mentioned other socket calls and how their PF_KEY behavior is

   * SADB_EXPIRE now communicates both hard and soft lifetime expires.

   * New "association" extension, even smaller base header.

   * Lifetime extension improvements.

   * Length now first in extensions.

   * Errors can be sent from kernel to user, also.

   * Examples section inserted.

Top      Up      ToC       Page 67 
   * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup.

   * Key splitting now only across auth algorithm and encryption
     algorithm. Thanks for B. Sommerfeld for clues here.

   The following changes were made between 00 and 01:

   * Added this change log.

   * Simplified TLV header syntax.

   * Splitting of algorithms. This may be controversial, but it allows
     PF_KEY to be used for more than just IPsec. It also allows some
     kinds of policies to be placed in the KMd easier.

   * Added solid definitions and formats for certificate identities,
     multiple keys, etc.

   * Specified how keys are to be layed out (most-to-least bits).

   * Changed sequence number semantics to be like an RPC transaction ID

Top      Up      ToC       Page 68 
F.  Full Copyright Statement

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an