Skip to main content

PF_KEY Key Management API, Version 2
draft-mcdonald-pf-key-v2-05

The information below is for an old version of the document that is already published as an RFC.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 2367.
Authors Craig Metz , Daniel L. McDonald , Bao Phan
Last updated 2021-04-15 (Latest revision 1998-04-27)
RFC stream Legacy stream
Intended RFC status Informational
Formats
Stream Legacy state (None)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state Became RFC 2367 (Informational)
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-mcdonald-pf-key-v2-05
Network Working Group                                    D. L. McDonald
Internet Draft                                               C. W. Metz
draft-mcdonald-pf-key-v2-05.txt                              B. G. Phan
                                                       28 February 1998

                  PF_KEY Key Management API, Version 2

Status of this Memo

     This document is an Internet Draft.  Internet  Drafts  are  working
   documents.

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

     This draft will be submitted to the RFC Editor for  publication  as
   an Informational document.

Abstract

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

McDonald, Metz, and Phan  Expires in 6 months           [Page 1]
Internet Draft            PF_KEY, Version 2             28 February 1998

Table of Contents
   1      Introduction .............................................  4
   1.1    Terminology ..............................................  4
   1.2    Conceptual Model .........................................  6
   1.3    PF_KEY Socket Definition .................................  8
   1.4    Overview of PF_KEY Messaging Behavior ....................  9
   1.5    Common PF_KEY Operations ................................. 10
   1.6    Differences Between PF_KEY and PF_ROUTE .................. 11
   1.7    Name Space ............................................... 11
   1.8    On Manual Keying ..........................................12
   2      PF_KEY Message Format .................................... 13
   2.1    Base Message Header Format ............................... 13
   2.2    Alignment of Headers and Extension Headers ............... 15
   2.3    Additional Message Fields ................................ 15
   2.3.1  Association Extension .................................... 16
   2.3.2  Lifetime Extension ....................................... 18
   2.3.3  Address Extension ........................................ 19
   2.3.4  Key Extension ............................................ 20
   2.3.5  Identity Extension ....................................... 21
   2.3.6  Sensitivity Extension .................................... 22
   2.3.7  Proposal Extension ....................................... 23
   2.3.8  Supported Algorithms Extension ........................... 25
   2.3.9  SPI Range Extension ...................................... 26
   2.4    Illustration of Message Layout ........................... 27
   3      Symbolic Names ........................................... 31
   3.1    Message Types ............................................ 31
   3.1.1  SADB_GETSPI .............................................. 33
   3.1.2  SADB_UPDATE .............................................. 34
   3.1.3  SADB_ADD ................................................. 35
   3.1.4  SADB_DELETE .............................................. 36
   3.1.5  SADB_GET ................................................. 37
   3.1.6  SADB_ACQUIRE ............................................. 37
   3.1.7  SADB_REGISTER ............................................ 39
   3.1.8  SADB_EXPIRE .............................................. 39
   3.1.9  SADB_FLUSH ............................................... 40
   3.1.10 SADB_DUMP ................................................ 41
   3.2    Security Association Flags ............................... 41
   3.3    Security Association States .............................. 42
   3.4    Security Association Types ............................... 42
   3.5    Algorithm Types .......................................... 43
   3.6    Extension Header Values .................................. 44
   3.7    Identity Extension Values ................................ 44
   3.8    Sensitivity Extension Values ............................. 45
   3.9    Proposal Extension Values ................................ 45
   4      Future Directions ........................................ 46
   5      Examples ................................................. 47
   5.1    Simple IP Security Example ............................... 47
   5.2    Proxy IP Security Example ................................ 49

McDonald, Metz, and Phan  Expires in 6 months           [Page 2]
Internet Draft            PF_KEY, Version 2             28 February 1998

   5.3    OSPF Security Example .................................... 51
   5.4    Miscellaneous ............................................ 51
   6      Security Considerations .................................. 53
          Acknowledgments ............,............................. 54
          References ............................................... 55
          Disclaimer ............................................... 57
          Authors' Addresses ....................................... 57
   A      Promiscuous Send/Receive Extension ....................... 58
   B      Passive Change Message Extension ......................... 60
   C      Sample Header File ....................................... 61
   D      Change Log ............................................... 66

McDonald, Metz, and Phan  Expires in 6 months           [Page 3]
Internet Draft            PF_KEY, Version 2             28 February 1998

1 Introduction

     PF_KEY is a new socket protocol family used by  trusted  privileged
   key management applications to communicate with an operating system's
   key management internals (referred to here as the "Key Engine" or the
   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 Key
   Engine thus refer to more than cryptographic keys  and  are  retained
   for consistency with the traditional phrase, "Key Management".

     PF_KEY is derived in part from the BSD  routing  socket,  PF_ROUTE.
   [Skl91]  This  document  describes Version 2 of PF_KEY. Version 1 was
   implemented in the  first  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  directly
   communicating  user-level  processes),  but  this  document  will not
   discuss in detail such possibilities.

     Security policy is deliberately omitted from this interface. PF_KEY
   is  not  a mechanism for tuning systemwide security policy, nor is it
   intended to enforce any sort of key management policy. The developers
   of  PF_KEY  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.

1.1 Terminology

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

   - MUST

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

   - SHOULD

     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

McDonald, Metz, and Phan  Expires in 6 months           [Page 4]
Internet Draft            PF_KEY, Version 2             28 February 1998

     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.

   - CONFORMANCE and COMPLIANCE

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

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

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

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

     In terms of IP Security, a general rule of thumb is that whatever
     might be labeled the "encryption" part of an ESP transform is

McDonald, Metz, and Phan  Expires in 6 months           [Page 5]
Internet Draft            PF_KEY, Version 2             28 February 1998

     probably a PF_KEY encryption algorithm. Whatever might be labelled
     the "authentication" part of an AH or ESP transform is probably a
     PF_KEY authentication algorithm.

1.2 Conceptual Model

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

     Key management is most commonly implemented in whole or part at the
   application   layer.   For  example,  the  ISAKMP/Oakley,  GKMP,  and
   Photuris proposals for IPsec key management are all application-layer
   protocols.   Manual  keying  is  also  done at the application layer.
   Even parts of the SKIP IP-layer keying proposal can be implemented at
   the application layer.  Figure 1 shows the relationship between a Key
   Management daemon and PF_KEY, 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
   Associations.

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

McDonald, Metz, and Phan  Expires in 6 months           [Page 6]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

                     Figure 1: Relationship of Key Mgmt to PF_KEY

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

McDonald, Metz, and Phan  Expires in 6 months           [Page 7]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

           Figure 2: Relationship of Trusted Application to PF_KEY

     When a trusted privileged application is using the Key  Engine  but
   implements the security protocol within itself, then operation varies
   slightly.  In this case, the application needing an SA sends a PF_KEY
   SADB_ACQUIRE  message  down  to  the  Key  Engine,  which then either
   returns an error or sends a similar SADB_ACQUIRE message up to one or
   more  key  management  applications capable of creating such SAs.  As
   before, the key management daemon stores the SA into the Key  Engine.
   Then,  the  trusted privileged application uses 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  actual cryptographic processing takes place in the
   kernel.  Such policy communication between the kernel mechanisms  and
   the  user-space  policy  MAY  be implemented by PF_KEY extensions, or
   other  such  mechanism.   This  document  does   not   specify   such
   extensions.

     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.

