Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2367

PF_KEY Key Management API, Version 2

Pages: 68
Informational
Errata
Part 2 of 3 – Pages 14 to 45
First   Prev   Next

Top   ToC   RFC2367 - Page 14   prevText
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.
Top   ToC   RFC2367 - Page 15
   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;
           };
Top   ToC   RFC2367 - Page 16
           /* 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
Top   ToC   RFC2367 - Page 17
   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.
Top   ToC   RFC2367 - Page 18
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).
Top   ToC   RFC2367 - Page 19
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
Top   ToC   RFC2367 - Page 20
   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.
Top   ToC   RFC2367 - Page 21
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;
Top   ToC   RFC2367 - Page 22
                   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 */
Top   ToC   RFC2367 - Page 23
           /* 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.
Top   ToC   RFC2367 - Page 24
   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.
Top   ToC   RFC2367 - Page 25
   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.
Top   ToC   RFC2367 - Page 26
   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.
Top   ToC   RFC2367 - Page 27
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                   |
       +---------------+---------------+---------------+---------------+
Top   ToC   RFC2367 - Page 28
       +---------------+---------------+---------------+---------------+
       |                    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.                                            <
       +---------------+---------------+---------------+---------------+
Top   ToC   RFC2367 - Page 29
   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)                           |
       +---------------+---------------+---------------+---------------+
Top   ToC   RFC2367 - Page 30
       +---------------+---------------+---------------+---------------+
       |                     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.
Top   ToC   RFC2367 - Page 31
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.
Top   ToC   RFC2367 - Page 32
   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>
Top   ToC   RFC2367 - Page 33
        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
Top   ToC   RFC2367 - Page 34
   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
Top   ToC   RFC2367 - Page 35
   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.
Top   ToC   RFC2367 - Page 36
     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
Top   ToC   RFC2367 - Page 37
   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.
Top   ToC   RFC2367 - Page 38
        <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.
Top   ToC   RFC2367 - Page 39
        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.
Top   ToC   RFC2367 - Page 40
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.
Top   ToC   RFC2367 - Page 41
           <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>.
Top   ToC   RFC2367 - Page 42
     #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>.
Top   ToC   RFC2367 - Page 43
           /* 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
Top   ToC   RFC2367 - Page 44
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
Top   ToC   RFC2367 - Page 45
   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.



(page 45 continued on part 3)

Next Section