Network Working Group                                    D. L. McDonald
Internet Draft                                               C. W. Metz
draft-mcdonald-pf-key-v2-02.txt                              B. G. Phan
                                                          21 April 1997

                  PF_KEY Key Management API, Version 2


     This document is an Internet Draft.  Internet  Drafts  are  working

     Internet Drafts are draft  documents  valid  for  a  maximum  of  6
   months.   Internet  Drafts  may be updated, replaced, or obsoleted by
   other documents at any time.  It is not appropriate to  use  Internet
   Drafts  as  reference material or to cite them other than as "work in

     A future version of this draft will be submitted to the RFC  Editor
   for publication as an Informational document.


     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. an ISAKMP daemon, a
   Photuris daemon or SKIP certificate discovery protocol daemon).


     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
   SADB).   The  Key  Engine and its structures incorporate the required
   security attributes for a session and are instances of the  "Security
   Association"  concept  described  in [Atk95a].  The names, PF_KEY and

McDonald, Metz, and Phan  Expires in 6 months           [Page 1]

Internet Draft            PF_KEY, Version 2                21 April 1997

   Key Engine, thus refer  to  more  than  cryptographic  keys  and  are
   retained   for   consistency   with   the  traditional  phrase,  "Key

     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  three  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 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  believed  that  it  was important to separate
   security mechanisms (such as PF_KEY) from  security  policies.   This
   permits a single mechanism to more easily support multiple policies.


     Even though this document is not intended to  be  a  standard,  the
   words that are used to define the significance of particular features
   of this proposal are usually capitalized.  These words are:

   - MUST

     This word or the adjective "REQUIRED" means that  the  item  is  an
   absolute requirement of the specification.


     This word or the adjective "RECOMMENDED"  means  that  there  might
   exist  valid reasons in particular circumstances to ignore this item,
   but the full implications should be understood and the case carefully
   weighed before taking a different course.

   - MAY

     This word or the adjective "OPTIONAL" means that this item is truly
   optional.   One  vendor  might  choose  to include the item because a
   particular  marketplace  requires  it  or  because  it  enhances  the
   product, for example; another vendor may omit the same item.

McDonald, Metz, and Phan  Expires in 6 months           [Page 2]

Internet Draft            PF_KEY, Version 2                21 April 1997


     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

     Key management is most commonly implemented in whole or part at the
   application-layer.   For  example,  the  Photuris, ISAKMP, and Oakley
   proposals  for  IPsec  key  management  are   all   application-layer
   protocols.   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, which it
   uses to communicate with the Key Engine, and PF_INET (or PF_INET6  in
   the  case of IPv6), which it uses 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

     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.

                     |Key Mgmt Daemon|
                       |           |
                       |           |
                       |           |                   Applications
                       |           |                   OS Kernel

McDonald, Metz, and Phan  Expires in 6 months           [Page 3]

Internet Draft            PF_KEY, Version 2                21 April 1997

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

                     |Routing  Daemon|
                       |           |
                       |           |
                       |           |                   Applications
                       |           |                   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

McDonald, Metz, and Phan  Expires in 6 months           [Page 4]

Internet Draft            PF_KEY, Version 2                21 April 1997

   before, the key management daemon stores the SA into the Key  Engine.
   Then,  the  trusted privileged application uses a SADB_GET message to
   obtain the SA from the Key Engine.

     In some implementations, policy may be implemented  in  user-space,
   even  though the actually 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  will   not   specify   such

     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.


     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 socket is created as follows:

           #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.   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  a  privileged  user.
   These  systems  SHOULD take steps to restrict the programs allowed to

McDonald, Metz, and Phan  Expires in 6 months           [Page 5]

Internet Draft            PF_KEY, Version 2                21 April 1997

   access the PF_KEY API.


     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 messages sent to the kernel are returned to all open PF_KEY
   sockets,  including  the  sender.  A process can disable this looping
   back of messages it generates by disabling the SO_USELOOPBACK  option
   using  the  setsockopt(2)  call.   A PF_KEY socket listener, which by
   default  receives  all  replies  may  disable  message  reception  by
   terminating  socket  input with the shutdown(2) call.  PF_KEY message
   delivery is not guaranteed,  especially  in  cases  where  kernel  or
   socket buffers are exhausted and messages are dropped.

     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 message  from  the
   kernel,  in  cases where not all PF_KEY sockets are in the same trust

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


     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.

     The second approach to add a  new  Security  Association  into  the
   kernel  is for the application to first request an SPI value from the
   kernel using the SADB_GETSPI message  and  then  send  a  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).

McDonald, Metz, and Phan  Expires in 6 months           [Page 6]

Internet Draft            PF_KEY, Version 2                21 April 1997

     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 a SADB_REGISTER message.  This ACQUIRE message will have a
   sequence number associated with it.  This  sequence  number  MUST  be
   used  by  followup  SADB_GETSPI and SADB_UPDATE messages, in order to
   keep track of which request gets its keying material.   The  sequence
   number (described below) is analogous to a transaction ID in a 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.


     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 subtle differences in PF_KEY.

   * The write() call doesn't return the PF_KEY error number, only the
     return message has the PF_KEY error number in cases of malformed
     fields.  This means that if SO_USELOOPBACK is disabled, error checking
     is hard.

     An implementation MAY use the write() error number to indicate an error,
     but an application MUST not depend on this behavior.

   * The entire message isn't always reflected in the reply.  An SADB_ADD is
     a good 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