1.3 PF_KEY Socket Definition

     The  PF_KEY  protocol  family  (PF_KEY)  symbol   is   defined   in
   <sys/socket.h>  in  the  same manner that other protocol families are

McDonald, Metz, and Phan  Expires in 6 months           [Page 8]
Internet Draft            PF_KEY, Version 2             28 February 1998

   defined.  PF_KEY does not  use  any  socket  addresses.  Applications
   using  PF_KEY  MUST  NOT depend on the availability of a symbol named
   AF_KEY, but kernel implementations  are  encouraged  to  define  that
   symbol for completeness.

     The key management socket is created as follows:

     #include <net/pfkeyv2.h>

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

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

1.4 Overview of PF_KEY Messaging Behavior

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

     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

McDonald, Metz, and Phan  Expires in 6 months           [Page 9]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

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

1.5 Common PF_KEY Operations

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

     The second approach to add a  new  Security  Association  into  the
   kernel  is for the application to first request 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).

     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, SADB_UPDATE, and SADB_ADD 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

McDonald, Metz, and Phan  Expires in 6 months          [Page 10]
Internet Draft            PF_KEY, Version 2             28 February 1998

   use  receipt  of  a  soft  lifetime  SADB_EXPIRE message as a hint to
   negotiate a replacement SA so the replacement SA will be ready and in
   the kernel before it is needed.

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

1.6 Differences Between PF_KEY and PF_ROUTE

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

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

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

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

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

1.7 Name Space

     All PF_KEYv2 preprocessor symbols  and  structure  definitions  are
   defined  as  a  result  of including the header file <net/pfkeyv2.h>.
   There is exactly one exception to this  rule:  the  symbol  "PF_KEY",
   which   is   defined  as  a  result  of  including  the  header  file
   <sys/socket.h>. All PF_KEYv2  preprocessor  symbols  start  with  the

McDonald, Metz, and Phan  Expires in 6 months          [Page 11]
Internet Draft            PF_KEY, Version 2             28 February 1998

   prefix  "SADB_" and all structure names start with "sadb_". There are
   exactly two exceptions to this rule: the symbol "PF_KEY_V2"  and  the
   symbol "PFKEYV2_REVISION".

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

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

1.8 On Manual Keying

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 12]
Internet Draft            PF_KEY, Version 2             28 February 1998

2 PF_KEY Message Format

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

     PF_KEY messages currently do not mandate any specific ordering  for
   non-network  multi-octet  fields.  Fields that may go across the wire
   (e.g. SPI) MUST be in network byte order.

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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 13]
Internet Draft            PF_KEY, Version 2             28 February 1998

   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 are enumerated later in this
                   document.

   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 analogous to a transaction ID in a
                   remote procedure call implementation.

McDonald, Metz, and Phan  Expires in 6 months          [Page 14]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

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 {

McDonald, Metz, and Phan  Expires in 6 months          [Page 15]
Internet Draft            PF_KEY, Version 2             28 February 1998

                   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.

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

     Types of  extensions  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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 16]
Internet Draft            PF_KEY, Version 2             28 February 1998

           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;
           };
           /* 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 a 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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 17]
Internet Draft            PF_KEY, Version 2             28 February 1998

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
   extension looks like:

           struct sadb_lifetime {
                   uint16_t sadb_lifetime_len;
                   uint16_t sadb_lifetime_exttype;
                   uint32_t sadb_lifetime_allocations;
                   uint64_t sadb_lifetime_bytes;
                   uint64_t sadb_lifetime_addtime;
                   uint64_t sadb_lifetime_usetime;
           };
           /* sizeof(struct sadb_lifetime) == 32 */

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

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 18]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

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

2.3.3 Address Extension

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

           struct sadb_address {
                   uint16_t sadb_address_len;
                   uint16_t sadb_address_exttype;
                   uint8_t sadb_address_proto;
                   uint8_t sadb_address_prefixlen;
                   uint16_t sadb_address_reserved;
           };
           /* sizeof(struct sadb_address) == 8 */

           /* followed by some form of struct sockaddr */

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

     The SRC and DST addresses for a security association MUST be in the
   same protocol family and MUST always be present or absent together in
   a message. The PROXY address MAY be in a different  protocol  family,

McDonald, Metz, and Phan  Expires in 6 months          [Page 19]
Internet Draft            PF_KEY, Version 2             28 February 1998

   and  represents  an actual originator of a packet.  (For example, the
   inner-packets's source address in a tunnel.)

     The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY)
   address.  The DST address MUST be a unicast or multicast address. The
   PROXY address MUST be a unicast address.

2.3.4 Key Extension

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

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

           /* followed by the key data */

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

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

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

     When   a   particular   security   protocol   only   requires   one

McDonald, Metz, and Phan  Expires in 6 months          [Page 20]
Internet Draft            PF_KEY, Version 2             28 February 1998

   authentication  and/or  one  encryption  key, the fully formed key is
   transmitted using the appropriate key extension.  When  a  particular
   security  protocol  requires  more than one key for the same function
   (e.g. Triple-DES using 2 or 3 keys, and asymmetric algorithms),  then
   those  two  fully formed keys concatenated together in the order used
   for outbound packet processing. In the case  of  multiple  keys,  the
   algorithm  MUST  be  able  to determine the lengths of the individual
   keys based on the information provided.  The total key  length  (when
   combined  with  knowledge  of  the algorithm in use) usually provides
   sufficient information to make this determination.

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

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

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

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

           0x123

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

           01 23           OR              12 30

   It is the opinion of the authors that the former (0x123 == 0x0123) is

McDonald, Metz, and Phan  Expires in 6 months          [Page 21]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

2.3.5 Identity Extension

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

           struct sadb_ident {
                   uint16_t sadb_ident_len;
                   uint16_t sadb_ident_exttype;
                   uint16_t sadb_ident_type;
                   uint16_t sadb_ident_reserved;
                   uint64_t sadb_ident_id;
           };
           /* sizeof(struct sadb_ident) == 16 */

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

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

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

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

2.3.6 Sensitivity Extension

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 22]
Internet Draft            PF_KEY, Version 2             28 February 1998

           struct sadb_sens {
                   uint16_t sadb_sens_len;
                   uint16_t sadb_sens_exttype;
                   uint32_t sadb_sens_dpd;
                   uint8_t sadb_sens_sens_level;
                   uint8_t sadb_sens_sens_len;
                   uint8_t sadb_sens_integ_level;
                   uint8_t sadb_sens_integ_len;
                   uint32_t sadb_sens_reserved;
           };
           /* sizeof(struct sadb_sens) == 16 */

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

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

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

2.3.7 Proposal Extension

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

           struct sadb_prop {
                   uint16_t sadb_prop_len;
                   uint16_t sadb_prop_exttype;
                   uint8_t sadb_prop_replay;
                   uint8_t sadb_prop_reserved[3];

McDonald, Metz, and Phan  Expires in 6 months          [Page 23]
Internet Draft            PF_KEY, Version 2             28 February 1998

           };
           /* sizeof(struct sadb_prop) == 8 */

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

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

           struct sadb_comb {
                   uint8_t sadb_comb_auth;
                   uint8_t sadb_comb_encrypt;
                   uint16_t sadb_comb_flags;
                   uint16_t sadb_comb_auth_minbits;
                   uint16_t sadb_comb_auth_maxbits;
                   uint16_t sadb_comb_encrypt_minbits;
                   uint16_t sadb_comb_encrypt_maxbits;
                   uint32_t sadb_comb_reserved;
                   uint32_t sadb_comb_soft_allocations;
                   uint32_t sadb_comb_hard_allocations;
                   uint64_t sadb_comb_soft_bytes;
                   uint64_t sadb_comb_hard_bytes;
                   uint64_t sadb_comb_soft_addtime;
                   uint64_t sadb_comb_hard_addtime;
                   uint64_t sadb_comb_soft_usetime;
                   uint64_t sadb_comb_hard_usetime;
           };
           /* sizeof(struct sadb_comb) == 72 */

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 24]
Internet Draft            PF_KEY, Version 2             28 February 1998

                   sadb_key_bits field of KEY_AUTH. The minimum MUST
                   NOT be greater than the maximum.

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

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

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

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 25]
Internet Draft            PF_KEY, Version 2             28 February 1998

