    Network Working Group                                       D. McDonald
    Request for Comments: 2367                                      C. Metz
    Category: Informational                                         B. Phan
                                                                  July 1998

                      PF_KEY Key Management API, Version 2

    Status of this Memo

       This memo provides information for the Internet community.  It does
       not specify an Internet standard of any kind.  Distribution of this
       memo is unlimited.

    Copyright Notice

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

    Abstract

       A generic key management API that can be used not only for IP
       Security [Atk95a] [Atk95b] [Atk95c] but also for other network
       security services is presented in this document.  Version 1 of this
       API was implemented inside 4.4-Lite BSD as part of the U. S. Naval
       Research Laboratory's freely distributable and usable IPv6 and IPsec
       implementation[AMPMC96].  It is documented here for the benefit of
       others who might also adopt and use the API, thus providing increased
       portability of key management applications (e.g. a manual keying
       application, an ISAKMP daemon, a GKMP daemon [HM97a][HM97b], a
       Photuris daemon, or a SKIP certificate discovery protocol daemon).

    Table of Contents

       1      Introduction .............................................  3
       1.1    Terminology ..............................................  3
       1.2    Conceptual Model .........................................  4
       1.3    PF_KEY Socket Definition .................................  8
       1.4    Overview of PF_KEY Messaging Behavior ....................  8
       1.5    Common PF_KEY Operations .................................  9
       1.6    Differences Between PF_KEY and PF_ROUTE .................. 10
       1.7    Name Space ............................................... 11
       1.8    On Manual Keying ..........................................11
       2      PF_KEY Message Format .................................... 11
       2.1    Base Message Header Format ............................... 12
       2.2    Alignment of Headers and Extension Headers ............... 14
       2.3    Additional Message Fields ................................ 14
       2.3.1  Association Extension .................................... 15
       2.3.2  Lifetime Extension ....................................... 16

    McDonald, et. al.            Informational                      [Page 1]

    RFC 2367               PF_KEY Key Management API               July 1998

       2.3.3  Address Extension ........................................ 18
       2.3.4  Key Extension ............................................ 19
       2.3.5  Identity Extension ....................................... 21
       2.3.6  Sensitivity Extension .................................... 21
       2.3.7  Proposal Extension ....................................... 22
       2.3.8  Supported Algorithms Extension ........................... 25
       2.3.9  SPI Range Extension ...................................... 26
       2.4    Illustration of Message Layout ........................... 27
       3      Symbolic Names ........................................... 30
       3.1    Message Types ............................................ 31
       3.1.1  SADB_GETSPI .............................................. 32
       3.1.2  SADB_UPDATE .............................................. 33
       3.1.3  SADB_ADD ................................................. 34
       3.1.4  SADB_DELETE .............................................. 35
       3.1.5  SADB_GET ................................................. 36
       3.1.6  SADB_ACQUIRE ............................................. 36
       3.1.7  SADB_REGISTER ............................................ 38
       3.1.8  SADB_EXPIRE .............................................. 39
       3.1.9  SADB_FLUSH ............................................... 40
       3.1.10 SADB_DUMP ................................................ 40
       3.2    Security Association Flags ............................... 41
       3.3    Security Association States .............................. 41
       3.4    Security Association Types ............................... 41
       3.5    Algorithm Types .......................................... 42
       3.6    Extension Header Values .................................. 43
       3.7    Identity Extension Values ................................ 44
       3.8    Sensitivity Extension Values ............................. 45
       3.9    Proposal Extension Values ................................ 45
       4      Future Directions ........................................ 45
       5      Examples ................................................. 45
       5.1    Simple IP Security Example ............................... 46
       5.2    Proxy IP Security Example ................................ 47
       5.3    OSPF Security Example .................................... 50
       5.4    Miscellaneous ............................................ 50
       6      Security Considerations .................................. 51
              Acknowledgments ............,............................. 52
              References ............................................... 52
              Disclaimer ............................................... 54
              Authors' Addresses ....................................... 54
       A      Promiscuous Send/Receive Extension ....................... 55
       B      Passive Change Message Extension ......................... 57
       C      Key Management Private Data Extension .................... 58
       D      Sample Header File ....................................... 59
       E      Change Log ............................................... 64
       F      Full Copyright Statement ................................. 68

    McDonald, et. al.            Informational                      [Page 2]

    RFC 2367               PF_KEY Key Management API               July 1998

    1 Introduction

       PF_KEY is a new socket protocol family used by trusted privileged key
       management applications to communicate with an operating system's key
       management internals (referred to here as the "Key Engine" or the
       Security Association Database (SADB)).  The Key Engine and its
       structures incorporate the required security attributes for a session
       and are instances of the "Security Association" (SA) concept
       described in [Atk95a].  The names PF_KEY and Key Engine thus refer to
       more than cryptographic keys and are retained for consistency with
       the traditional phrase, "Key Management".

       PF_KEY is derived in part from the BSD routing socket, PF_ROUTE.
       [Skl91] This document describes Version 2 of PF_KEY. Version 1 was
       implemented in the first five alpha test versions of the NRL
       IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco
       ISAKMP/Oakley key management daemon.  Version 2 extends and refines
       this interface. Theoretically, the messages defined in this document
       could be used in a non-socket context (e.g.  between two directly
       communicating user-level processes), but this document will not
       discuss in detail such possibilities.

       Security policy is deliberately omitted from this interface. PF_KEY
       is not a mechanism for tuning systemwide security policy, nor is it
       intended to enforce any sort of key management policy. The developers
       of PF_KEY believe that it is important to separate security
       mechanisms (such as PF_KEY) from security policies.  This permits a
       single mechanism to more easily support multiple policies.

    1.1 Terminology

       Even though this document is not intended to be an actual Internet
       standard, the words that are used to define the significance of
       particular features of this interface are usually capitalized.  Some
       of these words, including MUST, MAY, and SHOULD, are detailed in
       [Bra97].

       - CONFORMANCE and COMPLIANCE

       Conformance to this specification has the same meaning as compliance
       to this specification.  In either case, the mandatory-to-implement,
       or MUST, items MUST be fully implemented as specified here.  If any
       mandatory item is not implemented as specified here, that
       implementation is not conforming and not compliant with this
       specification.

    McDonald, et. al.            Informational                      [Page 3]

    RFC 2367               PF_KEY Key Management API               July 1998

       This specification also uses many terms that are commonly used in the
       context of network security.  Other documents provide more
       definitions and background information on these [VK83, HA94, Atk95a].
       Two terms deserve special mention:

       - (Encryption/Authentication) Algorithm

       For PF_KEY purposes, an algorithm, whether encryption or
       authentication, is the set of operations performed on a packet to
       complete authentication or encryption as indicated by the SA type.  A
       PF_KEY algorithm MAY consist of more than one cryptographic
       algorithm. Another possibility is that the same basic cryptographic
       algorithm may be applied with different modes of operation or some
       other implementation difference. These differences, henceforth called
       _algorithm differentiators_, distinguish between different PF_KEY
       algorithms, and options to the same algorithm.  Algorithm
       differentiators will often cause fundamentally different security
       properties.

       For example, both DES and 3DES use the same cryptographic algorithm,
       but they are used differently and have different security properties.
       The triple-application of DES is considered an algorithm
       differentiator.  There are therefore separate PF_KEY algorithms for
       DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same hash function, but
       construct their message authentication codes differently. The use of
       HMAC is an algorithm differentiator.  DES-ECB and DES-CBC are the
       same cryptographic algorithm, but use a different mode. Mode (e.g.,
       chaining vs. code-book) is an algorithm differentiator. Blowfish with
       a 128-bit key, however, is similar to Blowfish with a 384-bit key,
       because the algorithm's workings are otherwise the same and therefore
       the key length is not an algorithm differentiator.

       In terms of IP Security, a general rule of thumb is that whatever
       might be labeled the "encryption" part of an ESP transform is
       probably a PF_KEY encryption algorithm. Whatever might be labelled
       the "authentication" part of an AH or ESP transform is probably a
       PF_KEY authentication algorithm.

    1.2 Conceptual Model

       This section describes the conceptual model of an operating system
       that implements the PF_KEY key management application programming
       interface. This section is intended to provide background material
       useful to understand the rest of this document.  Presentation of this
       conceptual model does not constrain a PF_KEY implementation to
       strictly adhere to the conceptual components discussed in this
       subsection.

    McDonald, et. al.            Informational                      [Page 4]

    RFC 2367               PF_KEY Key Management API               July 1998

       Key management is most commonly implemented in whole or in part at
       the application layer.  For example, the ISAKMP/Oakley, GKMP, and
       Photuris proposals for IPsec key management are all application-layer
       protocols.  Manual keying is also done at the application layer.
       Even parts of the SKIP IP-layer keying proposal can be implemented at
       the application layer.  Figure 1 shows the relationship between a Key
       Management daemon and PF_KEY.  Key management daemons use PF_KEY to
       communicate with the Key Engine and use PF_INET (or PF_INET6 in the
       case of IPv6) to communicate, via the network, with a remote key
       management entity.

       The "Key Engine" or "Security Association Database (SADB)" is a
       logical entity in the kernel that stores, updates, and deletes
       Security Association data for various security protocols.  There are
       logical interfaces within the kernel (e.g.  getassocbyspi(),
       getassocbysocket()) that security protocols inside the kernel (e.g.
       IP Security, aka IPsec) use to request and obtain Security
       Associations.

       In the case of IPsec, if by policy a particular outbound packet needs
       processing, then the IPsec implementation requests an appropriate
       Security Association from the Key Engine via the kernel-internal
       interface.  If the Key Engine has an appropriate SA, it allocates the
       SA to this session (marking it as used) and returns the SA to the
       IPsec implementation for use.  If the Key Engine has no such SA but a
       key management application has previously indicated (via a PF_KEY
       SADB_REGISTER message) that it can obtain such SAs, then the Key
       Engine requests that such an SA be created (via a PF_KEY SADB_ACQUIRE
       message).  When the key management daemon creates a new SA, it places
       it into the Key Engine for future use.

    McDonald, et. al.            Informational                      [Page 5]

    RFC 2367               PF_KEY Key Management API               July 1998

                         +---------------+
                         |Key Mgmt Daemon|
                         +---------------+
                           |           |
                           |           |
                           |           |                   Applications
                   ======[PF_KEY]====[PF_INET]==========================
                           |           |                   OS Kernel
                   +------------+   +-----------------+
                   | Key Engine |   | TCP/IP,         |
                   |  or  SADB  |---| including IPsec |
                   +------------+   |                 |
                                    +-----------------+
                                           |
                                       +-----------+
                                       | Network   |
                                       | Interface |
                                       +-----------+

                  Figure 1: Relationship of Key Mgmt to PF_KEY

       For performance reasons, some security protocols (e.g. IP Security)
       are usually implemented inside the operating system kernel.  Other
       security protocols (e.g.  OSPFv2 Cryptographic Authentication) are
       implemented in trusted privileged applications outside the kernel.
       Figure 2 shows a trusted, privileged routing daemon using PF_INET to
       communicate routing information with a remote routing daemon and
       using PF_KEY to request, obtain, and delete Security Associations
       used with a routing protocol.

    McDonald, et. al.            Informational                      [Page 6]

    RFC 2367               PF_KEY Key Management API               July 1998

                         +---------------+
                         |Routing  Daemon|
                         +---------------+
                           |           |
                           |           |
                           |           |                   Applications
                   ======[PF_KEY]====[PF_INET]==========================
                           |           |                   OS Kernel
                   +------------+   +---------+
                   | Key Engine |   | TCP/IP  |
                   |  or  SADB  |---|         |
                   +------------+   +---------+
                                           |
                                       +-----------+
                                       | Network   |
                                       | Interface |
                                       +-----------+

            Figure 2: Relationship of Trusted Application to PF_KEY

       When a trusted privileged application is using the Key Engine but
       implements the security protocol within itself, then operation varies
       slightly.  In this case, the application needing an SA sends a PF_KEY
       SADB_ACQUIRE message down to the Key Engine, which then either
       returns an error or sends a similar SADB_ACQUIRE message up to one or
       more key management applications capable of creating such SAs.  As
       before, the key management daemon stores the SA into the Key Engine.
       Then, the trusted privileged application uses an SADB_GET message to
       obtain the SA from the Key Engine.

       In some implementations, policy may be implemented in user-space,
       even though the actual cryptographic processing takes place in the
       kernel.  Such policy communication between the kernel mechanisms and
       the user-space policy MAY be implemented by PF_KEY extensions, or
       other such mechanism.  This document does not specify such
       extensions.  A PF_KEY implementation specified by the memo does NOT
       have to support configuring systemwide policy using PF_KEY.

       Untrusted clients, for example a user's web browser or telnet client,
       do not need to use PF_KEY.  Mechanisms not specified here are used by
       such untrusted client applications to request security services (e.g.
       IPsec) from an operating system.  For security reasons, only trusted,
       privileged applications are permitted to open a PF_KEY socket.

    McDonald, et. al.            Informational                      [Page 7]

    RFC 2367               PF_KEY Key Management API               July 1998

    1.3 PF_KEY Socket Definition

       The PF_KEY protocol family (PF_KEY) symbol is defined in
       <sys/socket.h> in the same manner that other protocol families are
       defined.  PF_KEY does not use any socket addresses.  Applications
       using PF_KEY MUST NOT depend on the availability of a symbol named
       AF_KEY, but kernel implementations are encouraged to define that
       symbol for completeness.

         The key management socket is created as follows:

         #include <sys/types.h>
         #include <sys/socket.h>
         #include <net/pfkeyv2.h>

         int s;
         s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2);

       The PF_KEY domain currently supports only the SOCK_RAW socket type.
       The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT
       will be returned.  Only a trusted, privileged process can create a
       PF_KEY socket.  On conventional UNIX systems, a privileged process is
       a process with an effective userid of zero.  On non-MLS proprietary
       operating systems, the notion of a "privileged process" is
       implementation-defined.  On Compartmented Mode Workstations (CMWs) or
       other systems that claim to provide Multi-Level Security (MLS), a
       process MUST have the "key management privilege" in order to open a
       PF_KEY socket[DIA].  MLS systems that don't currently have such a
       specific privilege MUST add that special privilege and enforce it
       with PF_KEY in order to comply and conform with this specification.
       Some systems, most notably some popular personal computers, do not
       have the concept of an unprivileged user.  These systems SHOULD take
       steps to restrict the programs allowed to access the PF_KEY API.

    1.4 Overview of PF_KEY Messaging Behavior

       A process interacts with the key engine by sending and receiving
       messages using the PF_KEY socket.  Security association information
       can be inserted into and retrieved from the kernel's security
       association table using a set of predefined messages.  In the normal
       case, all properly-formed messages sent to the kernel are returned to
       all open PF_KEY sockets, including the sender.  Improperly formed
       messages will result in errors, and an implementation MUST check for
       a properly formed message before returning it to the appropriate
       listeners. Unlike the routing socket, most errors are sent in reply
       messages, not the errno field when write() or send() fails. PF_KEY
       message delivery is not guaranteed, especially in cases where kernel
       or socket buffers are exhausted and messages are dropped.

    McDonald, et. al.            Informational                      [Page 8]

    RFC 2367               PF_KEY Key Management API               July 1998

       Some messages are generated by the operating system to indicate that
       actions need to be taken, and are not necessarily in response to any
       message sent down by the user.  Such messages are not received by all
       PF_KEY sockets, but by sockets which have indicated that kernel-
       originated messages are to be received.  These messages are special
       because of the expected frequency at which they will occur.  Also, an
       implementation may further wish to restrict return messages from the
       kernel, in cases where not all PF_KEY sockets are in the same trust
       domain.

       Many of the normal BSD socket calls have undefined behavior on PF_KEY
       sockets.  These include: bind(), connect(), socketpair(), accept(),
       getpeername(), getsockname(), ioctl(), and listen().

    1.5 Common PF_KEY Operations

       There are two basic ways to add a new Security Association into the
       kernel.  The simplest is to send a single SADB_ADD message,
       containing all of the SA information, from the application into the
       kernel's Key Engine.  This approach works particularly well with
       manual key management, which is required for IPsec, and other
       security protocols.

       The second approach to add a new Security Association into the kernel
       is for the application to first request a Security Parameters Index
       (SPI) value from the kernel using the SADB_GETSPI message and then
       send an SADB_UPDATE message with the complete Security Association
       data.  This second approach works well with key management daemons
       when the SPI values need to be known before the entire Security
       Association data is known (e.g. so the SPI value can be indicated to
       the remote end of the key management session).

       An individual Security Association can be deleted using the
       SADB_DELETE message.  Categories of SAs or the entire kernel SA table
       can be deleted using the SADB_FLUSH message.

       The SADB_GET message is used by a trusted application-layer process
       (e.g.  routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF
       SA) from the kernel's Key Engine.

       The kernel or an application-layer can use the SADB_ACQUIRE message
       to request that a Security Association be created by some
       application-layer key management process that has registered with the
       kernel via an SADB_REGISTER message.  This ACQUIRE message will have
       a sequence number associated with it.  This sequence number MUST be
       used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages, in
       order to keep track of which request gets its keying material.  The
       sequence number (described below) is similar to a transaction ID in a

    McDonald, et. al.            Informational                      [Page 9]

    RFC 2367               PF_KEY Key Management API               July 1998

       remote procedure call.

       The SADB_EXPIRE message is sent from the kernel to key management
       applications when the "soft lifetime" or "hard lifetime" of a
       Security Association has expired.  Key management applications should
       use receipt of a soft lifetime SADB_EXPIRE message as a hint to
       negotiate a replacement SA so the replacement SA will be ready and in
       the kernel before it is needed.

       A SADB_DUMP message is also defined, but this is primarily intended
       for PF_KEY implementor debugging and is not used in ordinary
       operation of PF_KEY.

    1.6 Differences Between PF_KEY and PF_ROUTE

       The following bullets are points of difference between the routing
       socket and PF_KEY.  Programmers who are used to the routing socket
       semantics will find some differences in PF_KEY.

       * PF_KEY message errors are usually returned in PF_KEY messages
         instead of causing write() operations to fail and returning the
         error number in errno. This means that other listeners on a PF_KEY
         socket can be aware that requests from another process failed,
         which can be useful for auditing purposes. This also means that
         applications that fail to read PF_KEY messages cannot do error
         checking.

         An implementation MAY return the errors EINVAL, ENOMEM, and ENOBUFS
         by causing write() operations to fail and returning the error
         number in errno.  This is an optimization for common error cases in
         which it does not make sense for any other process to receive the
         error.  An application MUST NOT depend on such errors being set by
         the write() call, but it SHOULD check for such errors, and handle
         them in an appropriate manner.

       * The entire message isn't always reflected in the reply. A SADB_ADD
         message is an example of this.

       * The PID is not set by the kernel.  The process that originates the
         message MUST set the sadb_msg_pid to its own PID.  If the kernel
         ORIGINATES a message, it MUST set the sadb_msg_pid to 0.  A reply
         to an original message SHOULD have the pid of the original message.
         (E.g. the kernel's response to an SADB_ADD SHOULD have its pid set
         to the pid value of the original SADB_ADD message.)

    McDonald, et. al.            Informational                     [Page 10]

    RFC 2367               PF_KEY Key Management API               July 1998

    1.7 Name Space

       All PF_KEYv2 preprocessor symbols and structure definitions are
       defined as a result of including the header file <net/pfkeyv2.h>.
       There is exactly one exception to this rule: the symbol "PF_KEY" (two
       exceptions if "AF_KEY" is also counted), which is defined as a result
       of including the header file <sys/socket.h>.  All PF_KEYv2
       preprocessor symbols start with the prefix "SADB_" and all structure
       names start with "sadb_". There are exactly two exceptions to this
       rule: the symbol "PF_KEY_V2" and the symbol "PFKEYV2_REVISION".

       The symbol "PFKEYV2_REVISION" is a date-encoded value not unlike
       certain values defined by POSIX and X/Open.  The current value for
       PFKEYV2_REVISION is 199806L, where 1998 is the year and 06 is the
       month.

       Inclusion of the file <net/pfkeyv2.h> MUST NOT define symbols or
       structures in the PF_KEYv2 name space that are not described in this
       document without the explicit prior permission of the authors.  Any
       symbols or structures in the PF_KEYv2 name space that are not
       described in this document MUST start with "SADB_X_" or "sadb_x_". An
       implementation that fails to obey these rules IS NOT COMPLIANT WITH
       THIS SPECIFICATION and MUST NOT make any claim to be.  These rules
       also apply to any files that might be included as a result of
       including the file <net/pfkeyv2.h>. This rule provides implementors
       with some assurance that they will not encounter namespace-related
       surprises.

    1.8 On Manual Keying

       Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows an
       application full-reign over the security associations in a kernel
       that implements PF_KEY.  A PF_KEY implementation MUST have some sort
       of manual interface to PF_KEY, which SHOULD allow all of the
       functionality of the programmatic interface described here.

    2. PF_KEY Message Format

       PF_KEY messages consist of a base header followed by additional data
       fields, some of which may be optional.  The format of the additional
       data is dependent on the type of message.

       PF_KEY messages currently do not mandate any specific ordering for
       non-network multi-octet fields.  Unless otherwise specified (e.g. SPI
       values), fields MUST be in host-specific byte order.

    McDonald, et. al.            Informational                     [Page 11]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.1 Base Message Header Format

       PF_KEY messages consist of the base message header followed by
       security association specific data whose types and lengths are
       specified by a generic type-length encoding.

       This base header is shown below, using POSIX types.  The fields are
       arranged primarily for alignment, and where possible, for reasons of
       clarity.

               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;
               };
               /* sizeof(struct sadb_msg) == 16 */

       sadb_msg_version
                       The version field of this PF_KEY message. This MUST
                       be set to PF_KEY_V2. If this is not set to PF_KEY_V2,
                       the write() call MAY fail and return EINVAL.
                       Otherwise, the behavior is undetermined, given that
                       the application might not understand the formatting
                       of the messages arriving from the kernel.

       sadb_msg_type   Identifies the type of message. The valid message
                       types are described later in this document.

       sadb_msg_errno  Should be set to zero by the sender. The responder
                       stores the error code in this field if an error has
                       occurred. This includes the case where the responder
                       is in user space. (e.g. user-space negotiation
                       fails, an errno can be returned.)

       sadb_msg_satype Indicates the type of security association(s). Valid
                       Security Association types are declared in the file
                       <net/pfkeyv2.h>. The current set of Security
                       Association types is enumerated later in this
                       document.

    McDonald, et. al.            Informational                     [Page 12]

    RFC 2367               PF_KEY Key Management API               July 1998

       sadb_msg_len    Contains the total length, in 64-bit words, of all
                       data in the PF_KEY message including the base header
                       length and additional data after the base header, if
                       any. This length includes any padding or extra space
                       that might exist. Unless otherwise stated, all other
                       length fields are also measured in 64-bit words.

                       On user to kernel messages, this field MUST be
                       verified against the length of the inbound message.
                       EMSGSIZE MUST be returned if the verification fails.
                       On kernel to user messages, a size mismatch is most
                       likely the result of the user not providing a large
                       enough buffer for the message. In these cases, the
                       user application SHOULD drop the message, but it MAY
                       try and extract what information it can out of the
                       message.

       sadb_msg_reserved
                       Reserved value. It MUST be zeroed by the sender. All
                       fields labeled reserved later in the document have
                       the same semantics as this field.

       sadb_msg_seq    Contains the sequence number of this message. This
                       field, along with sadb_msg_pid, MUST be used to
                       uniquely identify requests to a process. The sender
                       is responsible for filling in this field. This
                       responsibility also includes matching the
                       sadb_msg_seq of a request (e.g. SADB_ACQUIRE).

                       This field is similar to a transaction ID in a
                       remote procedure call implementation.

       sadb_msg_pid    Identifies the process which originated this message,
                       or which process a message is bound for.  For
                       example, if process id 2112 sends an SADB_UPDATE
                       message to the kernel, the process MUST set this
                       field to 2112 and the kernel will set this field
                       to 2112 in its reply to that SADB_UPDATE
                       message. This field, along with sadb_msg_seq, can
                       be used to uniquely identify requests to a
                       process.

                       It is currently assumed that a 32-bit quantity will
                       hold an operating system's process ID space.

    McDonald, et. al.            Informational                     [Page 13]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.2 Alignment of Headers and Extension Headers

       The base message header is a multiple of 64 bits and fields after it
       in memory will be 64 bit aligned if the base itself is 64 bit
       aligned.  Some of the subsequent extension headers have 64 bit fields
       in them, and as a consequence need to be 64 bit aligned in an
       environment where 64 bit quantities need to be 64 bit aligned.

       The basic unit of alignment and length in PF_KEY Version 2 is 64
       bits. Therefore:

         * All extension headers, inclusive of the sadb_ext overlay fields,
           MUST be a multiple of 64 bits long.

         * All variable length data MUST be padded appropriately such that
           its length in a message is a multiple of 64 bits.

         * All length fields are, unless otherwise specified, in units of
           64 bits.

         * Implementations may safely access quantities of between 8 and 64
           bits directly within a message without risk of alignment faults.

       All PF_KEYv2 structures are packed and already have all intended
       padding.  Implementations MUST NOT insert any extra fields, including
       hidden padding, into any structure in this document.  This forbids
       implementations from "extending" or "enhancing" existing headers
       without changing the extension header type. As a guard against such
       insertion of silent padding, each structure in this document is
       labeled with its size in bytes. The size of these structures in an
       implementation MUST match the size listed.

    2.3 Additional Message Fields

       The additional data following the base header consists of various
       length-type-values fields.  The first 32-bits are of a constant form:

               struct sadb_ext {
                       uint16_t sadb_ext_len;
                       uint16_t sadb_ext_type;
               };
               /* sizeof(struct sadb_ext) == 4 */

       sadb_ext_len    Length of the extension header in 64 bit words,
                       inclusive.

    McDonald, et. al.            Informational                     [Page 14]

    RFC 2367               PF_KEY Key Management API               July 1998

       sadb_ext_type   The type of extension header that follows. Values for
                       this field are detailed later. The value zero is
                       reserved.

       Types of extension headers include: Association, Lifetime(s),
       Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and
       Supported. There MUST be only one instance of a extension type in a
       message.  (e.g.  Base, Key, Lifetime, Key is forbidden).  An EINVAL
       will be returned if there are duplicate extensions within a message.
       Implementations MAY enforce ordering of extensions in the order
       presented in the EXTENSION HEADER VALUES section.

       If an unknown extension type is encountered, it MUST be ignored.
       Applications using extension headers not specified in this document
       MUST be prepared to work around other system components not
       processing those headers.  Likewise, if an application encounters an
       unknown extension from the kernel, it must be prepared to work around
       it.  Also, a kernel that generates extra extension header types MUST
       NOT _depend_ on applications also understanding extra extension
       header types.

       All extension definitions include these two fields (len and exttype)
       because they are instances of a generic extension (not unlike
       sockaddr_in and sockaddr_in6 are instances of a generic sockaddr).
       The sadb_ext header MUST NOT ever be present in a message without at
       least four bytes of extension header data following it, and,
       therefore, there is no problem with it being only four bytes long.

       All extensions documented in this section MUST be implemented by a
       PF_KEY implementation.

    2.3.1 Association Extension

       The Association extension specifies data specific to a single
       security association. The only times this extension is not present is
       when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being
       passed and on the SADB_ACQUIRE message.

               struct sadb_sa {
                       uint16_t sadb_sa_len;
                       uint16_t sadb_sa_exttype;
                       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;
               };

    McDonald, et. al.            Informational                     [Page 15]

    RFC 2367               PF_KEY Key Management API               July 1998

               /* sizeof(struct sadb_sa) == 16 */

       sadb_sa_spi     The Security Parameters Index value for the security
                       association. Although this is a 32-bit field, some
                       types of security associations might have an SPI or
                       key identifier that is less than 32-bits long. In
                       this case, the smaller value shall be stored in the
                       least significant bits of this field and the unneeded
                       bits shall be zero. This field MUST be in network
                       byte order.

       sadb_sa_replay  The size of the replay window, if not zero. If zero,
                       then no replay window is in use.

       sadb_sa_state   The state of the security association. The currently
                       defined states are described later in this document.

       sadb_sa_auth    The authentication algorithm to be used with this
                       security association. The valid authentication
                       algorithms are described later in this document. A
                       value of zero means that no authentication is used
                       for this security association.

       sadb_sa_encrypt The encryption algorithm to be used with this
                       security association. The valid encryption algorithms
                       are described later in this document. A value of zero
                       means that no encryption is used for this security
                       association.

       sadb_sa_flags   A bitmap of options defined for the security
                       association. The currently defined flags are
                       described later in this document.

       The kernel MUST check these values where appropriate. For example,
       IPsec AH with no authentication algorithm is probably an error.

       When used with some messages, the values in some fields in this
       header should be ignored.

    2.3.2 Lifetime Extension

       The Lifetime extension specifies one or more lifetime variants for
       this security association.  If no Lifetime extension is present the
       association has an infinite lifetime.  An association SHOULD have a
       lifetime of some sort associated with it.  Lifetime variants come in
       three varieties, HARD - indicating the hard-limit expiration, SOFT -
       indicating the soft-limit expiration, and CURRENT - indicating the
       current state of a given security association.  The Lifetime

    McDonald, et. al.            Informational                     [Page 16]

    RFC 2367               PF_KEY Key Management API               July 1998

       extension looks like:

               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;
               };
               /* sizeof(struct sadb_lifetime) == 32 */

       sadb_lifetime_allocations
                       For CURRENT, the number of different connections,
                       endpoints, or flows that the association has been
                       allocated towards. For HARD and SOFT, the number of
                       these the association may be allocated towards
                       before it expires. The concept of a connection,
                       flow, or endpoint is system specific.

       sadb_lifetime_bytes
                       For CURRENT, how many bytes have been processed
                       using this security association. For HARD and SOFT,
                       the number of bytes that may be processed using
                       this security association before it expires.

       sadb_lifetime_addtime
                       For CURRENT, the time, in seconds, when the
                       association was created. For HARD and SOFT, the
                       number of seconds after the creation of the
                       association until it expires.

                       For such time fields, it is assumed that 64-bits is
                       sufficiently large to hold the POSIX time_t value.
                       If this assumption is wrong, this field will have to
                       be revisited.

       sadb_lifetime_usetime
                       For CURRENT, the time, in seconds, when association
                       was first used. For HARD and SOFT, the number of
                       seconds after the first use of the association until
                       it expires.

       The semantics of lifetimes are inclusive-OR, first-to-expire.  This
       means that if values for bytes and time, or multiple times, are
       passed in, the first of these values to be reached will cause a
       lifetime expiration.

    McDonald, et. al.            Informational                     [Page 17]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.3.3 Address Extension

       The Address extension specifies one or more addresses that are
       associated with a security association. Address extensions for both
       source and destination MUST be present when an Association extension
       is present. The format of an Address extension is:

               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;
               };
               /* sizeof(struct sadb_address) == 8 */

               /* followed by some form of struct sockaddr */

       The sockaddr structure SHOULD conform to the sockaddr structure of
       the system implementing PF_KEY. If the system has an sa_len field, so
       SHOULD the sockaddrs in the message. If the system has NO sa_len
       field, the sockaddrs SHOULD NOT have an sa_len field. All non-address
       information in the sockaddrs, such as sin_zero for AF_INET sockaddrs,
       and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out.  The
       zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all
       messages except for originating SADB_ACQUIRE messages, which SHOULD
       fill them in with ports from the relevant TCP or UDP session which
       generates the ACQUIRE message.  If the ports are non-zero, then the
       sadb_address_proto field, normally zero, MUST be filled in with the
       transport protocol's number.  If the sadb_address_prefixlen is non-
       zero, then the address has a prefix (often used in KM access control
       decisions), with length specified in sadb_address_prefixlen.  These
       additional fields may be useful to KM applications.

       The SRC and DST addresses for a security association MUST be in the
       same protocol family and MUST always be present or absent together in
       a message.  The PROXY address MAY be in a different protocol family,
       and for most security protocols, represents an actual originator of a
       packet.  (For example, the inner-packets's source address in a
       tunnel.)

       The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY)
       address.  The DST address can be any valid destination address
       (unicast, multicast, or even broadcast). The PROXY address SHOULD be
       a unicast address (there are experimental security protocols where
       PROXY semantics may be different than described above).

    McDonald, et. al.            Informational                     [Page 18]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.3.4 Key Extension

       The Key extension specifies one or more keys that are associated with
       a security association.  A Key extension will not always be present
       with messages, because of security risks.  The format of a Key
       extension is:

               struct sadb_key {
                       uint16_t sadb_key_len;
                       uint16_t sadb_key_exttype;
                       uint16_t sadb_key_bits;
                       uint16_t sadb_key_reserved;
               };
               /* sizeof(struct sadb_key) == 8 */

               /* followed by the key data */

       sadb_key_bits   The length of the valid key data, in bits. A value of
                       zero in sadb_key_bits MUST cause an error.

       The key extension comes in two varieties. The AUTH version is used
       with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT
       version is used with encryption keys (e.g. IPsec ESP).  PF_KEY deals
       only with fully formed cryptographic keys, not with "raw key
       material". For example, when ISAKMP/Oakley is in use, the key
       management daemon is always responsible for transforming the result
       of the Diffie-Hellman computation into distinct fully formed keys
       PRIOR to sending those keys into the kernel via PF_KEY.  This rule is
       made because PF_KEY is designed to support multiple security
       protocols (not just IP Security) and also multiple key management
       schemes including manual keying, which does not have the concept of
       "raw key material".  A clean, protocol-independent interface is
       important for portability to different operating systems as well as
       for portability to different security protocols.

       If an algorithm defines its key to include parity bits (e.g.  DES)
       then the key used with PF_KEY MUST also include those parity bits.
       For example, this means that a single DES key is always a 64-bit
       quantity.

       When a particular security protocol only requires one authentication
       and/or one encryption key, the fully formed key is transmitted using
       the appropriate key extension.  When a particular security protocol
       requires more than one key for the same function (e.g. Triple-DES
       using 2 or 3 keys, and asymmetric algorithms), then those two fully
       formed keys MUST be concatenated together in the order used for
       outbound packet processing. In the case of multiple keys, the
       algorithm MUST be able to determine the lengths of the individual

    McDonald, et. al.            Informational                     [Page 19]

    RFC 2367               PF_KEY Key Management API               July 1998

       keys based on the information provided.  The total key length (when
       combined with knowledge of the algorithm in use) usually provides
       sufficient information to make this determination.

       Keys are always passed through the PF_KEY interface in the order that
       they are used for outbound packet processing. For inbound processing,
       the correct order that keys are used might be different from this
       canonical concatenation order used with the PF_KEY interface. It is
       the responsibility of the implementation to use the keys in the
       correct order for both inbound and outbound processing.

       For example, consider a pair of nodes communicating unicast using an
       ESP three-key Triple-DES Security Association. Both the outbound SA
       on the sender node, and the inbound SA on the receiver node will
       contain key-A, followed by key-B, followed by key-C in their
       respective ENCRYPT key extensions. The outbound SA will use key-A
       first, followed by key-B, then key-C when encrypting. The inbound SA
       will use key-C, followed by key-B, then key-A when decrypting.
       (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.)
       The canonical ordering of key-A, key-B, key-C is used for 3DES, and
       should be documented.  The order of "encryption" is the canonical
       order for this example. [Sch96]

       The key data bits are arranged most-significant to least significant.
       For example, a 22-bit key would take up three octets, with the least
       significant two bits not containing key material. Five additional
       octets would then be used for padding to the next 64-bit boundary.

       While not directly related to PF_KEY, there is a user interface issue
       regarding odd-digit hexadecimal representation of keys.  Consider the
       example of the 16-bit number:

               0x123

       That will require two octets of storage. In the absence of other
       information, however, unclear whether the value shown is stored as:

               01 23           OR              12 30

       It is the opinion of the authors that the former (0x123 == 0x0123) is
       the better way to interpret this ambiguity. Extra information (for
       example, specifying 0x0123 or 0x1230, or specifying that this is only
       a twelve-bit number) would solve this problem.

    McDonald, et. al.            Informational                     [Page 20]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.3.5 Identity Extension

       The Identity extension contains endpoint identities.  This
       information is used by key management to select the identity
       certificate that is used in negotiations. This information may also
       be provided by a kernel to network security aware applications to
       identify the remote entity, possibly for access control purposes.  If
       this extension is not present, key management MUST assume that the
       addresses in the Address extension are the only identities for this
       Security Association. The Identity extension looks like:

               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;
               };
               /* sizeof(struct sadb_ident) == 16 */

               /* followed by the identity string, if present */

       sadb_ident_type The type of identity information that follows.
                       Currently defined identity types are described later
                       in this document.

       sadb_ident_id   An identifier used to aid in the construction of an
                       identity string if none is present.  A POSIX user id
                       value is one such identifier that will be used in this
                       field.  Use of this field is described later in this
                       document.

       A C string containing a textual representation of the identity
       information optionally follows the sadb_ident extension.  The format
       of this string is determined by the value in sadb_ident_type, and is
       described later in this document.

    2.3.6 Sensitivity Extension

       The Sensitivity extension contains security labeling information for
       a security association.  If this extension is not present, no
       sensitivity-related data can be obtained from this security
       association.  If this extension is present, then the need for
       explicit security labeling on the packet is obviated.

               struct sadb_sens {
                       uint16_t sadb_sens_len;
                       uint16_t sadb_sens_exttype;

    McDonald, et. al.            Informational                     [Page 21]

    RFC 2367               PF_KEY Key Management API               July 1998

                       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;
                       uint32_t sadb_sens_reserved;
               };
               /* sizeof(struct sadb_sens) == 16 */

               /* followed by:
                       uint64_t sadb_sens_bitmap[sens_len];
                       uint64_t sadb_integ_bitmap[integ_len]; */

       sadb_sens_dpd   Describes the protection domain, which allows
                       interpretation of the levels and compartment
                       bitmaps.
       sadb_sens_sens_level
                       The sensitivity level.
       sadb_sens_sens_len
                       The length, in 64 bit words, of the sensitivity
                       bitmap.
       sadb_sens_integ_level
                       The integrity level.
       sadb_sens_integ_len
                       The length, in 64 bit words, of the integrity
                       bitmap.

       This sensitivity extension is designed to support the Bell-LaPadula
       [BL74] security model used in compartmented-mode or multi-level
       secure systems, the Clark-Wilson [CW87] commercial security model,
       and/or the Biba integrity model [Biba77]. These formal models can be
       used to implement a wide variety of security policies. The definition
       of a particular security policy is outside the scope of this
       document.  Each of the bitmaps MUST be padded to a 64-bit boundary if
       they are not implicitly 64-bit aligned.

    2.3.7 Proposal Extension

       The Proposal extension contains a "proposed situation" of algorithm
       preferences.  It looks like:

               struct sadb_prop {
                       uint16_t sadb_prop_len;
                       uint16_t sadb_prop_exttype;
                       uint8_t sadb_prop_replay;
                       uint8_t sadb_prop_reserved[3];
               };
               /* sizeof(struct sadb_prop) == 8 */

    McDonald, et. al.            Informational                     [Page 22]

    RFC 2367               PF_KEY Key Management API               July 1998

               /* followed by:
                  struct sadb_comb sadb_combs[(sadb_prop_len *
                      sizeof(uint64_t) - sizeof(struct sadb_prop)) /
                      sizeof(struct sadb_comb)]; */

       Following the header is a list of proposed parameter combinations in
       preferential order.  The values in these fields have the same
       definition as the fields those values will move into if the
       combination is chosen.

           NOTE: Some algorithms in some security protocols will have
                 variable IV lengths per algorithm.  Variable length IVs
                 are not supported by PF_KEY v2.  If they were, however,
                 proposed IV lengths would go in the Proposal Extension.

       These combinations look like:

               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;
               };

               /* sizeof(struct sadb_comb) == 72 */

       sadb_comb_auth  If this combination is accepted, this will be the
                       value of sadb_sa_auth.

       sadb_comb_encrypt
                       If this combination is accepted, this will be the
                       value of sadb_sa_encrypt.

    McDonald, et. al.            Informational                     [Page 23]

    RFC 2367               PF_KEY Key Management API               July 1998

       sadb_comb_auth_minbits;
       sadb_comb_auth_maxbits;
                       The minimum and maximum acceptable authentication
                       key lengths, respectably, in bits. If sadb_comb_auth
                       is zero, both of these values MUST be zero. If
                       sadb_comb_auth is nonzero, both of these values MUST
                       be nonzero. If this combination is accepted, a value
                       between these (inclusive) will be stored in the
                       sadb_key_bits field of KEY_AUTH. The minimum MUST
                       NOT be greater than the maximum.

       sadb_comb_encrypt_minbits;
       sadb_comb_encrypt_maxbits;
                       The minimum and maximum acceptable encryption key
                       lengths, respectably, in bits. If sadb_comb_encrypt
                       is zero, both of these values MUST be zero. If
                       sadb_comb_encrypt is nonzero, both of these values
                       MUST be nonzero. If this combination is accepted, a
                       value between these (inclusive) will be stored in
                       the sadb_key_bits field of KEY_ENCRYPT. The minimum
                       MUST NOT be greater than the maximum.

       sadb_comb_soft_allocations
       sadb_comb_hard_allocations
                       If this combination is accepted, these are proposed
                       values of sadb_lifetime_allocations in the SOFT and
                       HARD lifetimes, respectively.

       sadb_comb_soft_bytes
       sadb_comb_hard_bytes
                       If this combination is accepted, these are proposed
                       values of sadb_lifetime_bytes in the SOFT and HARD
                       lifetimes, respectively.

       sadb_comb_soft_addtime
       sadb_comb_hard_addtime
                       If this combination is accepted, these are proposed
                       values of sadb_lifetime_addtime in the SOFT and HARD
                       lifetimes, respectively.

       sadb_comb_soft_usetime
       sadb_comb_hard_usetime
                       If this combination is accepted, these are proposed
                       values of sadb_lifetime_usetime in the SOFT and HARD
                       lifetimes, respectively.

    McDonald, et. al.            Informational                     [Page 24]

    RFC 2367               PF_KEY Key Management API               July 1998

       Each combination has an authentication and encryption algorithm,
       which may be 0, indicating none.  A combination's flags are the same
       as the flags in the Association extension.  The minimum and maximum
       key lengths (which are in bits) are derived from possible a priori
       policy decisions, along with basic properties of the algorithm.
       Lifetime attributes are also included in a combination, as some
       algorithms may know something about their lifetimes and can suggest
       lifetime limits.

    2.3.8 Supported Algorithms Extension

       The Supported Algorithms extension contains a list of all algorithms
       supported by the system. This tells key management what algorithms it
       can negotiate. Available authentication algorithms are listed in the
       SUPPORTED_AUTH extension and available encryption algorithms are
       listed in the SUPPORTED_ENCRYPT extension. The format of these
       extensions is:

               struct sadb_supported {
                       uint16_t sadb_supported_len;
                       uint16_t sadb_supported_exttype;
                       uint32_t sadb_supported_reserved;
               };
               /* sizeof(struct sadb_supported) == 8 */

               /* followed by:
                  struct sadb_alg sadb_algs[(sadb_supported_len *
                      sizeof(uint64_t) - sizeof(struct sadb_supported)) /
                      sizeof(struct sadb_alg)]; */

         This header is followed by one or more algorithm  descriptions.  An
       algorithm description looks like:

               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;
               };
               /* sizeof(struct sadb_alg) == 8 */

       sadb_alg_id    The algorithm identification value for this
                      algorithm. This is the value that is stored in
                      sadb_sa_auth or sadb_sa_encrypt if this algorithm is
                      selected.

    McDonald, et. al.            Informational                     [Page 25]

    RFC 2367               PF_KEY Key Management API               July 1998

       sadb_alg_ivlen The length of the initialization vector to be used
                      for the algorithm. If an IV is not needed, this
                      value MUST be set to zero.

       sadb_alg_minbits
                       The minimum acceptable key length, in bits. A value
                       of zero is invalid.

       sadb_alg_maxbits
                       The maximum acceptable key length, in bits. A value
                       of zero is invalid. The minimum MUST NOT be greater
                       than the maximum.

    2.3.9 SPI Range Extension

       One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI
       values.  This extension performs such a function.

               struct sadb_spirange {
                       uint16_t sadb_spirange_len;
                       uint16_t sadb_spirange_exttype;
                       uint32_t sadb_spirange_min;
                       uint32_t sadb_spirange_max;
                       uint32_t sadb_spirange_reserved;
               };
               /* sizeof(struct sadb_spirange) == 16 */

       sadb_spirange_min
                       The minimum acceptable SPI value.

       sadb_spirange_max
                       The maximum acceptable SPI value. The maximum MUST
                       be greater than or equal to the minimum.

    McDonald, et. al.            Informational                     [Page 26]

    RFC 2367               PF_KEY Key Management API               July 1998

    2.4 Illustration of Message Layout

       The following shows how the octets are laid out in a PF_KEY message.
       Optional fields are indicated as such.

       The base header is as follows:

         0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
        +---------------+---------------+---------------+---------------+
        |  ...version   | sadb_msg_type | sadb_msg_errno| ...msg_satype |
        +---------------+---------------+---------------+---------------+
        |          sadb_msg_len         |       sadb_msg_reserved       |
        +---------------+---------------+---------------+---------------+
        |                         sadb_msg_seq                          |
        +---------------+---------------+---------------+---------------+
        |                         sadb_msg_pid                          |
        +---------------+---------------+---------------+---------------+

       The base header may be followed by one or more of the following
       extension fields, depending on the values of various base header
       fields.  The following fields are ordered such that if they appear,
       they SHOULD appear in the order presented below.

       An extension field MUST not be repeated.  If there is a situation
       where an extension MUST be repeated, it should be brought to the
       attention of the authors.

       The Association extension

           0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
           +---------------+---------------+---------------+---------------+
           |          sadb_sa_len          |        sadb_sa_exttype        |
           +---------------+---------------+---------------+---------------+
           |                          sadb_sa_spi                          |
           +---------------+---------------+---------------+---------------+
           |   ...replay   | sadb_sa_state | sadb_sa_auth  |sadb_sa_encrypt|
           +---------------+---------------+---------------+---------------+
           |                         sadb_sa_flags                         |
           +---------------+---------------+---------------+---------------+

       The Lifetime extension

           +---------------+---------------+---------------+---------------+
           |         sadb_lifetime_len     |    sadb_lifetime_exttype      |
           +---------------+---------------+---------------+---------------+
           |                   sadb_lifetime_allocations                   |
           +---------------+---------------+---------------+---------------+

    McDonald, et. al.            Informational                     [Page 27]

    RFC 2367               PF_KEY Key Management API               July 1998

           +---------------+---------------+---------------+---------------+
           |                    sadb_lifetime_bytes                        |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                    sadb_lifetime_addtime                      |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                    sadb_lifetime_usetime                      |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+

       The Address extension

           +---------------+---------------+---------------+---------------+
           |       sadb_address_len        |     sadb_address_exttype      |
           +---------------+---------------+---------------+---------------+
           | _address_proto| ..._prefixlen |     sadb_address_reserved     |
           +---------------+---------------+---------------+---------------+
           >     Some form of 64-bit aligned struct sockaddr goes here.    <
           +---------------+---------------+---------------+---------------+

       The Key extension

           +---------------+---------------+---------------+---------------+
           |         sadb_key_len          |         sadb_key_exttype      |
           +---------------+---------------+---------------+---------------+
           |        sadb_key_bits          |        sadb_key_reserved      |
           +---------------+---------------+---------------+---------------+
           >    A key, padded to 64-bits, most significant bits to least.  >
           +---------------+---------------+---------------+---------------+

       The Identity extension

           +---------------+---------------+---------------+---------------+
           |        sadb_ident_len         |      sadb_ident_exttype       |
           +---------------+---------------+---------------+---------------+
           |        sadb_ident_type        |      sadb_ident_reserved      |
           +---------------+---------------+---------------+---------------+
           |                         sadb_ident_id                         |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           >  A null-terminated C-string which MUST be padded out for      >
           <  64-bit alignment.                                            <
           +---------------+---------------+---------------+---------------+

    McDonald, et. al.            Informational                     [Page 28]

    RFC 2367               PF_KEY Key Management API               July 1998

       The Sensitivity extension

           +---------------+---------------+---------------+---------------+
           |         sadb_sens_len         |      sadb_sens_exttype        |
           +---------------+---------------+---------------+---------------+
           |                         sadb_sens_dpd                         |
           +---------------+---------------+---------------+---------------+
           | ...sens_level | ...sens_len   |..._integ_level| ..integ_len   |
           +---------------+---------------+---------------+---------------+
           |                       sadb_sens_reserved                      |
           +---------------+---------------+---------------+---------------+
           >    The sensitivity bitmap, followed immediately by the        <
           <    integrity bitmap, each is an array of uint64_t.            >
           +---------------+---------------+---------------+---------------+

       The Proposal extension

           +---------------+---------------+---------------+---------------+
           |         sadb_prop_len         |       sadb_prop_exttype       |
           +---------------+---------------+---------------+---------------+
           |...prop_replay |           sadb_prop_reserved                  |
           +---------------+---------------+---------------+---------------+
           >     One or more combinations, specified as follows...         <
           +---------------+---------------+---------------+---------------+

           Combination
           +---------------+---------------+---------------+---------------+
           |sadb_comb_auth |sadb_comb_encr |        sadb_comb_flags        |
           +---------------+---------------+---------------+---------------+
           |    sadb_comb_auth_minbits     |     sadb_comb_auth_maxbits    |
           +---------------+---------------+---------------+---------------+
           |   sadb_comb_encrypt_minbits   |    sadb_comb_encrypt_maxbits  |
           +---------------+---------------+---------------+---------------+
           |                       sadb_comb_reserved                      |
           +---------------+---------------+---------------+---------------+
           |                   sadb_comb_soft_allocations                  |
           +---------------+---------------+---------------+---------------+
           |                   sadb_comb_hard_allocations                  |
           +---------------+---------------+---------------+---------------+
           |                      sadb_comb_soft_bytes                     |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                      sadb_comb_hard_bytes                     |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                     sadb_comb_soft_addtime                    |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+

    McDonald, et. al.            Informational                     [Page 29]

    RFC 2367               PF_KEY Key Management API               July 1998

           +---------------+---------------+---------------+---------------+
           |                     sadb_comb_hard_addtime                    |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                     sadb_comb_soft_usetime                    |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+
           |                     sadb_comb_hard_usetime                    |
           |                           (64 bits)                           |
           +---------------+---------------+---------------+---------------+

       The Supported Algorithms extension

           +---------------+---------------+---------------+---------------+
           |      sadb_supported_len       |     sadb_supported_exttype    |
           +---------------+---------------+---------------+---------------+
           |                    sadb_supported_reserved                    |
           +---------------+---------------+---------------+---------------+

          Followed by one or more Algorithm Descriptors

           +---------------+---------------+---------------+---------------+
           |  sadb_alg_id  | sadb_alg_ivlen|       sadb_alg_minbits        |
           +---------------+---------------+---------------+---------------+
           |        sadb_alg_maxbits       |       sadb_alg_reserved       |
           +---------------+---------------+---------------+---------------+

       The SPI Range extension

           +---------------+---------------+---------------+---------------+
           |       sadb_spirange_len       |     sadb_spirange_exttype     |
           +---------------+---------------+---------------+---------------+
           |                      sadb_spirange_min                        |
           +---------------+---------------+---------------+---------------+
           |                      sadb_spirange_max                        |
           +---------------+---------------+---------------+---------------+
           |                    sadb_spirange_reserved                     |
           +---------------+---------------+---------------+---------------+

    3 Symbolic Names

       This section defines various symbols used with PF_KEY and the
       semantics associated with each symbol.  Applications MUST use the
       symbolic names in order to be portable.  The numeric definitions
       shown are for illustrative purposes, unless explicitly stated
       otherwise.  The numeric definition MAY vary on other systems.  The
       symbolic name MUST be kept the same for all conforming
       implementations.

    McDonald, et. al.            Informational                     [Page 30]

    RFC 2367               PF_KEY Key Management API               July 1998

    3.1 Message Types

       The following message types are used with PF_KEY.  These are defined
       in the file <net/pfkeyv2.h>.

               #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   /* not used normally */

               #define SADB_MAX         10

       Each message has a behavior.  A behavior is defined as where the
       initial message travels (e.g. user to kernel), and what subsequent
       actions are expected to take place.  Contents of messages are
       illustrated as:

       <base, REQUIRED EXTENSION, REQ., (OPTIONAL EXT.,) (OPT)>

       The SA extension is sometimes used only for its SPI field.  If all
       other fields MUST be ignored, this is represented by "SA(*)".

       The lifetime extensions are represented with one to three letters
       after the word "lifetime," representing (H)ARD, (S)OFT, and
       (C)URRENT.

       The address extensions are represented with one to three letters
       after the word "address," representing (S)RC, (D)ST, (P)ROXY.

           NOTE: Some security association types do not use a source
                  address for SA identification, where others do.  This may
                  cause EEXIST errors for some SA types where others do not
                  report collisions.  It is expected that application
                  authors know enough about the underlying security
                  association types to understand these differences.

       The key extensions are represented with one or two letters after the
       word "key," representing (A)UTH and (E)NCRYPT.

    McDonald, et. al.            Informational                     [Page 31]

    RFC 2367               PF_KEY Key Management API               July 1998

       The identity extensions are represented with one or two letters after
       the word "identity," representing (S)RC and (D)ST.

       In the case of an error, only the base header is returned.

       Note that any standard error could be returned for any message.

       Typically, they will be either one of the errors specifically listed
       in the description for a message or one of the following:

               EINVAL  Various message improprieties, including SPI ranges
                       that are malformed.
               ENOMEM  Needed memory was not available.
               ENOBUFS Needed memory was not available.
               EMSGSIZ The message exceeds the maximum length allowed.

    3.1.1 SADB_GETSPI

       The SADB_GETSPI message allows a process to obtain a unique SPI value
       for given security association type, source address, and destination
       address.  This message followed by an SADB_UPDATE is one way to
       create a security association (SADB_ADD is the other method).  The
       process specifies the type in the base header, the source and
       destination address in address extension.  If the SADB_GETSPI message
       is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq
       MUST be the same as the SADB_ACQUIRE message.  The application may
       also specify the SPI.  This is done by having the kernel select
       within a range of SPI values by using the SPI range extension.  To
       specify a single SPI value to be verified, the application sets the
       high and low values to be equal.  Permitting range specification is
       important because the kernel can allocate an SPI value based on what
       it knows about SPI values already in use.  The kernel returns the
       same message with the allocated SPI value stored in the spi field of
       an association extension.  The allocate SPI (and destination address)
       refer to a LARVAL security association.  An SADB_UPDATE message can
       later be used to add an entry with the requested SPI value.

       It is recommended that associations that are created with SADB_GETSPI
       SHOULD be automatically deleted within a fixed amount of time if they
       are not updated by an SADB_UPDATE message.  This allows SA storage
       not to get cluttered with larval associations.

         The message behavior of the SADB_GETSPI message is:

            Send an SADB_GETSPI message from a user process to the kernel.

            <base, address, SPI range>

    McDonald, et. al.            Informational                     [Page 32]

    RFC 2367               PF_KEY Key Management API               July 1998

            The kernel returns the SADB_GETSPI message to all listening
            processes.

            <base, SA(*), address(SD)>

         Errors:

            EEXIST  Requested SPI or SPI range is not available or already
                    used.

    3.1.2 SADB_UPDATE Message

       The SADB_UPDATE message allows a process to update the information in
       an existing Security Association.  Since SADB_GETSPI does not allow
       setting of certain parameters, this message is needed to fully form
       the SADB_SASTATE_LARVAL security association created with
       SADB_GETSPI.  The format of the update message is a base header,
       followed by an association header and possibly by several extension
       headers. The kernel searches for the security association with the
       same type, spi, source address and destination address specified in
       the message and updates the Security Association information using
       the content of the SADB_UPDATE message.

       The kernel MAY disallow SADB_UPDATE to succeed unless the message is
       issued from the same socket that created the security association.
       Such enforcement significantly reduces the chance of accidental
       changes to an in-use security association.  Malicious trusted parties
       could still issue an SADB_FLUSH or SADB_DELETE message, but deletion
       of associations is more easily detected and less likely to occur
       accidentally than an erroneous SADB_UPDATE. The counter argument to
       supporting this behavior involves the case where a user-space key
       management application fails and is restarted.  The new instance of
       the application will not have the same socket as the creator of the
       security association.

       The kernel MUST sanity check all significant values submitted in an
       SADB_UPDATE message before changing the SA in its database and MUST
       return EINVAL if any of the values are invalid.  Examples of checks
       that should be performed are DES key parity bits, key length
       checking, checks for keys known to be weak for the specified
       algorithm, and checks for flags or parameters known to be
       incompatible with the specified algorithm.

       Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_UPDATE
       message.  If the original SA is an SADB_SASTATE_LARVAL SA, then any
       value in the SA may be changed except for the source address,
       destination address, and SPI.  If the original SA is an
       SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA

    McDonald, et. al.            Informational                     [Page 33]

    RFC 2367               PF_KEY Key Management API               July 1998

       MUST return EINVAL.  It is not valid for established keying or
       algorithm information to change without the SPI changing, which would
       require creation of a new SA rather than a change to an existing SA.
       Once keying and algorithm information is negotiated, address and
       identity information is fixed for the SA. Therefore, if the original
       SA is an SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state
       field in the SA header and lifetimes (hard, soft, and current) may be
       changed and any attempt to change other values MUST result in an
       error return of EINVAL.

         The message behavior of the SADB_UPDATE message is:

            Send an SADB_UPDATE message from a user process to the kernel.

            <base, SA, (lifetime(HSC),) address(SD), (address(P),)
              key(AE), (identity(SD),) (sensitivity)>

            The kernel returns the SADB_UPDATE message to all listening
            processes.

            <base, SA, (lifetime(HSC),) address(SD), (address(P),)
              (identity(SD),) (sensitivity)>

       The keying material is not returned on the message from the kernel to
       listening sockets because listeners might not have the privileges to
       see such keying material.

         Errors:
             ESRCH   The security association to be updated was not found.
             EINVAL  In addition to other possible causes, this error is
                     returned if sanity checking on the SA values (such
                     as the keys) fails.
             EACCES  Insufficient privilege to update entry. The socket
                     issuing the SADB_UPDATE is not creator of the entry
                         to be updated.

    3.1.3 SADB_ADD

       The SADB_ADD message is nearly identical to the SADB_UPDATE message,
       except that it does not require a previous call to SADB_GETSPI.  The
       SADB_ADD message is used in manual keying applications, and in other
       cases where the uniqueness of the SPI is known immediately.

       An SADB_ADD message is also used when negotiation is finished, and
       the second of a pair of associations is added.  The SPI for this
       association was determined by the peer machine.  The sadb_msg_seq

    McDonald, et. al.            Informational                     [Page 34]

    RFC 2367               PF_KEY Key Management API               July 1998

       MUST be set to the value set in a kernel-generated SADB_ACQUIRE so
       that both associations in a pair are bound to the same ACQUIRE
       request.

       The kernel MUST sanity check all used fields in the SA submitted in
       an SADB_ADD message before adding the SA to its database and MUST
       return EINVAL if any of the values are invalid.

       Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_ADD message.
       SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is not
       sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state.
       Therefore, the sadb_sa_state field of all submitted SAs MUST be
       SADB_SASTATE_MATURE and the kernel MUST return an error if this is
       not true.

         The message behavior of the SADB_ADD message is:

            Send an SADB_ADD message from a user process to the kernel.

            <base, SA, (lifetime(HS),) address(SD), (address(P),)
              key(AE), (identity(SD),) (sensitivity)>

            The kernel returns the SADB_ADD message to all listening
            processes.

            <base, SA, (lifetime(HS),) address(SD), (identity(SD),)
              (sensitivity)>

       The keying material is not returned on the message from the kernel to
       listening sockets because listeners may not have the privileges to
       see such keying material.

         Errors:

            EEXIST  The security association that was to be added already
                    exists.
            EINVAL  In addition to other possible causes, this error is
                    returned if sanity checking on the SA values (such
                    as the keys) fails.

    3.1.4 SADB_DELETE

       The SADB_DELETE message causes the kernel to delete a Security
       Association from the key table.  The delete message consists of the
       base header followed by the association, and the source and
       destination sockaddrs in the address extension.  The kernel deletes
       the security association matching the type, spi, source address, and
       destination address in the message.

    McDonald, et. al.            Informational                     [Page 35]

    RFC 2367               PF_KEY Key Management API               July 1998

         The message behavior for SADB_DELETE is as follows:

            Send an SADB_DELETE message from a user process to the kernel.

            <base, SA(*), address(SD)>

            The kernel returns the SADB_DELETE message to all listening
            processes.

            <base, SA(*), address(SD)>

    3.1.5 SADB_GET

       The SADB_GET message allows a process to retrieve a copy of a
       Security Association from the kernel's key table.  The get message
       consists of the base header follows by the relevant extension fields.
       The Security Association matching the type, spi, source address, and
       destination address is returned.

          The message behavior of the SADB_GET message is:

             Send an SADB_GET message from a user process to the kernel.

             <base, SA(*), address(SD)>

             The kernel returns the SADB_GET message to the socket that sent
             the SADB_GET message.

             <base, SA, (lifetime(HSC),) address(SD), (address(P),) key(AE),
               (identity(SD),) (sensitivity)>

         Errors:
             ESRCH   The sought security association was not found.

    3.1.6 SADB_ACQUIRE

       The SADB_ACQUIRE message is typically sent only by the kernel to key
       socket listeners who have registered their key socket (see
       SADB_REGISTER message).  SADB_ACQUIRE messages can be sent by
       application-level consumers of security associations (such as an
       OSPFv2 implementation that uses OSPF security).  The SADB_ACQUIRE
       message is a base header along with an address extension, possibly an
       identity extension, and a proposal extension. The proposed situation
       contains a list of desirable algorithms that can be used if the
       algorithms in the base header are not available.  The values for the
       fields in the base header and in the security association data which
       follows the base header indicate the properties of the Security
       Association that the listening process should attempt to acquire.  If

    McDonald, et. al.            Informational                     [Page 36]

    RFC 2367               PF_KEY Key Management API               July 1998

       the message originates from the kernel (i.e. the sadb_msg_pid is 0),
       the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and
       SADB_UPDATE, or subsequent SADB_ADD message to bind a security
       association to the request.  This avoids the race condition of two
       TCP connections between two IP hosts that each require unique
       associations, and having one steal another's security association.
       The sadb_msg_errno and sadb_msg_state fields should be ignored by the
       listening process.

       The SADB_ACQUIRE message is typically triggered by an outbound packet
       that needs security but for which there is no applicable Security
       Association existing in the key table.  If the packet can be
       sufficiently protected by more than one algorithm or combination of
       options, the SADB_ACQUIRE message MUST order the preference of
       possibilities in the Proposal extension.

       There are three messaging behaviors for SADB_ACQUIRE.  The first is
       where the kernel needs a security association (e.g. for IPsec).

         The kernel sends an SADB_ACQUIRE message to registered sockets.

            <base, address(SD), (address(P)), (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 when, for some reason, key management fails, it can
       send an ACQUIRE message with the same sadb_msg_seq as the initial
       ACQUIRE with a non-zero errno.

            Send an SADB_ACQUIRE to indicate key management failure.

            <base>

       The third is where an application-layer consumer of security
       associations (e.g.  an OSPFv2 or RIPv2 daemon) needs a security
       association.

            Send an SADB_ACQUIRE message from a user process to the kernel.

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

            The kernel returns an SADB_ACQUIRE message to registered
              sockets.

    McDonald, et. al.            Informational                     [Page 37]

    RFC 2367               PF_KEY Key Management API               July 1998

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

            The user-level consumer waits for an SADB_UPDATE or SADB_ADD
            message for its particular type, and then can use that
            association by using SADB_GET messages.

       Errors:
           EINVAL  Invalid acquire request.
           EPROTONOSUPPORT   No KM application has registered with the Key
                   Engine as being able to obtain the requested SA type, so
                   the requested SA cannot be acquired.

    3.1.7 SADB_REGISTER

       The SADB_REGISTER message allows an application to register its key
       socket as able to acquire new security associations for the kernel.
       SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for
       the type of security association specified in sadb_msg_satype.  The
       application specifies the type of security association that it can
       acquire for the kernel in the type field of its register message.  If
       an application can acquire multiple types of security association, it
       MUST register each type in a separate message. Only the base header
       is needed for the register message.  Key management applications MAY
       register for a type not known to the kernel, because the consumer may
       be in user-space (e.g. OSPFv2 security).

       The reply of the SADB_REGISTER message contains a supported algorithm
       extension.  That field contains an array of supported algorithms, one
       per octet.  This allows key management applications to know what
       algorithm are supported by the kernel.

       In an environment where algorithms can be dynamically loaded and
       unloaded, an asynchronous SADB_REGISTER reply MAY be generated.  The
       list of supported algorithms MUST be a complete list, so the
       application can make note of omissions or additions.

         The messaging behavior of the SADB_REGISTER message is:

            Send an SADB_REGISTER message from a user process to the kernel.

            <base>

            The kernel returns an SADB_REGISTER message to registered
            sockets, with algorithm types supported by the kernel being
            indicated in the supported algorithms field.

    McDonald, et. al.            Informational                     [Page 38]

    RFC 2367               PF_KEY Key Management API               July 1998

            NOTE:  This message may arrive asynchronously due to an
                   algorithm being loaded or unloaded into a dynamically
                   linked kernel.

            <base, supported>

    3.1.8 SADB_EXPIRE Message

       The operating system kernel is responsible for tracking SA
       expirations for security protocols that are implemented inside the
       kernel.  If the soft limit or hard limit of a Security Association
       has expired for a security protocol implemented inside the kernel,
       then the kernel MUST issue an SADB_EXPIRE message to all key socket
       listeners.  If the soft limit or hard limit of a Security Association
       for a user-level security protocol has expired, the user-level
       protocol SHOULD issue an SADB_EXPIRE message.

       The base header will contain the security association information
       followed by the source sockaddr, destination sockaddr, (and, if
       present, internal sockaddr,) (and, if present, one or both
       compartment bitmaps).

       The lifetime extension of an SADB_EXPIRE message is important to
       indicate which lifetime expired.  If a HARD lifetime extension is
       included, it indicates that the HARD lifetime expired.  This means
       the association MAY be deleted already from the SADB.  If a SOFT
       lifetime extension is included, it indicates that the SOFT lifetime
       expired.  The CURRENT lifetime extension will indicate the current
       status, and comparisons to the HARD or SOFT lifetime will indicate
       which limit was reached.  HARD lifetimes MUST take precedence over
       SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same,
       the HARD lifetime will appear on the EXPIRE message.  The
       pathological case of HARD lifetimes being shorter than SOFT lifetimes
       is handled such that the SOFT lifetime will never expire.

         The messaging behavior of the SADB_EXPIRE message is:

               The kernel sends an SADB_EXPIRE message to all listeners when
               the soft limit of a security association has been expired.

               <base, SA, lifetime(C and one of HS), address(SD)>

       Note that the SADB_EXPIRE message is ONLY sent by the kernel to the
       KMd.  It is a one-way informational message that does not have a
       reply.

    McDonald, et. al.            Informational                     [Page 39]

    RFC 2367               PF_KEY Key Management API               July 1998

    3.1.9 SADB_FLUSH

       The SADB_FLUSH message causes the kernel to delete all entries in its
       key table for a certain sadb_msg_satype.  Only the base header is
       required for a flush message.  If sadb_msg_satype is filled in with a
       specific value, only associations of that type are deleted.  If it is
       filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted.

         The messaging behavior for SADB_FLUSH is:

               Send an SADB_FLUSH message from a user process to the kernel.

               <base>

               The kernel will return an SADB_FLUSH message to all listening
               sockets.

               <base>

               The reply message happens only after the actual flushing
               of security associations has been attempted.

    3.1.10 SADB_DUMP

       The SADB_DUMP message causes the kernel to dump the operating
       system's entire Key Table to the requesting key socket. As in
       SADB_FLUSH, if a sadb_msg_satype value is in the message, only
       associations of that type will be dumped. If SADB_SATYPE_UNSPEC is
       specified, all associations will be dumped. Each Security Association
       is returned in its own SADB_DUMP message.  A SADB_DUMP message with a
       sadb_seq field of zero indicates the end of the dump transaction. The
       dump message is used for debugging purposes only and is not intended
       for production use.

       Support for the dump message MAY be discontinued in future versions
       of PF_KEY.  Key management applications MUST NOT depend on this
       message for basic operation.

         The messaging behavior for SADB_DUMP is:

               Send an SADB_DUMP message from a user process to the kernel.

               <base>

               Several SADB_DUMP messages will return from the kernel to the
               sending socket.

    McDonald, et. al.            Informational                     [Page 40]

    RFC 2367               PF_KEY Key Management API               July 1998

               <base, SA, (lifetime (HSC),) address(SD), (address(P),)
                 key(AE), (identity(SD),) (sensitivity)>

    3.2 Security Association Flags

       The Security Association's flags are a bitmask field.  These flags
       also appear in a combination that is part of a PROPOSAL extension.
       The related symbolic definitions below should be used in order that
       applications will be portable:

         #define SADB_SAFLAGS_PFS 1    /* perfect forward secrecy */

       The SADB_SAFLAGS_PFS flag indicates to key management that this
       association should have perfect forward secrecy in its key.  (In
       other words, any given session key cannot be determined by
       cryptanalysis of previous session keys or some master key.)

    3.3 Security Association States

       The security association state field is an integer that describes the
       states of a security association.  They are:

         #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

       A SADB_SASTATE_LARVAL security association is one that was created by
       the SADB_GETSPI message.  A SADB_SASTATE_MATURE association is one
       that was updated with the SADB_UPDATE message or added with the
       SADB_ADD message.  A DYING association is one whose soft lifetime has
       expired.  A SADB_SASTATE_DEAD association is one whose hard lifetime
       has expired, but hasn't been reaped by system garbage collection.  If
       a consumer of security associations has to extend an association
       beyond its normal lifetime (e.g. OSPF Security) it MUST only set the
       soft lifetime for an association.

    3.4 Security Association Types

       This defines the type of Security Association in this message.  The
       symbolic names are always the same, even on different
       implementations.  Applications SHOULD use the symbolic name in order
       to have maximum portability across different implementations.  These
       are defined in the file <net/pfkeyv2.h>.

    McDonald, et. al.            Informational                     [Page 41]

    RFC 2367               PF_KEY Key Management API               July 1998

         #define SADB_SATYPE_UNSPEC        0

         #define SADB_SATYPE_AH            2  /* RFC-1826 */
         #define SADB_SATYPE_ESP           3  /* RFC-1827 */

         #define SADB_SATYPE_RSVP          5  /* RSVP Authentication */
         #define SADB_SATYPE_OSPFV2        6  /* OSPFv2 Authentication */
         #define SADB_SATYPE_RIPV2         7  /* RIPv2 Authentication */
         #define SADB_SATYPE_MIP           8  /* Mobile IP Auth. */

         #define SADB_SATYPE_MAX           8

       SADB_SATYPE_UNSPEC is defined for completeness and means no specific
       type of security association.  This type is never used with PF_KEY
       SAs.

       SADB_SATYPE_AH is for the IP Authentication Header [Atk95b].

       SADB_SATYPE_ESP  is  for  the  IP  Encapsulating   Security   Payload
       [Atk95c].

       SADB_SATYPE_RSVP is for the RSVP Integrity Object.

       SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication
       [Moy98].

       SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97].

       SADB_SATYPE_MIP is for Mobile IP's authentication extensions [Per97].

       SADB_SATYPE_MAX is always set to the highest valid numeric value.

    3.5 Algorithm Types

       The algorithm type is interpreted in the context of the Security
       Association type defined above.  The numeric value might vary between
       implementations, but the symbolic name MUST NOT vary between
       implementations.  Applications should use the symbolic name in order
       to have maximum portability to various implementations.

       Some of the algorithm types defined below might not be standardized
       or might be deprecated in the future.  To obtain an assignment for a
       symbolic name, contact the authors.

         The symbols below are defined in <net/pfkeyv2.h>.

    McDonald, et. al.            Informational                     [Page 42]

    RFC 2367               PF_KEY Key Management API               July 1998

               /* Authentication algorithms */
               #define SADB_AALG_NONE          0
               #define SADB_AALG_MD5HMAC       2
               #define SADB_AALG_SHA1HMAC      3
               #define SADB_AALG_MAX           3

               /* Encryption algorithms */
               #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

       The algorithm for SADB_AALG_MD5_HMAC is defined in [MG98a].  The
       algorithm for SADB_AALG_SHA1HMAC is defined in [MG98b].  The
       algorithm for SADB_EALG_DESCBC is defined in [MD98].  SADB_EALG_NULL
       is the NULL encryption algorithm, defined in [GK98].  The
       SADB_EALG_NONE value is not to be used in any security association
       except those which have no possible encryption algorithm in them
       (e.g. IPsec AH).

    3.6 Extension Header Values

       To briefly recap the extension header values:

               #define SADB_EXT_RESERVED          0
               #define SADB_EXT_SA                1
               #define SADB_EXT_LIFETIME_CURRENT  2
               #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_SUPPORTED_ENCRYPT 15
               #define SADB_EXT_SPIRANGE          16

               #define SADB_EXT_MAX               16

    McDonald, et. al.            Informational                     [Page 43]

    RFC 2367               PF_KEY Key Management API               July 1998

    3.7 Identity Extension Values

       Each identity can have a certain type.

               #define SADB_IDENTTYPE_RESERVED  0
               #define SADB_IDENTTYPE_PREFIX    1
               #define SADB_IDENTTYPE_FQDN      2
               #define SADB_IDENTTYPE_USERFQDN  3

               #define SADB_IDENTTYPE_MAX       3

       The PREFIX identity string consists of a network address followed by a
       forward slash and a prefix length. The network address is in a
       printable numeric form appropriate for the protocol family.  The
       prefix length is a decimal number greater than or equal to zero and
       less than the number of bits in the network address. It indicates the
       number of bits in the network address that are significant; all bits
       in the network address that are not significant MUST be set to zero.
       Note that implementations MUST parse the contents of the printable
       address into a binary form for comparison purposes because multiple
       printable strings are valid representations of the same address in
       many protocol families (for example, some allow leading zeros and some
       have letters that are case insensitive). Examples of PREFIX identities
       are "199.33.248.64/27" and "3ffe::1/128". If the source or destination
       identity is a PREFIX identity, the source or destination address for
       the SA (respectively) MUST be within that prefix.  The sadb_ident_id
       field is zeroed for these identity types.

       The FQDN identity string contains a fully qualified domain name. An
       example FQDN identity is "ministry-of-truth.inner.net".  The
       sadb_ident_id field is zeroed for these identity types.

       The UserFQDN identity consists of a text string in the format commonly
       used for Internet-standard electronic mail. The syntax is the text
       username, followed by the "@" character, followed in turn by the
       appropriate fully qualified domain name.  This identity specifies both
       a username and an associated FQDN. There is no requirement that this
       string specify a mailbox valid for SMTP or other electronic mail
       use. This identity is useful with protocols supporting user-oriented
       keying.  It is a convenient identity form because the DNS Security
       extensions can be used to distribute signed public key values by
       associating KEY and SIG records with an appropriate MB DNS record. An
       example UserFQDN identity is "julia@ministry-of-love.inner.net".  The
       sadb_ident_id field is used to contain a POSIX user id in the absence
       of an identity string itself so that a user-level application can use
       the getpwuid{,_r}() routine to obtain a textual user login id.  If a
       string is present, it SHOULD match the numeric value in the
       sadb_ident_id field.  If it does not match, the string SHOULD override

    McDonald, et. al.            Informational                     [Page 44]

    RFC 2367               PF_KEY Key Management API               July 1998

       the numeric value.

    3.8 Sensitivity Extension Values

       The only field currently defined in the sensitivity extension is the
       sadb_sens_dpd, which represents the data protection domain.  The other
       data in the sensitivity extension is based off the sadb_sens_dpd
       value.

       The DP/DOI is defined to be the same as the "Labeled Domain Identifier
       Value" of the IP Security DOI specification [Pip98]. As noted in that
       specification, values in the range 0x80000000 to 0xffffffff
       (inclusive) are reserved for private use and values in the range
       0x00000001 through 0x7fffffff are assigned by IANA.  The all-zeros
       DP/DOI value is permanently reserved to mean that "no DP/DOI is in
       use".

    3.9 Proposal Extension Values

       These are already mentioned in the Algorithm Types and Security
       Association Flags sections.

    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
       needed.

       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

    McDonald, et. al.            Informational                     [Page 45]

    RFC 2367               PF_KEY Key Management API               July 1998

       particular implementation method.

    5.1 Simple IP Security Example

                         +---------------+    +-------------+
                         |Key Mgmt Daemon|    | Application |
                         +---------------+    +-------------+
                           |           |     /
                           |           |    /
                           |           |    |              Applications
                   ======[PF_KEY]====[PF_INET]==========================
                           |           |    |              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
       generated:

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

       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

    McDonald, et. al.            Informational                     [Page 46]

    RFC 2367               PF_KEY Key Management API               July 1998

       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
       sadb_msg_seq.

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

         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,
                              <etc.>
         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
       extension.

    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.

    McDonald, et. al.            Informational                     [Page 47]

    RFC 2367               PF_KEY Key Management API               July 1998

         Consider this case:

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

         Key:
                   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

    McDonald, et. al.            Informational                     [Page 48]

    RFC 2367               PF_KEY Key Management API               July 1998

         Key:
                   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.

    McDonald, et. al.            Informational                     [Page 49]

    RFC 2367               PF_KEY Key Management API               July 1998

    5.3 OSPF Security Example

               +---------------+    +-------------+
               |Key Mgmt Daemon|    | OSPF daemon |
               +---------------+    +-------------+
                 |           |     /    /        |
                 |    /------|----+    /         |
                 |   /       |    +---+          |           Applications
         ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================
                 |           |    |              |           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
       association:

         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,>
                              proposal
         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.

    McDonald, et. al.            Informational                     [Page 50]

    RFC 2367               PF_KEY Key Management API               July 1998

         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
       overflows.

         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
       internetwork.

       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.

    McDonald, et. al.            Informational                     [Page 51]

    RFC 2367               PF_KEY Key Management API               July 1998

    Acknowledgments

       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 <pf_key-request@inner.net>.

    References

       [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
       1995.

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

       [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.

    McDonald, et. al.            Informational                     [Page 52]

    RFC 2367               PF_KEY Key Management API               July 1998

       [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.

    McDonald, et. al.            Informational                     [Page 53]

    RFC 2367               PF_KEY Key Management API               July 1998

       [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.

    Disclaimer

       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
       specification.

    Authors' Addresses

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

       Phone: +1 650 786 6815
       EMail: danmcd@eng.sun.com

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

       Phone: (DSN) 754-8590
       EMail: cmetz@inner.net

       Bao G. Phan
       U. S. Naval Research Laboratory

       EMail: phan@itd.nrl.navy.mil

    McDonald, et. al.            Informational                     [Page 54]

    RFC 2367               PF_KEY Key Management API               July 1998

    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.

             <base>

             The kernel returns the SADB_X_PROMISC message to all listening
             processes.

    McDonald, et. al.            Informational                     [Page 55]

    RFC 2367               PF_KEY Key Management API               July 1998

             <base>

             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
             process(s).

             <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)>

         Errors:
             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
                   socket.

    McDonald, et. al.            Informational                     [Page 56]

    RFC 2367               PF_KEY Key Management API               July 1998

    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
            sockets.

            <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
            kernel.

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

            The kernel returns an SADB_X_PCHANGE message to registered
            sockets.

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

    McDonald, et. al.            Informational                     [Page 57]

    RFC 2367               PF_KEY Key Management API               July 1998

    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.

    McDonald, et. al.            Informational                     [Page 58]

    RFC 2367               PF_KEY Key Management API               July 1998

    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;

    McDonald, et. al.            Informational                     [Page 59]

    RFC 2367               PF_KEY Key Management API               July 1998

         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;

    McDonald, et. al.            Informational                     [Page 60]

    RFC 2367               PF_KEY Key Management API               July 1998

         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;

    McDonald, et. al.            Informational                     [Page 61]

    RFC 2367               PF_KEY Key Management API               July 1998

         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_CURRENT     2
       #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_SUPPORTED_ENCRYPT    15
       #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

    McDonald, et. al.            Informational                     [Page 62]

    RFC 2367               PF_KEY Key Management API               July 1998

       #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_RESERVED   0
       #define SADB_IDENTTYPE_PREFIX     1
       #define SADB_IDENTTYPE_FQDN       2
       #define SADB_IDENTTYPE_USERFQDN   3
       #define SADB_IDENTTYPE_MAX        3

       #define SADB_KEY_FLAGS_MAX 0
       #endif /* __PFKEY_V2_H */

    McDonald, et. al.            Informational                     [Page 63]

    RFC 2367               PF_KEY Key Management API               July 1998

    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
         lifetimes.

       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:

    McDonald, et. al.            Informational                     [Page 64]

    RFC 2367               PF_KEY Key Management API               July 1998

       * Stronger language about manual keying.

       * PFKEYV2_REVISION, ala POSIX.

       * 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.

    McDonald, et. al.            Informational                     [Page 65]

    RFC 2367               PF_KEY Key Management API               July 1998

       * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER
         FILE).

       * 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
         socket.)

       * 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
         undefined.

       * 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.

    McDonald, et. al.            Informational                     [Page 66]

    RFC 2367               PF_KEY Key Management API               July 1998

       * 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
         number.

    McDonald, et. al.            Informational                     [Page 67]

    RFC 2367               PF_KEY Key Management API               July 1998

    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
       English.

       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
       "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
       TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
       BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
       HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
       MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

    McDonald, et. al.            Informational                     [Page 68]