McDonald, Metz, and Phan  Expires in 6 months           [Page 7]

Internet Draft            PF_KEY, Version 2                21 April 1997

     originates a message, it MUST set the sadb_msg_pid to 0.


     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.  Fields that may go across the wire
   (e.g. SPI) MUST be in network byte order.


     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

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

   sadb_version    The version field of this PF_KEY message.  This MUST be
                   set to PF_KEY_V2.

   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 replier stores
                   the error code in this field if an error has occured.
                   This includes the case where the replier is in user
                   space.  (E.g. User-space negotiation fails, an errno can
                   be returned.)


McDonald, Metz, and Phan  Expires in 6 months           [Page 8]

Internet Draft            PF_KEY, Version 2                21 April 1997

                   Indicates the type of security association(s) (e.g. AH,
                   ESP, OSPF, etc). Valid Security Association types are
                   declared in the file <net/pfkeyv2.h>. The current set of
                   Security Association types are enumerated later in this

   sadb_msg_len    Contains the total length, in 32-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 32-bit words.

                   If this field mismatches the actual length of data,
                   EMSGSIZE MUST be returned.

                   Reserved value.  It MUST be zeroed by the sender, and it
                   MUST be ignored by the receiver.  All fields labelled
                   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
                   resposibility also includes matching the sadb_msg_seq of
                   a request (e.g. SADB_ACQUIRE).

                   This field is analogous 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 a SADB_UPDATE message to the
                   kernel, the message to the kernel MUST set its process
                   id to 2112, and the SADB_UPDATE reply from the kernel
                   will fill in this fields with 2112.  This field, along
                   with sadb_msg_seq, can be used to uniquely identify
                   requests to a process.

                   It is currently believed that a 32-bit quantity will
                   hold an operating system's process ID space.  If this
                   assumption is not true, then sadb_msg_pid will have to
                   be revisited.

McDonald, Metz, and Phan  Expires in 6 months           [Page 9]