2.3.8 Supported Algorithms Extension

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

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

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

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

           struct sadb_alg {
                   uint8_t sadb_alg_id;
                   uint8_t sadb_alg_ivlen;
                   uint16_t sadb_alg_minbits;
                   uint16_t sadb_alg_maxbits;
                   uint16_t sadb_alg_reserved;
           };
           /* sizeof(struct sadb_alg) == 8 */

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

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

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

   sadb_alg_maxbits
                   The maximum acceptable key length, in bits. A value

McDonald, Metz, and Phan  Expires in 6 months          [Page 26]
Internet Draft            PF_KEY, Version 2             28 February 1998

                   of zero is invalid. The minimum MUST NOT be greater
                   than the maximum.

2.3.9 SPI Range Extension

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

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

   sadb_spirange_min
                   The minimum acceptable SPI value.

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

2.4 Illustration of Message Layout

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

   The base header is as follows:

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 27]
Internet Draft            PF_KEY, Version 2             28 February 1998

   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.

McDonald, Metz, and Phan  Expires in 6 months          [Page 28]
Internet Draft            PF_KEY, Version 2             28 February 1998

   The Association extension

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

   The Lifetime extension

       +---------------+---------------+---------------+---------------+
       |         sadb_lifetime_len     |    sadb_lifetime_exttype      |
       +---------------+---------------+---------------+---------------+
       |                   sadb_lifetime_allocations                   |
       +---------------+---------------+---------------+---------------+
       |                    sadb_lifetime_bytes                        |
       |                           (64 bits)                           |
       +---------------+---------------+---------------+---------------+
       |                    sadb_lifetime_addtime                      |
       |                           (64 bits)                           |
       +---------------+---------------+---------------+---------------+
       |                    sadb_lifetime_usetime                      |
       |                           (64 bits)                           |
       +---------------+---------------+---------------+---------------+

   The Address extension

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 29]
Internet Draft            PF_KEY, Version 2             28 February 1998

   The Key extension

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

   The Identity extension

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

   The Sensitivity extension

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 30]
Internet Draft            PF_KEY, Version 2             28 February 1998

   The Proposal extension

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 31]
Internet Draft            PF_KEY, Version 2             28 February 1998

   The Supported Algorithms extension

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

      Followed by one or more Algorithm Descriptors

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

   The SPI Range extension

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

3 Symbolic Names

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

3.1 Message Types

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 32]
Internet Draft            PF_KEY, Version 2             28 February 1998

           #define SADB_RESERVED    0
           #define SADB_GETSPI      1
           #define SADB_UPDATE      2
           #define SADB_ADD         3
           #define SADB_DELETE      4
           #define SADB_GET         5
           #define SADB_ACQUIRE     6
           #define SADB_REGISTER    7
           #define SADB_EXPIRE      8
           #define SADB_FLUSH       9

           #define SADB_DUMP        10   /* not used normally */

           #define SADB_MAX         10

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

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

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

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

   The address extensions are represented  with  one  to  three  letters
   after the word "address," representing (S)RC, (D)ST, (P)ROXY.
           NOTE:   Some security association types do not use a source
                   address for SA identification, where others do.  This
                   may cause EEXIST errors for some SA types where others
                   do not report collisions.  It is expected that
                   application authors know enough about the underlying
                   security association types to understand these
                   differences.

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

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 33]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

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

3.1.1 SADB_GETSPI

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

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

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

    Errors:

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

3.1.2 SADB_UPDATE Message

     The SADB_UPDATE message allows a process to update the  information

McDonald, Metz, and Phan  Expires in 6 months          [Page 34]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

     The kernel MAY disallow SADB_UPDATE to succeed unless  the  message
   is issued from the same socket that created the security association.
   Such enforcement  significantly  reduces  the  chance  of  accidental
   changes  to  an  in-use  security  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  to supporting this behavior involves the case where a user-
   space key management application fails and  is  restarted.   The  new
   instance  of  the  application  will  not have the same socket as the
   creator of the security association.

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

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

     The message behavior of the SADB_UPDATE message is:

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 35]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

        The kernel returns the SADB_UPDATE message to all listening
        processes.

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

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

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

3.1.3 SADB_ADD

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

     An SADB_ADD message is also used when negotiation is finished,  and
   the  second  of  a  pair  of associations is added.  The SPI for this
   association was determined by the  peer  machine.   The  sadb_msg_seq
   MUST  be  set  to the value set in a kernel-generated SADB_ACQUIRE so
   that both associations in a  pair  are  bound  to  the  same  ACQUIRE
   request.

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 36]
Internet Draft            PF_KEY, Version 2             28 February 1998

   not true.

     The message behavior of the SADB_ADD message is:

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

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

        The kernel returns the SADB_ADD message to all listening
        processes.

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

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

    Errors:

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

3.1.4 SADB_DELETE

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

     The message behavior for SADB_DELETE is as follows:

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

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

        The kernel returns the SADB_DELETE message to all listening
        processes.

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 37]
Internet Draft            PF_KEY, Version 2             28 February 1998

3.1.5 SADB_GET

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

     The message behavior of the SADB_GET message is:

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

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

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

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

    Errors:
        ESRCH   The sought security association was not found.

3.1.6 SADB_ACQUIRE

     The SADB_ACQUIRE message is typically sent only by  the  kernel  to
   key  socket  listeners  who  have  registered  their  key socket (see
   SADB_REGISTER  message).   SADB_ACQUIRE  messages  can  be  sent   by
   application-level  consumers  of  security  associations  (such as an
   OSPFv2 implementation that uses  OSPF  security).   The  SADB_ACQUIRE
   message is a base header along with an address extension, possibly an
   identity extension, and a proposal extension. The proposed  situation
   contains  a  list  of  desirable  algorithms  that can be used if the
   algorithms in the base header are not available.  The values for  the
   fields  in the base header and in the security association data which
   follows the base header  indicate  the  properties  of  the  Security
   Association that the listening process should attempt to acquire.  If
   the message originates from the kernel (i.e. the sadb_msg_pid is  0),
   the  sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and
   SADB_UPDATE, or  subsequent  SADB_ADD  message  to  bind  a  security
   association  to  the  request.  This avoids the race condition of two
   TCP connections  between  two  IP  hosts  that  each  require  unique
   associations,  and  having  one steal another's security association.
   The sadb_msg_errno and sadb_msg_state fields should be ignored by the
   listening process.

     The SADB_ACQUIRE message is  typically  triggered  by  an  outbound
   packet  that  needs  security  but  for  which there is no applicable

