doc: Add RFC documents

1 files changed, 3811 insertions, 0 deletions

diff --git a/doc/rfc/rfc2367.txt b/doc/rfc/rfc2367.txt
new file mode 100644
index 0000000..032702d
--- /dev/null
+++ b/doc/rfc/rfc2367.txt
@@ -0,0 +1,3811 @@
+
+
+
+
+
+
+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]
+