Internet Draft            PF_KEY, Version 2                21 April 1997


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

           struct sadb_hdr {
                   uint16_t sadb_hdr_len;      /* In 32-bit words, inclusive */
                   uint16_t sadb_hdr_hdrtype;  /* 0 is reserved */

   Types  of  extensions  headers  include:  Association,   Lifetime(s),
   Address,  Key, Identity, 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

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


     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

           struct sadb_sa {
                   uint16_t sadb_sa_len;
                   uint16_t sadb_sa_hdrtype;  /* ASSOCIATION */
                   uint32_t sadb_sa_spi;
                   uint8_t sadb_sa_replay_window_len;
                   uint8_t sadb_sa_state;
                   uint8_t sadb_sa_encrypt;
                   uint8_t sadb_sa_auth;
                   uint32_t sadb_sa_flags;

   The sadb_sa_spi field contains the Security  Parameters  Index  value
   for  the  Security Association. Although this is a 32-bit field, some
   types of Security Association 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

   The  sadb_sa_replay_window_len  specifies  the  size  of  the  replay

McDonald, Metz, and Phan  Expires in 6 months          [Page 10]

Internet Draft            PF_KEY, Version 2                21 April 1997

   window, if not zero.  If zero, then no replay window is in use.

   The sadb_sa_state field is an integer field containing the  state  of
   the  Security  Association.  This  field should be set to zero by the
   sending process and is set to the state of the  Security  Association
   when  the  message  is  received.   The  current  set  of  States are
   enumerated later in this document.

   The sadb_sa_encrypt and sadb_sa_auth fields identify  the  encryption
   and  authentication  algorithm(s) used for this security association.
   This can identify that no encryption or authentication  is  used  for
   this  association.   See section 3.4 for values that can be placed in
   this field.  The  kernel  MUST  check  sanity  where  relevant.   For
   example  IPsec  AH  with  no  authentication algorithm is probably an

   The sadb_sa_flags field contains a bitmap of options defined for  the
   security  assocation  (e.g.  replay  protection, PFS, EXPIRED, etc.).
   These flags are enumerated later in this document.


      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  limits  in  a  given  security  association.   The
    Lifetime extension looks like:

            struct sadb_lifetime {
                    uint16_t sadb_lifetime_len;
                    uint16_t sadb_lifetime_hdrtype; /* LIFETIME */
                    uint8_t sadb_lifetime_which; /* Bitmask */
                    uint8_t sadb_lifetime_reserved[3];  /* Padding */

    The sadb_lifetime_which field contains  a  bitmask  indicating  what
    lifetimes;  hard,  soft,  and  current; follow.  A lifetime value is
    encoded as follows:

            struct sadb_lifetime_val {
                    /* The following corresponds to sadb_lifetime_which */
                    uint8_t sadb_lifetime_val_which;
                    uint8_t sadb_lifetime_val_reserved;
                    uint16_t sadb_lifetime_val_allocations;

McDonald, Metz, and Phan  Expires in 6 months          [Page 11]

Internet Draft            PF_KEY, Version 2                21 April 1997

                    uint32_t sadb_lifetime_val_bytes;
                    time_t sadb_lifetime_val_absolute;
                    time_t sadb_lifetime_val_updatetime;
                    time_t sadb_lifetime_val_usetime;

    The sadb_lifetime_val_bytes  field  contains  how  many  bytes  this
    security  association  can  consume  before  it expires for HARD and
    SOFT.  In the case of CURRENT, it indicates how many bytes have been
    consumed.  The sadb_lifetime_val_allocations field contains how many
    different connections, endpoints, or flows  an  association  can  be
    allocated  towards,  or  in  the case of CURRENT, how many times the
    association has been allocated.  (The concept of a connection, flow,
    or  endpoint  is  somewhat  system-specific.)   There are three time
    fields, one indicating absolute expiration time, one indicating time
    after  SA  update,  and  another inidicating time after first use of
    this SA.  The update time and use time will indicate remaining  time
    in  the case of CURRENT, and the assigned limits in the case of HARD
    or SOFT.

    The  semantics  of  lifetimes  are   inclusive-OR,   first-to-expire
    semantics.   This  means  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.


      The Address extension specifies one or  more  addresses  that  are
    associated  with  a security association.  An Address extension MUST
    be present when an Association address is present, and MUST  specify
    at  least the source and destination addresses.  (The source address
    can be INADDR_ANY or it's  IPv6  counterpart.)   The  format  of  an
    Address extension is:

            struct sadb_address {
                    uint16_t sadb_address_len;
                    uint16_t sadb_address_hdrtype; /* ADDRESS */
                    uint8_t sadb_address_which;  /* Bitmask */
                    uint8_t sadb_address_reserved[3];  /* Padding */
                    /* Followed by one or more sockaddr structures. */

    The sadb_address_which field  contains  a  bitmask  indicating  what
    addresses; source, destination, inner-source, inner-destination, and
    proxy; follow.  For each bit set in the sadb_address_which field,  a
    struct sockaddr follows, in the order specified above.  The sockaddr
    structure SHOULD conform to the sockaddr  structure  of  the  system
    implementing  PF_KEY.   (E.g.  If the system has an sa_len field, so

McDonald, Metz, and Phan  Expires in 6 months          [Page 12]

Internet Draft            PF_KEY, Version 2                21 April 1997

    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 MUST be zeroed out.


      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_keyblk {
                    uint16_t sadb_keyblk_len;
                    uint16_t sadb_keyblk_hdrtype; /* KEY */
                    uint8_t sadb_keyblk_which; /* Bitmask, which keys? */
                    uint8_t sadb_keyblk_reserved[3]; /* Padding */
                    /* Followed by sadb_key */

    The Key extension is followed by the  appropriate  number  of  keys,
    which  contain information to correspond it to which keys are in the
    keyblock.  These keys are encoded as follows:

            struct sadb_key {
                    uint16_t sadb_key_len;  /* Length of key in bits */
                    uint8_t sadb_key_which; /* Corresponds to keyblk_which */
                    uint8_t sadb_key_type;  /* 3DES, DES, HMAC-MD5, etc. */
                    /* Actual key follows */

    The length of individual keys is in bits, and is interpreted by  the
    algorithm.   Each  key is padded to a 32-bit boundary.  The key bits
    are arranged most-sigificant to least significant.  For  example,  a
    22-bit  key  would  take up three octets, with the least significant
    two bits not containing key material.  An additional octet would  be
    used for padding to a 32-bit boundary.

    The sadb_key_which field indicates what sort of key this is, and  is
    one  bit out of the list of bits in sadb_keyblk_which.  These values
    are detailed later.


      The Identity extension  contains  endpoint  identities.   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:

McDonald, Metz, and Phan  Expires in 6 months          [Page 13]

Internet Draft            PF_KEY, Version 2                21 April 1997

            struct sadb_id {
                    uint16_t sadb_id_len;
                    uint16_t sadb_id_hdrtype;  /* IDENTITY */
                    uint8_t sadb_id_which;  /* bitmask */
                    uint8_t sadb_id_reserved[3];  /* Padding */
                    /* Followed by one or more sadb_certids */

    The sadb_id_which field  is  a  bitmask,  indicating  if  source  or
    destination  certificate identities are present.  Each identity is a
    32-bit aligned quantity, specified as:

            struct sadb_certid {
                    uint16_t sadb_certid_len;  /* In 32-bit words */
                    uint16_t sadb_certid_type;
                    /* Cert id. follows */

    Following each sadb_certid is 32-bit aligned data.  The type of data
    can  either be nothing (if the specified identity is the address), a
    null-terminated C  string  (for  fully-qualified  domain  names,  or
    mailbox  identities), and address/mask pair (for address ranges), or
    a port-pair/protocol tuple, used in concert with the addresses.  See
    the ILLUSTRATION OF MESSAGE LAYOUT section for details.


      The Sensitiviy extension contains security  labelling  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 labelling on the packet is obviated.

            struct sadb_sens {
                    uint16_t sadb_sens_len;
                    uint16_t sadb_sens_hdrtype;  /* SENSITIVITY */
                    uint32_t sadb_sens_dpd;
                    uint8_t sadb_sens_sens_level;
                    uint8_t sadb_sens_sens_bitmap_len;  /* 32-bit words */
                    uint8_t sadb_sens_integ_level;
                    uint8_t sadb_sens_integ_bitmap_len; /* 32-bit words */
                     * followed by two uint32_t arrays
                     * uint32_t sadb_sens_bitmap[sens_bitmap_len];
                     * uint32_t integ_bitmap[integ_bitmap_len];

McDonald, Metz, and Phan  Expires in 6 months          [Page 14]

Internet Draft            PF_KEY, Version 2                21 April 1997

    The lengths of the bitmaps are in bytes.  Following this  field  are
    the  bitmaps.   Only at the end of the second bitmap does padding to
    32-bits occur.  The sadb_sens_dpd describes the  protection  domain,
    which allows interpretation of the levels and compartment bitmaps.


      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_hdrtype;  /* PROPOSAL */
                    uint8_t sadb_prop_num;
                    uint8_t sadb_prop_replay;   /* Replay win. size. */
                    uint16_t sadb_prop_reserved;

    Following the header are a  list  of  combinations  in  preferential
    order.   A  combination contains an <auth, encrypt> algorithm, pair,
    and some other parameters.  These combinations look like:

            struct sadb_comb {
                    uint8_t sadb_comb_auth;
                    uint8_t sadb_comb_encr;
                    uint16_t sadb_comb_flags;
                    uint16_t sadb_comb_auth_keylen_min;
                    uint16_t sadb_comb_auth_keylen_max;
                    uint16_t sadb_comb_encr_keylen_min;
                    uint16_t sadb_comb_encr_keylen_max;

    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
    keylengths  are  derived  from  possible  a priori policy decisions,
    along with basic properties of the algorithm.


      The  Supported  Algorithms  extension  contains  a  list  of   all
    algorithms  supported  by  the  system.   This  is  useful  for  key
    management, as it now knows what algorithms it can  negotiate.   Its
    format is:

            struct sadb_alg {
                    uint16_t sadb_alg_len;
                    uint16_t sadb_alg_hdrtype;  /* SUPPORTED */

McDonald, Metz, and Phan  Expires in 6 months          [Page 15]

Internet Draft            PF_KEY, Version 2                21 April 1997

                    uint8_t sadb_alg_num_auth;  /* # of auth algs */
                    uint8_t sadb_alg_num_encrypt; /* # of encrypt algs */
                    uint16_t sadb_alg_reserved;
                    /* Followed by one or more alg_desc */

    It is followed by one or more algorithm descriptors.   An  algorithm
    descriptor looks like:

            struct sadb_algd {
                    uint8_t sadb_algd_type; /* Algorithm type. */
                    uint8_t sadb_algd_ivlen;   /* IV len, in bits */
                    uint16_t sadb_algd_minlen; /* Min. key len (in bits) */
                    uint16_t sadb_algd_maxlen; /* Max. key length */
                    uint16_t sadb_algd_reserved;

    32-bit alignment is guaranteed by  the  fields  automatically.   The
    initialization  vector  length  is 0 if not needed, and 0 if needed.
    The minlen and maxlen are key lengths in bits.


    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_hdrtype; /* SPI_RANGE */
                    uint32_t sadb_spirange_low;
                    uint32_t sadb_spirange_hi;


   The following shows how the octets are layed 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
        | sadb_version  | sadb_msg_type | sadb_msg_errno| sadb_sa_type  |
        |          sadb_msg_len         |       sadb_msg_reserved       |
        |                         sadb_msg_seq                          |

McDonald, Metz, and Phan  Expires in 6 months          [Page 16]

Internet Draft            PF_KEY, Version 2                21 April 1997

        |                         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_hdrtype        |
       |                          sadb_sa_spi                          |
       | ...replay...  | sadb_sa_state |sadb_sa_encrypt| sadb_sa_auth  |
       |                         sadb_sa_flags                         |

   The Lifetime extension

       |         sadb_lifetime_len     |    sadb_lifetime_hdrtype      |
       |  ..._which    |             sadb_lifetime_reserved            |

      A lifetime value

       | ..._val_which | ..._reserved  | sadb_lifetime_val_allocations |
       |                  sadb_lifetime_val_bytes                      |
       >                  sadb_lifetime_val_absolute                   <
       >                  sadb_lifetime_val_updatetime                 <
       >                  sadb_lifetime_val_usetime                    <

McDonald, Metz, and Phan  Expires in 6 months          [Page 17]

Internet Draft            PF_KEY, Version 2                21 April 1997

   The Address extension

       |       sadb_address_len        |     sadb_address_hdrtype      |
       |sadb_addr_which|             sadb_addr_reserved                |
       >             32-bit aligned struct sockaddr(s)                 <

   The Key extension

       |      sadb_keyblk_len          |      sadb_keyblk_hdrtype      |
       |...keyblk_which|             sadb_keyblk_reserved              |
       >         One or more actual keys, encoded as follows...        <

      An actual key

       |        sadb_key_len           | sadb_key_which| sadb_key_type |
       >     A key, padded to 32-bits, most sigificant bits to least.  <

   The Identity extension

       |          sadb_id_len          |        sadb_id_hdrtype        |
       | sadb_id_which |               sadb_id_reserved                |
       >     One or more certificate identities of the following forms <

      IPv6 address or IPv4 address should look in the previous Address
      extension for actual values.

       |        sadb_certid_len        |       sadb_certid_type        |
       >                      Certificate data                         <

      NOTE that the Certificate data gets filled with useful fields for

McDonald, Metz, and Phan  Expires in 6 months          [Page 18]

Internet Draft            PF_KEY, Version 2                21 April 1997

      most identity types.

      An IPv6 or IPv4 address prefix

       |        sadb_certid_len        |       sadb_certid_type        |
       |pref_len (bits)|                     reserved                  |
       >   16-bytes of IPv6 or 4-bytes of IPv4 address prefix          <

      A Fully-qualified domain name, or a mailbox ID.

       |        sadb_certid_len        |       sadb_certid_type        |
       >  A null-terminated C-string which MUST be padded out for 32-  >
       <  bit alignment                                                <

      A connection ID, which uses address plus port/protocol information.

       |        sadb_certid_len        |       sadb_certid_type        |
       |  protocol_id  |                    reserved                   |
       |          source_port          |      destination_port         |

   The Sensitivity extension

       |         sadb_sens_len         |      sadb_sens_hdrtype        |
       |                         sadb_sens_dpd                         |
       | ...sens_level | ...bitmap_len |..._integ_level| ...bitmap_len |
       > The sensitivity bitmap, followed immediately by the integrity <
       < bitmap, each is an array of uint32_t.                         >

   The Proposal extension

       |         sadb_prop_len         |       sadb_prop_hdrtype       |

McDonald, Metz, and Phan  Expires in 6 months          [Page 19]

Internet Draft            PF_KEY, Version 2                21 April 1997

       | sadb_prop_num | ..prop_replay |       sadb_prop_reserved      |
       >     One or more combinations, specified as follows...         <

       |sadb_comb_auth |sadb_comb_encr |        sadb_comb_flags        |
       |  sadb_comb_auth_keylen_min    |   sadb_comb_auth_keylen_max   |
       |  sadb_comb_encr_keylen_min    |   sadb_comb_encr_keylen_max   |

   The Supported Algorithms extension

       |         sadb_alg_len          |        sadb_alg_hdrtype       |
       | ...num_auth   |  ...num_encr. |        sadb_alg_reserved      |

      Followed by one or more Algorithm Descriptors

       |sadb_algd_type |sadb_algd_ivlen|      sadb_algd_minlen         |
       |        sadb_algd_maxlen       |      sadb_algd_reserved       |

   The SPI Range extension

       |       sadb_spirange_len       |     sadb_spirange_hdrtype     |
       |                      sadb_spirange_low                        |
       |                       sadb_spirange_hi                        |


     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

McDonald, Metz, and Phan  Expires in 6 months          [Page 20]

Internet Draft            PF_KEY, Version 2                21 April 1997

   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

   If an  implementation  has  implementation  specific  extensions  the
   SADB_X_ prefix MUST be used to name such extensions.


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

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


   The Lifetime extension is represented with one to three letters after
   it, to represent (H)ard, (S)oft, or (C)urrent.

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

3.1.1 SADB_GETSPI Message

     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 a 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,  and,  if  proxy  key

McDonald, Metz, and Phan  Expires in 6 months          [Page 21]

Internet Draft            PF_KEY, Version 2                21 April 1997

   management is in use, the internal sockaddrs or  the  proxy  sockaddr
   are  also  included  in  the  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 specifiy 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.  An SADB_UPDATE
   message can later be used to add an  entry  with  the  requested  SPI

     The message behavior of the SADB_GETSPI message is:

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

        <base, address, SPI range>

        The kernel returns the SADB_GETSPI message to all listening

        <base, association, address>


        EINVAL  Various message improprieties, including SPI ranges that
                are malformed.
        ENOBUFS No buffer space is available to process request.
        EEXIST  Requested SPI or SPI range is not available/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  larval security association created with SADB_GETSPI.  The
   format of the update  message  is  a  base  header,  followed  by  an
   association  header  and  any  relevant  extensions.   If  the keying
   material, lifetimes, compartment bitmaps, or  certificate  identities
   need  to be updated, these extensions should be included.  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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 22]

Internet Draft            PF_KEY, Version 2                21 April 1997

     The kernel SHOULD perform  sanity  checking  on  various  technical
   parameters passed in as part of the SADB_UPDATE message.  One example
   is DES key parity bit checking.  Other examples  include  key  length
   checking,  and  checks  for  keys  known to be weak for the specified

     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  associations.   Malicious  trusted
   parties could still issue a 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 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 message behavior of the SADB_UPDATE message is:

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

        <base, association, (lifetime (HS),) address, key, (identity,)

        The kernel returns the SADB_UPDATE message to all listening

        <base, association, (lifetime (HSC),) address, (identity,)

     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.

        ESRCH   The security association to be updated was not found.
        EINVAL  Various message improprieties, including sanity check
                failures on keys.
        EACCES  Insufficient privilege to update entry.  Socket issuing
                the SADB_UPDATE is not creator of the entry to be updated.

3.1.3 SADB_ADD Message

     The  SADB_ADD  message  is  nearly  identical  to  the  SADB_UPDATE

McDonald, Metz, and Phan  Expires in 6 months          [Page 23]

Internet Draft            PF_KEY, Version 2                21 April 1997

   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.  It MAY be useful  to
   set  the  sadb_msg_seq  to that of a kernel-generated SADB_ACQUIRE so
   that both associations in a  pair  are  bound  to  the  same  ACQUIRE

     The message behavior of the SADB_ADD message is:

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

        <base, association, (lifetime (HS),) address, key, (identity,)

        The kernel returns the SADB_ADD message to all listening

        <base, association, (lifetime (HSC),) address, (identity,)

  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.


        EEXIST  The security association that was to be added already
        EINVAL  Various message improprieties, including sanity check
                failures on keys.

3.1.4 SADB_DELETE Message

     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.

     The message behavior for SADB_DELETE is as follows:

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 24]

Internet Draft            PF_KEY, Version 2                21 April 1997

        <base, association, address>

        The kernel returns the SADB_DELETE message to all listening

        <base, association, address>

3.1.5 SADB_GET Message

     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 K_USED flag is set  inside  the
   Key Engine for the returned Security Association.

     The message behavior of the SADB_GET message is:

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

        <base, association, address>

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

        <base, association, (lifetime (HSC),) address, key, (identity,)

        ESRCH   The sought security association was not found.

3.1.6 SADB_ACQUIRE Message

     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 a
   certificate identity extension, and if more than  one  algorithm  and
   options  is acceptable, 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
   the  message originates from the kernel (i.e. the sadb_msg_pid is 0),

McDonald, Metz, and Phan  Expires in 6 months          [Page 25]

Internet Draft            PF_KEY, Version 2                21 April 1997

   the sadb_seq number MUST be used by a subsequent SADB_GETSPI  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_errno and sadb_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 a SADB_ACQUIRE message to registered sockets.

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

   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 inidicate key management failure.


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

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

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

        The kernel returns a SADB_ACQUIRE message to registered sockets.

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

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

        EINVAL  Invalid acquire request.
        EPROTONOSUPPORT   No KM application has registered with the Key

McDonald, Metz, and Phan  Expires in 6 months          [Page 26]

Internet Draft            PF_KEY, Version 2                21 April 1997

                Engine as being able to obtain the requested SA type, so
                the requested SA cannot be acquired.

3.1.7 SADB_REGISTER Message

     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_sa_type.  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
   algorithm, one per octet.  This allows key management applications to
   know what algorithm are supported by the kernel.

     In an enviroment where algorithms can  be  dynamically  loaded  and
   unloaded,  an asyncryonous 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 a SADB_REGISTER message from a user process to the kernel.


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

        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,

McDonald, Metz, and Phan  Expires in 6 months          [Page 27]

Internet Draft            PF_KEY, Version 2                21 April 1997

   then the kernel MUST issue an SADB_EXPIRE message to all  key  socket
   listeners.   A  user  application  is  responsible  for  tracking  SA
   expirations for security protocols (e.g.  OSPF  Authentication)  that
   are  implemented  inside that user application.  If the soft limit or
   hard  limit  of  a  Security  Association  has  expired,   the   user
   application SHOULD issue a 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 inidicates 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 a SADB_EXPIRE message to all listeners when the
        soft limit of a security association has been expired.

        <base, association, lifetime (HSC), address, (identity,)

        EINVAL  Message Invalid for some reason.

3.1.9  SADB_FLUSH Message

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

     The messaging behavior for SADB_FLUSH is:

McDonald, Metz, and Phan  Expires in 6 months          [Page 28]

Internet Draft            PF_KEY, Version 2                21 April 1997

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


           The kernel will return a SADB_FLUSH message to all listening


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

McDonald, Metz, and Phan  Expires in 6 months          [Page 29]

Internet Draft            PF_KEY, Version 2                21 April 1997

3.1.10  SADB_DUMP Message

     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_sa_type  value  is  in  the  message,   only
   associations  of  that  type  will be dumped.  If SADB_SATYPE_NONE is
   specified, all associations will be used.  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.
   Unlike  other  key messages, the dump message is returned only to the
   key socket originating the dump request because  of  the  potentially
   large  amount  of data it can generate.  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 the key socket, hence key management applications MUST NOT  depend
   on this message for basic operation.

     The messaging behavior for SADB_DUMP is:

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


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

           <base, association, (lifetime (HSC),) address, key, (identity,)

McDonald, Metz, and Phan  Expires in 6 months          [Page 30]

Internet Draft            PF_KEY, Version 2                21 April 1997

     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 SA_USED         0x1     /* SA used/not used */
        #define SA_UNIQUE       0x2     /* SA unique/reusable */
        #define SA_INBOUND      0x4     /* SA for packets destined here */
        #define SA_OUTBOUND     0x8     /* SA for packets sourced here */
        #define SA_FORWARD      0x10    /* SA for packets forwarded thru */
        #define SA_PFS          0x20    /* Perfect forward secrecy? */
        #define SA_REPLAY       0x40    /* Replay protection? */

     SA_USED is set by the operating system if the Security  Association
   has  been used.  Otherwise this flag is not set.  If SADB_GET is used
   to read an SA from the Key Engine, the Key Engine will set SA_USED on
   the SA that was read via SADB_GET.

     SA_UNIQUE  is  set  by  the  operating  system  if   the   Security
   Association  has  been  allocated  uniquely  to a single user (e.g. a
   particular network socket).  If this is not set,  then  the  Security
   Association is considered sharable.

     SA_INBOUND  is  set  for  an  inbound  Security   Association   and
   SA_OUTBOUND  is set for an outbound Security Association.  SA_FORWARD
   is used for a Security Association used only for packets  originating
   elsewhere  and  destined  elsewhere  that have security processing on
   this node.  Both flags can be set in environments where bidirectional
   security associations exist.

[Dan McD.:      Why SA_FORWARD?  Isn't SA_OUTBOUND sufficient?  I may
                implement forwarding such that it's hard or impossible for
                the key engine/SADB to tell the difference. ]

     The SA_PFS flag indicates to key management that  this  association
   should have perfect forward secrecy in its key.  (In other words, the
   session key cannot be determined by cryptanalysis of previous  keying

     The SA_REPLAY specifies that replay protection should be enabled on
   this association.


     The security association state field is an integer  that  describes

McDonald, Metz, and Phan  Expires in 6 months          [Page 31]

Internet Draft            PF_KEY, Version 2                21 April 1997

   the states of a security association.  They are:

           #define SA_STATE_LARVAL   0
           #define SA_STATE_MATURE   1
           #define SA_STATE_DYING    2
           #define SA_STATE_DEAD     3

           #define SA_STATE_MAX      3

     A LARVAL security association  is  one  that  was  created  by  the
   SADB_GETSPI  message.   A  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 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)  MUST  only  set  the  soft  lifetime  for  an


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

        #define SADB_SATYPE_NONE          0

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

        #define SADB_SATYPE_RSVP          3  /* RSVP Authentication */
        #define SADB_SATYPE_OSPFV2        4  /* OSPFv2 Authentication */
        #define SADB_SATYPE_RIPV2         5  /* RIPv2 Authentication */
        #define SADB_SATYPE_MIPV4         6  /* Mobile IPv4 Authentication */

        #define SADB_SATYPE_MAX           6

           SADB_SATYPE_NONE is defined for  completeness  and  means  no
   Security Association.  This type is never used with PF_KEY.

           SADB_SATYPE_AH is for the IP Authentication Header defined in
   [Atk95b].   SADB_SATYPE_ESP  is  for  the  IP  Encapsulating Security
   Payload defined in [Atk95c].

           SADB_SATYPE_RSVP is for the RSVP Integrity Object.

McDonald, Metz, and Phan  Expires in 6 months          [Page 32]

Internet Draft            PF_KEY, Version 2                21 April 1997

           SADB_SATYPE_OSPFv2    is     for     OSPFv2     Cryptographic
   authentication,  while  SADB_SATYPE_RIPv2  is for RIPv2 Cryptographic

           SADB_SATYPE_MAX is never used with PF_KEY but is defined  for
   completeness.   It  is always set to the highest valid numeric value.
   There MUST not be gaps  in  the  numbering  of  security  types;  all
   numbers must be used sequentially.


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

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

           /* Authentication algorithms */
           #define SADB_AALG_NONE          0

           #define SADB_AALG_MD5_HMAC      1
           #define SADB_AALG_SHA1_HMAC     2

           #define SADB_AALG_MAX           2

           /* Encryption algorithms */
           #define SADB_EALG_NONE          0

           #define SADB_EALG_DES_CBC       1
           #define SADB_EALG_3DES          2
           #define SADB_EALG_RC5           3

           #define SADB_EALG_MAX           3

   The algorithm for  SADB_AALG_MD5_HMAC  is  defined  in  [OG96].   The
   algorithm   for   SADB_AALG_SHA1_HMAC  is  defined  in  [CG96].   The
   algorithm for SADB_EALG_DES_CBC is defined in [Hug96].


   To briefly recap the extension header values:

McDonald, Metz, and Phan  Expires in 6 months          [Page 33]

Internet Draft            PF_KEY, Version 2                21 April 1997

           #define SA_EXT_ASSOCIATION 1
           #define SA_EXT_LIFETIME 2
           #define SA_EXT_ADDRESS 3
           #define SA_EXT_KEY 4
           #define SA_EXT_IDENTITY 5
           #define SA_EXT_SENSITIVITY 6
           #define SA_EXT_PROPOSAL 7
           #define SA_EXT_SUPPORTED 8
           #define SA_EXT_SPI_RANGE 9

           #define SA_EXT_MAX 9


     The sadb_address_which field is a bitmask which can  indicate  what
   sockaddrs follow, and what they represent.  These bit values are:

           #define SADB_ADDR_SRC 0x1               /* Source */
           #define SADB_ADDR_DST 0x2               /* Destination */
           #define SADB_ADDR_INNER_SRC 0x4         /* Inner-packet src */
           #define SADB_ADDR_INNNER_DST 0x8        /* Inner-packet dst */
           #define SADB_ADDR_PROXY 0x10            /* Proxy address */


     The sadb_lifetime_which field is a bitmask which  represents  which
   lifetime values are in the extension.  These bit values are:

           #define SADB_LIFETYPE_HARD 0x1 /* Hard lifetime */
           #define SADB_LIFETYPE_SOFT 0x2 /* Soft lifetime */
           #define SADB_LIFETYPE_CURRENT 0x4 /* Current lifetime left */


     The sadb_keyblk_which field is a  bitmask  which  represents  which
   keys are in the key block.  These bit values are:

           #define SADB_KEYBLK_AUTH 0x1    /* Authentication key */
           #define SADB_KEYBLK_ENCRYPT 0x2 /* Encryption key */


   The idh_which field is a  bitmask  which  indicates  what  identities

           #define SADB_ID_SRC 0x1
           #define SADB_ID_DST 0x2

McDonald, Metz, and Phan  Expires in 6 months          [Page 34]

Internet Draft            PF_KEY, Version 2                21 April 1997

   Each identity can have a certain type.

           #define SADB_IDT_IPV4_ADDR 1
           #define SADB_IDT_IPV6_ADDR 2
           #define SADB_IDT_IPV4_RANGE 3
           #define SADB_IDT_IPV6_RANGE 4
           #define SADB_IDT_FQDN 5
           #define SADB_IDT_USER_FQDN 6
           #define SADB_IDT_IPV4_CONNID 7
           #define SADB_IDT_IPV6_CONNID 8

           #define SADB_IDT_MAX 8


     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 senstivity extension is based off the sadb_sens_dpd

     If the highest order bit of the DP/DOI is set to 1, then the DP/DOI
   is  not  necessarily  globally  unique and is from a number space set
   aside for private use among consenting users.

     If the highest order bit of the DP/DOI is set to zero,  the  DP/DOI
   is  globally  unique from a number space administered by the Internet
   Assigned Numbers Authority.  In order to conserve the limited  amount
   of globally unique DP/DOI number space, IANA will not normally permit
   any one organization to obtain very  many  DP/DOI  values.   The  all
   zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is
   in use".

           #define SADB_DPD_NONE 0
           #define SADB_DPD_DOD_GENSER 1
           #define SADB_DPD_DOD_SCI 2
           #define SADB_DPD_DOE 3
           #define SADB_DPD_NATO 4

           #define SADB_DPD_MAX 4


   These are already mentioned in the ALGORITHM  TYPES  and  ASSOCIATION
   FLAGS sections.

McDonald, Metz, and Phan  Expires in 6 months          [Page 35]

Internet Draft            PF_KEY, Version 2                21 April 1997


     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

   [ALL:    What else belongs here ?  ]


     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  both.   These
   examples  are  purely illustrative, and are not intended to mandate a
   particular implementation method.


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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 36]

Internet Draft            PF_KEY, Version 2                21 April 1997

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

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

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

      Kernel->Registered:  SADB_ACQUIRE for AH, addr, ID, sens, proposal

     The KMd reads  the  ACQUIRE  message,  espcially  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, addr

     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.

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

      KMd->Kernel:         SADB_UPDATE for AH, assoc, addr, key, <etc.>
      Kernel->All:         SADB_UPDATE for AH, assoc, addr, <etc.>

   The results of the UPDATE (minus the actual keying material) 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, addr, key, <etc.>
      Kernel->All:         SADB_ADD for AH, assoc, addr, <etc.>

     If one of the extensions passed down was a Lifetime  extension,  it

McDonald, Metz, and Phan  Expires in 6 months          [Page 37]

Internet Draft            PF_KEY, Version 2                21 April 1997

   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, addr,
                                   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


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

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

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

      OSPFd->Kernel:       SADB_GET of OSPF, assoc, address
      Kernel->OSPFd:       SADB_GET of OSPF, assoc, address, key, <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, addr, <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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 38]

Internet Draft            PF_KEY, Version 2                21 April 1997


     Some have suggested using the PF_KEY messages over something like a
   UNIX  pipe,  or  direct  communication for situations like the one in
   this example.  It is a valid approach, but  this  document  does  not
   pursue  this possibility and leaves it to a willing party to document

     The two main reasons for involving the kernel are compatibility and
   leverage.   Compatibility  is  important so that a KMd can service as
   many consumers of SAs as it can.  Leverage  means  that  an  enhanced
   kernel  implementation  (or specialized user-space OS components) can
   provide  common  SA  maintenance   routines   (such   as   expiration


     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.

      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 my a KMd, or  by
   a system maintenance program.

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

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

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


     This draft discusses a method for creating, reading,  and  deleting
   Security  Associations  from  an  operating  system.   Only  trusted,
   privileged users and processes should be able to perform any of these

McDonald, Metz, and Phan  Expires in 6 months          [Page 39]

Internet Draft            PF_KEY, Version 2                21 April 1997

   operations.   It  is  unclear  whether  this  mechanism  provides any
   security when used with operating systems not having the concept of a
   trusted, privileged user.

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 40]

Internet Draft            PF_KEY, Version 2                21 April 1997


     The editors of this document are listed primarily  in  Alphabetical
   order.   A  side effect of this particular alphabetical listing is to
   also show the  history  (starting  with  the  most  recent)  of  text
   contribution  to  this  document.  Ran Atkinson also contributed much
   advice and wisdom toward this document.  Finally, the  editors  would
   like to thank the PF_KEY reviewers list.

   [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] Randall J. Atkinson, IP Security Architecture, RFC-1825,
            August 1995.

   [Atk95b] Randall J. Atkinson, IP Authentication Header, RFC-1826,
            August 1995.

   [Atk95c] Randall J. Atkinson, IP Encapsulating Security Payload, RFC-1827,
            August 1995.

   [CG96]   S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with Replay
            Prevention", Internet Draft, May 1996.

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

   [Hug96]  Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay
            Prevention Security Transform", Internet Draft, April 1996.

   [OG96]   Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with
            Replay Prevention", Internet Draft, May 1996.

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


     The views and specification here are those of the editors and are not
   necessarily those of their employers.  The employers have not passed
   judgement 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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 41]

Internet Draft            PF_KEY, Version 2                21 April 1997


              Daniel L. McDonald
              Sun Microsystems, Inc.
              2550 Garcia Avenue, MS UMPK17-202
              Mountain View, CA 94043-1100

              Craig W. Metz
              The Inner Net

              Bao G. Phan
              U. S. Naval Research Laboratory
              Code 5544
              4555 Overlook Ave. SW
              Washington, DC 20375


   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 arguement 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, Metz, and Phan  Expires in 6 months          [Page 42]

Internet Draft            PF_KEY, Version 2                21 April 1997

   * 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 policy 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, Metz, and Phan  Expires in 6 months          [Page 43]