McDonald, Metz, and Phan  Expires in 6 months          [Page 38]
Internet Draft            PF_KEY, Version 2             28 February 1998

   Security Association existing in the key table.  If the packet can be
   sufficiently  protected  by more than one algorithm or combination of
   options, the  SADB_ACQUIRE  message  MUST  order  the  preference  of
   possibilities in the Proposal extension.

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

        The kernel sends an SADB_ACQUIRE message to registered sockets.

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

        NOTE:   The address(SD) extensions MUST have the port fields
                filled in with the port numbers of the session requiring
                keys if appropriate.

   The second is when, for some reason, key  management  fails,  it  can
   send  an  ACQUIRE  message  with the same sadb_msg_seq as the initial
   ACQUIRE with a non-zero errno.

        Send an SADB_ACQUIRE to indicate key management failure.

        <base>

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

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

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

        The kernel returns an SADB_ACQUIRE message to registered sockets.

        <base, address(SD), (address(P),) (identity(SD),) (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.

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 39]
Internet Draft            PF_KEY, Version 2             28 February 1998

                the requested SA cannot be acquired.

3.1.7 SADB_REGISTER

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

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

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

     The messaging behavior of the SADB_REGISTER message is:

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

        <base>

        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

McDonald, Metz, and Phan  Expires in 6 months          [Page 40]
Internet Draft            PF_KEY, Version 2             28 February 1998

   has  expired  for  a security protocol implemented inside the kernel,
   then the kernel MUST issue an SADB_EXPIRE message to all  key  socket
   listeners.  If the soft limit or hard limit of a Security Association
   for a  user-level  security  protocol  has  expired,  the  user-level
   protocol SHOULD issue 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 indicates that the HARD lifetime  expired.   This  means
   the  association  MAY  be  deleted  already from the SADB.  If a SOFT
   lifetime extension is included, it indicates that the  SOFT  lifetime
   expired.   The  CURRENT  lifetime extension will indicate the current
   status, and comparisons to the HARD or SOFT  lifetime  will  indicate
   which  limit  was  reached.  HARD lifetimes MUST take precedence over
   SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the  same,
   the   HARD   lifetime   will  appear  on  the  EXPIRE  message.   The
   pathological case of HARD lifetimes being shorter than SOFT lifetimes
   is handled such that the SOFT lifetime will never expire.

     The messaging behavior of the SADB_EXPIRE message is:

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

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

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

3.1.9 SADB_FLUSH

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

     The messaging behavior for SADB_FLUSH is:

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

           <base>

McDonald, Metz, and Phan  Expires in 6 months          [Page 41]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

           <base>

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

3.1.10 SADB_DUMP

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

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

     The messaging behavior for SADB_DUMP is:

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

           <base>

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

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

3.2 Security Association Flags

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

        #define SADB_SAFLAGS_PFS 1    /* perfect forward secrecy */

     The SADB_SAFLAGS_PFS flag indicates to  key  management  that  this
   association  should  have  perfect  forward  secrecy in its key.  (In
   other  words,  any  given  session  key  cannot  be   determined   by

McDonald, Metz, and Phan  Expires in 6 months          [Page 42]
Internet Draft            PF_KEY, Version 2             28 February 1998

   cryptanalysis of previous session keys or some master key.)

3.3 Security Association States

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

           #define SADB_SASTATE_LARVAL   0
           #define SADB_SASTATE_MATURE   1
           #define SADB_SASTATE_DYING    2
           #define SADB_SASTATE_DEAD     3

           #define SADB_SASTATE_MAX      3

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

3.4 Security Association Types

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

        #define SADB_SATYPE_UNSPEC        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_MIP           6  /* Mobile IP Auth. */

        #define SADB_SATYPE_MAX           6

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 43]
Internet Draft            PF_KEY, Version 2             28 February 1998

   SADB_SATYPE_AH is for the IP Authentication Header [Atk95b].

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

   SADB_SATYPE_RSVP is for the RSVP Integrity Object [Baker97].

   SADB_SATYPE_OSPFV2  is  for   OSPFv2   Cryptographic   authentication
   [Moy97].

   SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97].

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

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

3.5 Algorithm Types

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

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

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

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

           /* Encryption algorithms */
           #define SADB_EALG_NONE          0
           #define SADB_EALG_DESCBC        1
           #define SADB_EALG_3DESCBC       2
           #define SADB_EALG_MAX           2

   The algorithm for  SADB_AALG_MD5_HMAC  is  defined  in  [OG96].   The
   algorithm for SADB_AALG_SHA1HMAC is defined in [CG96].  The algorithm

McDonald, Metz, and Phan  Expires in 6 months          [Page 44]
Internet Draft            PF_KEY, Version 2             28 February 1998

   for SADB_EALG_DESCBC is defined in [Hug96].

3.6 Extension Header Values

   To briefly recap the extension header values:

           #define SADB_EXT_RESERVED          0
           #define SADB_EXT_SA                1
           #define SADB_EXT_LIFETIME_CURRENT  2
           #define SADB_EXT_LIFETIME_HARD     3
           #define SADB_EXT_LIFETIME_SOFT     4
           #define SADB_EXT_ADDRESS_SRC       5
           #define SADB_EXT_ADDRESS_DST       6
           #define SADB_EXT_ADDRESS_PROXY     7
           #define SADB_EXT_KEY_AUTH          8
           #define SADB_EXT_KEY_ENCRYPT       9
           #define SADB_EXT_IDENTITY_SRC      10
           #define SADB_EXT_IDENTITY_DST      11
           #define SADB_EXT_SENSITIVITY       12
           #define SADB_EXT_PROPOSAL          13
           #define SADB_EXT_SUPPORTED_AUTH    14
           #define SADB_EXT_SUPPORTED_ENCRYPT 15
           #define SADB_EXT_SPIRANGE          16

           #define SADB_EXT_MAX               16

3.7 Identity Extension Values

     Each identity can have a certain type.

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

           #define SADB_IDENTTYPE_MAX       3

     The PREFIX identity string consists of a network  address  followed
   by  a  forward slash and a prefix length. The network address is in a
   printable numeric form  appropriate  for  the  protocol  family.  The
   prefix  length  is a decimal number greater than or equal to zero and
   less than the number of bits in the network address. It indicates the
   number  of bits in the network address that are significant; all bits
   in the network address that are not significant MUST be set to  zero.
   Note  that  implementations  MUST parse the contents of the printable
   address into a binary form for comparison purposes  because  multiple
   printable  strings  are  valid representations of the same address in
   many protocol families (for example, some  allow  leading  zeros  and

McDonald, Metz, and Phan  Expires in 6 months          [Page 45]
Internet Draft            PF_KEY, Version 2             28 February 1998

   some  have  letters  that  are  case insensitive). Examples of PREFIX
   identities           are            "199.33.248.64/27"            and
   "5f00:3000:c721::f800:19:1/128".   If   the   source  or  destination
   identity is a PREFIX identity, the source or destination address  for
   the  SA (respectively) MUST be within that prefix.  The sadb_ident_id
   field is zeroed for these identity types.

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

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

3.8 Sensitivity Extension Values

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

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

3.9 Proposal Extension Values

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 46]
Internet Draft            PF_KEY, Version 2             28 February 1998

4 Future Directions

     While the current specification for the Sensitivity  and  Integrity
   Labels  is believed to be general enough, if a case should arise that
   can't work with the current specification then  this  might  cause  a
   change in a future version of PF_KEY.

     Similarly, PF_KEY might need extensions to work with other kinds of
   Security  Associations  in future.  It is strongly desirable for such
   extensions to be made in a backwards-compatible manner should they be
   needed.

     When more experience is gained with certificate management,  it  is
   possible  that  the  IDENTITY  extension will have to be revisited to
   allow a finer grained selection of certificate identities.

