rfc2367.txt

RFC 的详细文档！

   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;