McDonald, Metz, and Phan  Expires in 6 months          [Page 47]
Internet Draft            PF_KEY, Version 2             28 February 1998

5 Examples

     The following examples illustrate how PF_KEY  is  used.  The  first
   example is an IP Security example, where the consumer of the security
   associations is inside an operating system kernel. The second example
   is  an OSPF Security example, which illustrates a user-level consumer
   of  security  associations.  The  third  example  covers  things  not
   mentioned  by  the  first  two  examples.  A  real system may closely
   conform to one of these  examples,  or  take  parts  of  them.  These
   examples  are  purely illustrative, and are not intended to mandate a
   particular implementation method.

5.1 Simple IP Security Example

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

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

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

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 48]
Internet Draft            PF_KEY, Version 2             28 February 1998

                           proposals

     The KMd reads the  ACQUIRE  message,  especially  the  sadb_msg_seq
   number.    Before  it  begins  the  negotiation,  it  sends  down  an
   SADB_GETSPI message with the sadb_msg_seq number  equal  to  the  one
   received  in  the  ACQUIRE.   The  kernel  returns the results of the
   GETSPI to all listening sockets.

      KMd->Kernel:         SADB_GETSPI for AH, addr, SPI range
      Kernel->All:         SADB_GETSPI for AH, assoc, addrs

     The KMd may perform a second GETSPI  operation  if  it  needs  both
   directions  of  IPsec SPI values.  Now that the KMd has an SPI for at
   least one of the security associations, it begins negotiation.  After
   deriving  keying material, and negotiating other parameters, it sends
   down one (or more)  SADB_UPDATE  messages  with  the  same  value  in
   sadb_msg_seq.

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

      KMd->Kernel:         SADB_UPDATE for AH, assoc (with an error)
      Kernel->All:         SADB_UPDATE for AH, assoc (same error)

   but if it succeeds, it can instead

      KMd->Kernel:         SADB_UPDATE for AH, assoc, addrs, keys,
                           <etc.>
      Kernel->All:         SADB_UPDATE for AH, assoc, addrs, <etc.>

   The results of the UPDATE (minus the actual keys)  are  sent  to  all
   listening sockets.  If only one SPI value was determined locally, the
   other SPI (since IPsec SAs are unidirectional) must be added with  an
   SADB_ADD message.

      KMd->Kernel:         SADB_ADD for AH, assoc, addrs, keys, <etc.>
      Kernel->All:         SADB_ADD for AH, assoc, addrs, <etc.>

     If one of the extensions passed down was a Lifetime  extension,  it
   is possible at some point an SADB_EXPIRE message will arrive when one
   of the lifetimes has expired.

      Kernel->All:         SADB_EXPIRE for AH, assoc, addrs,
                           Hard or Soft, Current, <etc.>

     The KMd can use this as a clue to begin negotiation, or, if it  has
   some  say  in  policy,  send  an  SADB_UPDATE  down  with  a lifetime
   extension.

McDonald, Metz, and Phan  Expires in 6 months          [Page 49]
Internet Draft            PF_KEY, Version 2             28 February 1998

5.2 Proxy IP Security Example

           Many people are interested in using IP Security in a  "proxy"
   or  "firewall" configuration in which an intermediate system provides
   security services for "inside"  hosts.  In  these  environments,  the
   intermediate   systems   can  use  PF_KEY  to  communicate  with  key
   management applications almost exactly as they would if they were the
   actual  endpoints. The messaging behavior of PF_KEY in these cases is
   exactly the same as the previous example, but the address information
   is slightly different.

     Consider this case:

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

     Key:
               A           "outside" host that implements IPsec
               B           "firewall" that implements IPsec
               C           "inside" host that does not implement IPsec

               ===         IP_{A<->B} ESP [ IP_{A<->C} ULP ]
               ---         IP_{A<->C} ULP

     A is a single system that wishes to communicate with  the  "inside"
   system  C.   B  is  a "firewall" between C and the outside world that
   will do ESP and tunneling on C's behalf.   A discovers that it  needs
   to send traffic to C via B through methods not described here (Use of
   the DNS' KX record might be one method for discovering this).

           For packets that flow from left to right, A  and  B  need  an
   IPsec Security Association with:

           SA type of ESP tunnel-mode
           Source Identity that dominates A (e.g. A's address)
           Destination Identity that dominates B (e.g. B's address)
           No Proxy Identity or a Proxy Identity that dominates A.

           For packets to flow from right to left, A and B need an IPsec
   Security Association with:
           SA type of ESP tunnel-mode
           Source Identity that dominates C.
           Destination Identity that dominates A.
           Proxy Identity that dominates B.

   For this second SA (for packets flowing from C  towards  A),  node  A
   MUST  verify  that the outer source address is dominated by the Proxy
   Identity for the SA used with those packets.  If node A does  not  do
   this,  node  B  could forge packets with an arbitrary Source Identity

McDonald, Metz, and Phan  Expires in 6 months          [Page 50]
Internet Draft            PF_KEY, Version 2             28 February 1998

   and defeat the packet origin protections provided by IPsec.

     Now consider a slightly more complex case:

               A_1 --|                  |-- D_1
                     |--- B ====== C ---|
               A_2 --|                  |-- D_2

     Key:
               A_n     "inside" host on net 1 that does not do IPsec.
               B       "firewall" for net 1 that supports IPsec.
               C       "firewall" for net 2 that supports IPsec.
               D_n     "inside" host on net 2 that does not do IPsec.
               ===     IP_{B<->C} ESP [ IP_{A<->C} ULP ]
               ---     IP_{A<->C} ULP

           For A_1 to send a packet to D_1, B and C need a SA with:

                   SA Type of ESP
                   Source Identity that dominates A_1.
                   Destination Identity that dominates C.
                   Proxy Identity that dominates B.

           For D_1 to send a packet to A_1, C and B need a SA with:
                   SA Type of ESP Tunnel-mode
                   Source Identity that dominates D_1.
                   Destination Identity that dominates B.
                   Proxy Identity that dominates C.

           Note that A_2 and D_2 could be substituted for  A_1  and  D_1
   (respectively)  here; the association of an SA with a particular pair
   of ends or group of those pairs is a policy decision on  B  and/or  C
   and  not necessarily a function of key management.  The same check of
   the Proxy Identity against the outer source IP address MUST  also  be
   performed in this case for the same reason.

     For a more detailed discussion of the use of IP Security in complex
   cases, please see [Atk97].

      NOTE: The notion of identity domination might be unfamiliar.
      Let H represent some node. Let Hn represent H's fully qualified
      domain name. Let Ha represent the IP address of H. Let Hs
      represent the IP subnet containing Ha. Let Hd represent a fully
      qualified domain name that is a parent of the fully qualified
      domain name of H. Let M be a UserFQDN identity that whose right-
      hand part is Hn or Ha.

McDonald, Metz, and Phan  Expires in 6 months          [Page 51]
Internet Draft            PF_KEY, Version 2             28 February 1998

      Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the
      example above. Hs dominates any node having an IP address
      within the IP address range represented by Hs. Hd dominates any
      node having a fully qualified domain name within underneath Hd.

5.3 OSPF Security Example

              +---------------+    +-------------+
              |Key Mgmt Daemon|    | OSPF daemon |
              +---------------+    +-------------+
                |           |     /    /        |
                |    /------|----+    /         |
                |   /       |    +---+          |           Applications
        ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================
                |           |    |              |           OS Kernel
        +------------+   +-----------------+  +---------+
        | Key Engine |   | TCP/IP,         |  | Routing |
        |  or  SADB  |---| including IPsec |--| Table   |
        +------------+   |                 |  +---------+
                         +-----------------+

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

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

      OSPFd->Kernel:       SADB_GET of OSPF, assoc, addrs
      Kernel->OSPFd:       SADB_GET of OSPF, assoc, addrs, keys, <etc.>

     If this GET fails, the OSPFd may need to  acquire  a  new  security
   association.  This interaction is as follows:

      OSPFd->Kernel:       SADB_ACQUIRE of OSPF, addrs, <ID, sens,>
                           proposal
      Kernel->Registered:  SADB_ACQUIRE of OSPF, <same as sent message>

     The KMd sees this and performs  actions  similar  to  the  previous
   example.   One  difference,  however, is that when the UPDATE message
   comes back, the OSPFd will then perform a GET of the  updated  SA  to
   retrieve all of its parameters.

5.4 Miscellaneous

     Some messages work well only in system  maintenance  programs,  for

McDonald, Metz, and Phan  Expires in 6 months          [Page 52]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 53]
Internet Draft            PF_KEY, Version 2             28 February 1998

6 Security Considerations

     This draft discusses a method for creating, reading, modifying, and
   deleting  Security  Associations  from  an  operating  system.   Only
   trusted, privileged users and processes should be able to perform any
   of  these  operations.  It is unclear whether this mechanism provides
   any security when used with operating systems not having the  concept
   of a trusted, privileged user.

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

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

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 54]
Internet Draft            PF_KEY, Version 2             28 February 1998

Acknowledgments

     The authors of this document are listed primarily  in  alphabetical
   order.   Randall  Atkinson  and  Ron  Lee provided useful feedback on
   earlier versions of this document.

     At one time or other, all of the authors worked at the  Center  for
   High   Assurance   Computer   Systems  at  the  U.S.  Naval  Research
   Laboratory. This work  was  sponsored  by  the  Information  Security
   Program  Office  (PMW-161),  U.S.  Space  and  Naval  Warfare Systems
   Command (SPAWAR) and the Computing Systems Technology Office, Defense
   Advanced  Research Projects Agency (DARPA/CSTO). We really appreciate
   their sponsorship of our  efforts  and  their  continued  support  of
   PF_KEY development. Without that support, PF_KEY would not exist.

     The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST97].

     Finally, the authors would like to thank those who sent in comments
   and  questions  on  the  various  iterations  of  this document. This
   specification and implementations of it are discussed on  the  PF_KEY
   mailing list. If you would like to be added to this list, send a note
   to <pf_key-request@inner.net>.

McDonald, Metz, and Phan  Expires in 6 months          [Page 55]
Internet Draft            PF_KEY, Version 2             28 February 1998

References

   [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig
            W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in
            4.4-Lite BSD", Proceedings of the 1996 USENIX Conference,
            San Diego, CA, January 1996, USENIX Association.

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

   [Atk97]  Atkinson, Randall, "Key Exchange Delegation Record for the
            Domain Name System", Internet-draft, June 1997."

   [BA97]   F. Baker and R. Atkinson, "RIP-2 MD5 Authentication",
            RFC 2082, January 1997.

   [Baker97] Fred Baker, "RSVP Cryptographic Authentication", Internet
            Draft, May 1997.

   [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer
            Systems", MTR-3153, The MITRE Corporation, June 1975;
            ESD-TR-76-372, April 1977.

   [BL74]   D. Elliot Bell and Leonard J. LaPadula, "Secure Computer
            Systems: Unified Exposition and Multics Interpretation",
            MTR 2997, The MITRE Corporation, April 1974. (AD/A 020 445)

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

   [CW87]   D. D. Clark and D. R. Wilson, "A Comparison of Commercial
            and Military Computer Security Policies", Proceedings of the
            1987 Symposium on Security and Privacy, pp. 184-195, IEEE
            Computer Society, Washington, D.C., 1987

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

   [DMS97]  Dorsaway, N., Metzger, P., Simpson, W. A., "The ESP Triple-
            DES Transform," Internet-Draft.

McDonald, Metz, and Phan  Expires in 6 months          [Page 56]
Internet Draft            PF_KEY, Version 2             28 February 1998

   [HM97a]  H. Harney, C. Muckenhirn, "Group Key Management Protocol
            (GKMP) Specification", RFC 2093, July 1997.

   [HM97b]  H. Harney, C. Muckenhirn, "Group Key Management Protocol
            (GKMP) Architecture", RFC 2094, July 1997.

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

   [MSST97] Douglas Maughan, Mark Schertler, Mark Schneider, Jeff
            Turner, "Internet Security Association and Key Management
            Protocol (ISAKMP)", Internet Draft, February 1997.

   [Moy97]  J. Moy, "OSPF Version 2", Internet Draft, April 1997.

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

   [Perkins97] C. Perkins, "IP Mobility Support", RFC 2002,
            October 1996.

   [Piper97] Derrel Piper, "The Internet IP Security Domain of
            Interpretation for ISAKMP", Internet Draft, February 1997.

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 57]
Internet Draft            PF_KEY, Version 2             28 February 1998

Disclaimer

     The views and specification here are those of the editors  and  are
   not  necessarily  those  of  their employers.  The employers have not
   passed judgment on the merits, if any, of this work.  The editors and
   their employers specifically disclaim responsibility for any problems
   arising from correct or  incorrect  implementation  or  use  of  this
   specification.

Authors' Addresses

              Daniel L. McDonald
              Sun Microsystems, Inc.
              901 San Antonio Road, MS UMPK17-202
              Palo Alto, CA 94303
              E-mail: danmcd@eng.sun.com

              Craig Metz
              The Inner Net
              Box 10314-1932
              Blacksburg, VA 24062-0314
              DSN:    754-8590
              E-mail: cmetz@inner.net

              Bao G. Phan
              U. S. Naval Research Laboratory
              phan@itd.nrl.navy.mil

McDonald, Metz, and Phan  Expires in 6 months          [Page 58]
Internet Draft            PF_KEY, Version 2             28 February 1998

Appendix A: Promiscuous Send/Receive Extension

     A kernel supporting PF_KEY MAY implement  the  following  extension
   for development and debugging purposes. If it does, it MUST implement
   the extension as specified here. An  implementation  MAY  require  an
   application to have additional privileges to perform promiscuous send
   and/or receive operations.

     The SADB_X_PROMISC  message  allows  an  application  to  send  and
   receive messages in a "promiscuous mode." There are two forms of this
   message:  control and data. The  control  form  consists  of  only  a
   message  header.   This  message  is  used to toggle the promiscuous-
   receive function. A value of one in the sadb_msg_satype field enables
   promiscuous  message reception for this socket, while a value of zero
   in that field disables it.

     The second form of this message is the data form. This is  used  to
   send or receive messages in their raw form. Messages in the data form
   consist of a message header followed by an entire new message.  There
   will  be  two  message  headers  in a row: one for the SADB_X_PROMISC
   message, and one for the payload message.

     Data messages sent from the application  are  sent  to  either  the
   PF_KEY   socket   of   a  single  process  identified  by  a  nonzero
   sadb_msg_seq or to all PF_KEY sockets if sadb_msg_seq is zero.  These
   messages  are  sent  without  any processing of their contents by the
   PF_KEY interface (including sanity checking).  This  promiscuous-send
   capability  allows  an application to send messages as if it were the
   kernel. This also allows it to send erroneous messages.

     If the promiscuous-receive function has been enabled, a copy of any
   message  sent  via  PF_KEY by another application or by the kernel is
   sent  to  the  promiscuous  application.  This  is  done  before  any
   processing  of the message's contents by the PF_KEY interface (again,
   including  sanity  checking).  This  promiscuous-receive   capability
   allows  an  application to receive all messages sent by other parties
   using PF_KEY.

     The messaging behavior of the SADB_X_PROMISC message is:

        Send a control-form SADB_X_PROMISC message from a user process
        to the kernel.

        <base>

        The kernel returns the SADB_X_PROMISC message to all listening
        processes.

McDonald, Metz, and Phan  Expires in 6 months          [Page 59]
Internet Draft            PF_KEY, Version 2             28 February 1998

        <base>

        Send a data-form SADB_X_PROMISC message from a user process to
        the kernel.

        <base, base(, others)>

        The kernel sends the encapsulated message to the target
        process(s).

        <base(, others)>

        If promiscuous-receive is enabled, the kernel will encapsulate
        and send copies of all messages sent via the PF_KEY interface.

        <base, base(, others)>

    Errors:
        EPERM Additional privileges are required to perform the
              requested operations.
        ESRCH (Data form, sending) The target process in sadb_msg_seq
              does not exist or does not have an open PF_KEY Version 2
              socket.

McDonald, Metz, and Phan  Expires in 6 months          [Page 60]
Internet Draft            PF_KEY, Version 2             28 February 1998

Appendix B: Passive Change Message Extension

     The SADB_X_PCHANGE message is a passive-side (aka.  the  "listener"
   or "receiver") counterpart to the SADB_ACQUIRE message.  It is useful
   for when key management applications wish to more effectively  handle
   incoming  key  management  requests  for  passive-side  sessions that
   deviate from systemwide default  security  services.   If  a  passive
   session  requests  that  only  certain  levels of security service be
   allowed, the SADB_X_PCHANGE message  expresses  this  change  to  any
   registered  PF_KEY  sockets.   Unlike  SADB_ACQUIRE,  this message is
   purely informational, and demands no other PF_KEY interaction.

     The SADB_X_PCHANGE message  is  typically  triggered  by  either  a
   change  in  an  endpoint's  requested  security  services, or when an
   endpoint that made a special request disappears.  In the former case,
   an  SADB_X_PCHANGE  looks  like  an  SADB_ACQUIRE,  complete  with an
   sadb_proposal  extension   indicating   the   preferred   algorithms,
   lifetimes,  and  other  attributes.   When  a  passive session either
   disappears, or reverts to a default behavior, an SADB_X_PCHANGE  will
   be  issued  with  _no_  sadb_proposal  extension, indicating that the
   exception to systemwide default behavior has disappeared.

     There are two messaging behaviors for SADB_X_PCHANGE.  The first is
   the kernel-originated case:

        The kernel sends an SADB_X_PCHANGE message to registered sockets.
n
        <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>

        NOTE:   The address(SD) extensions MUST have the port fields
                filled in with the port numbers of the session requiring
                keys if appropriate.

  The second is for a user-level consumer of SAs.

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

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

        The kernel returns an SADB_X_PCHANGE message to registered sockets.

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

McDonald, Metz, and Phan  Expires in 6 months          [Page 61]
Internet Draft            PF_KEY, Version 2             28 February 1998

Appendix C: Sample Header File

   /*
   This file defines structures and symbols for the PF_KEY Version 2
   key management interface. It was written at the U.S. Naval Research
   Laboratory. This file is in the public domain. The authors ask that
   you leave this credit intact on any copies of this file.
   */
   #ifndef __PFKEY_V2_H
   #define __PFKEY_V2_H 1

   #define PF_KEY_V2 2
   #define PFKEYV2_REVISION        199802L

   #define SADB_RESERVED    0
   #define SADB_GETSPI      1
   #define SADB_UPDATE      2
   #define SADB_ADD         3
   #define SADB_DELETE      4
   #define SADB_GET         5
   #define SADB_ACQUIRE     6
   #define SADB_REGISTER    7
   #define SADB_EXPIRE      8
   #define SADB_FLUSH       9
   #define SADB_DUMP        10
   #define SADB_X_PROMISC   11
   #define SADB_X_PCHANGE   12
   #define SADB_MAX         12

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

   struct sadb_ext {
     uint16_t sadb_ext_len;
     uint16_t sadb_ext_type;
   };

McDonald, Metz, and Phan  Expires in 6 months          [Page 62]
Internet Draft            PF_KEY, Version 2             28 February 1998

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

   struct sadb_lifetime {
     uint16_t sadb_lifetime_len;
     uint16_t sadb_lifetime_exttype;
     uint32_t sadb_lifetime_allocations;
     uint64_t sadb_lifetime_bytes;
     uint64_t sadb_lifetime_addtime;
     uint64_t sadb_lifetime_usetime;
   };

   struct sadb_address {
     uint16_t sadb_address_len;
     uint16_t sadb_address_exttype;
     uint8_t sadb_address_proto;
     uint8_t sadb_address_prefixlen;
     uint16_t sadb_address_reserved;
   };

   struct sadb_key {
     uint16_t sadb_key_len;
     uint16_t sadb_key_exttype;
     uint16_t sadb_key_bits;
     uint16_t sadb_key_reserved;
   };

   struct sadb_ident {
     uint16_t sadb_ident_len;
     uint16_t sadb_ident_exttype;
     uint16_t sadb_ident_type;
     uint16_t sadb_ident_reserved;
     uint64_t sadb_ident_id;
   };

McDonald, Metz, and Phan  Expires in 6 months          [Page 63]
Internet Draft            PF_KEY, Version 2             28 February 1998

   struct sadb_sens {
     uint16_t sadb_sens_len;
     uint16_t sadb_sens_exttype;
     uint32_t sadb_sens_dpd;
     uint8_t sadb_sens_sens_level;
     uint8_t sadb_sens_sens_len;
     uint8_t sadb_sens_integ_level;
     uint8_t sadb_sens_integ_len;
     uint32_t sadb_sens_reserved;
   };

   struct sadb_prop {
     uint16_t sadb_prop_len;
     uint16_t sadb_prop_exttype;
     uint8_t sadb_prop_replay;
     uint8_t sadb_prop_reserved[3];
   };

   struct sadb_comb {
     uint8_t sadb_comb_auth;
     uint8_t sadb_comb_encrypt;
     uint16_t sadb_comb_flags;
     uint16_t sadb_comb_auth_minbits;
     uint16_t sadb_comb_auth_maxbits;
     uint16_t sadb_comb_encrypt_minbits;
     uint16_t sadb_comb_encrypt_maxbits;
     uint32_t sadb_comb_reserved;
     uint32_t sadb_comb_soft_allocations;
     uint32_t sadb_comb_hard_allocations;
     uint64_t sadb_comb_soft_bytes;
     uint64_t sadb_comb_hard_bytes;
     uint64_t sadb_comb_soft_addtime;
     uint64_t sadb_comb_hard_addtime;
     uint64_t sadb_comb_soft_usetime;
     uint64_t sadb_comb_hard_usetime;
   };

McDonald, Metz, and Phan  Expires in 6 months          [Page 64]
Internet Draft            PF_KEY, Version 2             28 February 1998

   struct sadb_supported {
     uint16_t sadb_supported_len;
     uint16_t sadb_supported_exttype;
     uint32_t sadb_supported_reserved;
   };

   struct sadb_alg {
     uint8_t sadb_alg_id;
     uint8_t sadb_alg_ivlen;
     uint16_t sadb_alg_minbits;
     uint16_t sadb_alg_maxbits;
     uint16_t sadb_alg_reserved;
   };

   struct sadb_spirange {
     uint16_t sadb_spirange_len;
     uint16_t sadb_spirange_exttype;
     uint32_t sadb_spirange_min;
     uint32_t sadb_spirange_max;
     uint32_t sadb_spirange_reserved;
   };

   #define SADB_EXT_RESERVED             0
   #define SADB_EXT_SA                   1
   #define SADB_EXT_LIFETIME_CURRENT     2
   #define SADB_EXT_LIFETIME_HARD        3
   #define SADB_EXT_LIFETIME_SOFT        4
   #define SADB_EXT_ADDRESS_SRC          5
   #define SADB_EXT_ADDRESS_DST          6
   #define SADB_EXT_ADDRESS_PROXY        7
   #define SADB_EXT_KEY_AUTH             8
   #define SADB_EXT_KEY_ENCRYPT          9
   #define SADB_EXT_IDENTITY_SRC         10
   #define SADB_EXT_IDENTITY_DST         11
   #define SADB_EXT_SENSITIVITY          12
   #define SADB_EXT_PROPOSAL             13
   #define SADB_EXT_SUPPORTED_AUTH       14
   #define SADB_EXT_SUPPORTED_ENCRYPT    15
   #define SADB_EXT_SPIRANGE             16
   #define SADB_EXT_MAX                  16

   #define SADB_SATYPE_UNSPEC    0
   #define SADB_SATYPE_AH        1
   #define SADB_SATYPE_ESP       2
   #define SADB_SATYPE_RSVP      3
   #define SADB_SATYPE_OSPFV2    4
   #define SADB_SATYPE_RIPV2     5
   #define SADB_SATYPE_MIP       6

McDonald, Metz, and Phan  Expires in 6 months          [Page 65]
Internet Draft            PF_KEY, Version 2             28 February 1998

   #define SADB_SATYPE_MAX       6

   #define SADB_SASTATE_LARVAL   0
   #define SADB_SASTATE_MATURE   1
   #define SADB_SASTATE_DYING    2
   #define SADB_SASTATE_DEAD     3
   #define SADB_SASTATE_MAX      3

   #define SADB_SAFLAGS_PFS      1

   #define SADB_AALG_NONE        0
   #define SADB_AALG_MD5HMAC     1
   #define SADB_AALG_SHA1HMAC    2
   #define SADB_AALG_MAX         2

   #define SADB_EALG_NONE        0
   #define SADB_EALG_DESCBC      1
   #define SADB_EALG_3DESCBC     2
   #define SADB_EALG_MAX         2

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

   #define SADB_KEY_FLAGS_MAX 0
   #endif /* __PFKEY_V2_H */

McDonald, Metz, and Phan  Expires in 6 months          [Page 66]
Internet Draft            PF_KEY, Version 2             28 February 1998

Appendix D: Change Log

   The following changes were made between 04 and 05:

   * New appendix on Passive Change message.

   * New sadb_address_prefixlen field.

   * Small clarifications on sadb_ident_id usage.

   * New PFKEYV2_REVISION value.

   * Small clarification on what a PROXY address is.

   * Corrected sadb_spirange_{min,max} language.

   * In ADD messages that are in response to an ACQUIRE, the sadb_msg_seq MUST
     be the same as that of the originating ACQUIRE.

   * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up PROXY
     addresses when it needs them.

   * Clarification on SADB_EXPIRE and user-level security protocols.

   The following changes were made between 03 and 04:

   * Stronger language about manual keying.

   * PFKEYV2_REVISION, ala POSIX.

   * Put in language about sockaddr ports in ACQUIRE messages.

   * Mention of asymmetric algorithms.

   * New sadb_ident_id field for easier construction of USER_FQDN identity
   strings.

   * Caveat about source addresses not always used for collision detection.
     (e.g. IPsec)

   The following changes were made between 02 and 03:

McDonald, Metz, and Phan  Expires in 6 months          [Page 67]
Internet Draft            PF_KEY, Version 2             28 February 1998

   * Formatting changes.

   * Many editorial cleanups, rewordings, clarifications.

   * Restrictions that prevent many strange and invalid cases.

   * Added definitions section.

   * Removed connection identity type (this will reappear when it is
     more clear what it should look like).

   * Removed 5.2.1 (Why involve the kernel?).

   * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed
     from src, dst, and proxy and you had to anyway for sanity checking.

   * Removed REPLAY flag; sadb_sa_replay==0 means the same thing.

   * Renamed bit lengths to "bits" to avoid potential confusion.

   * Explicitly listed lengths for structures.

   * Reworked identities to always use a string format.

   * Removed requirements for support of shutdown() and SO_USELOOPBACK.

   * 64 bit alignment and 64 bit lengths instead of 32 bit.

   * time_t replaced with uint64 in lifetimes.

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

   * Explicit error if PF_KEY_V2 not set at socket() call.

   * More text on SO_USELOOPBACK.

   * Made fields names and symbol names more consistent.

   * Explicit error if PF_KEY_V2 is not in sadb_msg_version field.

   * Bytes lifetime field now a 64-bit quantity.

   * Explicit len/exttype wording.

   * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.)

   * UI example (0x123 == 0x1230 or 0x0123).

McDonald, Metz, and Phan  Expires in 6 months          [Page 68]
Internet Draft            PF_KEY, Version 2             28 February 1998

   * Cleaned up and fixed some message behavior examples.

   The following changes were made between 01 and 02:

   * Mentioned that people COULD use these same messages between user
     progs. (Also mentioned why you still might want to use the actual
     socket.)

   * Various wordsmithing changes.

   * Took out netkey/ directory, and make net/pfkeyv2.h

   * Inserted PF_KEY_V2 proto argument per C. Metz.

   * Mentioned other socket calls and how their PF_KEY behavior is
     undefined.

   * SADB_EXPIRE now communicates both hard and soft lifetime expires.

   * New "association" extension, even smaller base header.

   * Lifetime extension improvements.

   * Length now first in extensions.

   * Errors can be sent from kernel to user, also.

   * Examples section inserted.

   * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup.

   * Key splitting now only across auth algorithm and encryption
     algorithm. Thanks for B. Sommerfeld for clues here.

   The following changes were made between 00 and 01:

   * Added this change log.

   * Simplified TLV header syntax.

   * Splitting of algorithms. This may be controversial, but it allows
     PF_KEY to be used for more than just IPsec. It also allows some
     kinds of policies to be placed in the KMd easier.

   * Added solid definitions and formats for certificate identities,
     multiple keys, etc.

   * Specified how keys are to be layed out (most-to-least bits).

McDonald, Metz, and Phan  Expires in 6 months          [Page 69]
Internet Draft            PF_KEY, Version 2             28 February 1998

   * Changed sequence number semantics to be like an RPC transaction ID
     number.

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