HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 10:05:12 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Thu, 20 Mar 1997 00:14:00 GMT ETag: "361e9b-1439c-33308148" Accept-Ranges: bytes Content-Length: 82844 Connection: close Content-Type: text/plain Network Working Group D. L. McDonald Internet Draft C. W. Metz draft-mcdonald-pf-key-v2-01.txt B. G. Phan 17 March 1997 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". A future version of 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. an ISAKMP daemon, a Photuris daemon or SKIP certificate discovery protocol daemon). 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 McDonald, Metz, and Phan Expires in 6 months [Page 1] Internet Draft PF_KEY, Version 2 17 March 1997 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. 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 In this document, the words that are used to define the significance of each particular requirement 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 This word or the adjective "OPTIONAL" means that this item is truly optional. One vendor might choose to include the item because a particular marketplace requires it or because it enhances the product, for example; another vendor may omit the same item. McDonald, Metz, and Phan Expires in 6 months [Page 2] Internet Draft PF_KEY, Version 2 17 March 1997 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 Photuris, ISAKMP, and Oakley proposals for IPsec key management are all application-layer protocols. Even parts of the SKIP IP-layer keying proposal can be implemented at the application layer. Figure 1 shows the relationship between a Key Management daemon and PF_KEY, which it uses to communicate with the Key Engine, and PF_INET (or PF_INET6 in the case of IPv6), which it uses to communicate via the network with a remote key management entity. The "Key Engine" or "Security Association Database (SADB)" is a logical entity in the kernel that stores, updates, and deletes Security Association data for various security protocols. There are logical interfaces within the kernel (e.g. getassocbyspi(), getassocbysocket()) that security protocols inside the kernel (e.g. IP Security, aka IPsec) use to request and obtain Security 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. +---------------+ |Key Mgmt Daemon| +---------------+ | | | | | | Applications ======[PF_KEY]====[PF_INET]========================== | | OS Kernel McDonald, Metz, and Phan Expires in 6 months [Page 3] Internet Draft PF_KEY, Version 2 17 March 1997 +------------+ +-----------------+ | Key Engine | | TCP/IP, | | or SADB |---| including IPsec | +------------+ | | +-----------------+ | +-----------+ | Network | | Interface | +-----------+ Figure 1: Relationship of Key Mgmt to PF_KEY For performance reasons, some security protocols (e.g. IP Security) are usually implemented inside the operating system kernel. Other security protocols (e.g. OSPFv2 Cryptographic Authentication) are implemented in trusted privileged applications outside the kernel. Figure 2 shows a trusted, privileged routing daemon using PF_INET to communicate routing information with a remote routing daemon and using PF_KEY to request, obtain, and delete Security Associations used with a routing protocol. +---------------+ |Routing Daemon| +---------------+ | | | | | | Applications ======[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 McDonald, Metz, and Phan Expires in 6 months [Page 4] Internet Draft PF_KEY, Version 2 17 March 1997 before, the key management daemon stores the SA into the Key Engine. Then, the trusted privileged application uses a SADB_GET message to obtain the SA from the Key Engine. In some implementations, policy may be implemented in user-space, even though the actually cryptographic processing takes place in the kernel. Such policy communication between the kernel mechanisms and the user-space policy MAY be implemented by PF_KEY extensions, or other such mechanism. This document will not specify such 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 in the same manner that other protocol families are defined. PF_KEY does not use any socket addresses. Applications using PF_KEY MUST NOT depend on the availability of a symbol named AF_KEY, but kernel implementations are encouraged to define that symbol for completeness. The key socket is created as follows: #include int s; s = socket(PF_KEY, SOCK_RAW, 0) The PF_KEY domain currently supports only the SOCK_RAW socket type. The protocol field MUST be set to 0. Only a trusted, privileged process can create a PF_KEY socket. On conventional UNIX systems, a privileged process is a process with an effective userid of zero. On non-MLS proprietary operating systems, the notion of a "privileged process" is implementation-defined. On Compartmented Mode Workstations (CMWs) or other systems that claim to provide Multi- Level Security (MLS), a process MUST have the "key management privilege" in order to open a PF_KEY socket[DIA]. MLS systems that don't currently have such a specific privilege MUST add that special privilege and enforce it with PF_KEY in order to comply and conform with this specification. Some systems, most notably some popular personal computers, do not have the concept of a privileged user. These systems SHOULD take steps to restrict the programs allowed to McDonald, Metz, and Phan Expires in 6 months [Page 5] Internet Draft PF_KEY, Version 2 17 March 1997 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 messages sent to the kernel are returned to all open PF_KEY sockets, including the sender. A process can disable this looping back of messages it generates by disabling the SO_USELOOPBACK option using the setsockopt(2) call. A PF_KEY socket listener, which by default receives all replies may disable message reception by terminating socket input with the shutdown(2) call. PF_KEY message delivery is not guaranteed, especially in cases where kernel or socket buffers are exhausted and messages are dropped. Some messages are generated by the operating system to indicate that actions need to be taken, and are not necessarily in response to any message sent down by the user. Such messages are not received by all PF_KEY sockets, but by sockets which have indicated that kernel- originated messages are to be received. These messages are special because of the expected frequency at which they will occur. Also, an implementation may further wish to restrict return message from the kernel, in cases where not all PF_KEY sockets are in the same trust domain. ******* NOTE: SECTIONS LIKE THIS, INSIDE ******* ARE META-COMMENTS AND OPEN ISSUES THAT NEED CONTEXT TO BE CLEAR. [RJA: Clarifying text on security restrictions is needed here, IMHO.] ******* 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. 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 McDonald, Metz, and Phan Expires in 6 months [Page 6] Internet Draft PF_KEY, Version 2 17 March 1997 (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 and SADB_UPDATE messages, in order to keep track of which request gets its keying material. The sequence number (described below) is analogous to a transaction ID in a remote procedure call. The SADB_EXPIRE message is sent from the kernel to key management applications when the "soft lifetime" or "hard lifetime" of a Security Association has expired. Key management applications should use receipt of a 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 implementer debugging and is not used in ordinary operation of PF_KEY. 1.6 DIFFERENCES BETWEEN PF_KEY AND THE PF_ROUTE ROUTING SOCKET The following bullets are points of difference between the routing socket and PF_KEY. Programmers who are used to the routing socket semantics will find some subtle differences in PF_KEY. * The write() call doesn't return the PF_KEY error number, only the return message has the PF_KEY error number in cases of malformed fields. This means that if SO_USELOOPBACK is disabled, error checking is hard. * The entire message isn't always reflected in the reply. An SADB_ADD is a good example of this. * The PID is not set by the kernel. The process that originates the message MUST set the sadb_msg_pid to its own PID. If the kernel originates a message, it MUST set the sadb_msg_pid to 0. McDonald, Metz, and Phan Expires in 6 months [Page 7] Internet Draft PF_KEY, Version 2 17 March 1997 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_hdr { /* Basic hdr stuff */ uint8_t sadb_version; /* 2 */ uint8_t sadb_msg_type; uint8_t sadb_msg_errno; uint8_t sadb_sa_type; uint16_t sadb_msg_len; /* In 32-bit words, incl. */ uint16_t sadb_sa_assocopts; uint32_t sadb_msg_seq; uint32_t sadb_msg_pid; /* Basic SA stuff */ uint32_t sadb_sa_spi; uint8_t sadb_sa_replay_window_len; uint8_t sadb_sa_state; uint8_t sadb_sa_encrypt; /* Or uint16_t */ uint8_t sadb_sa_auth; /* sadb_sa_transform */ }; sadb_version The version field of this PF_KEY message. Set to 2. sadb_msg_type Identifies the type of message. The valid message types are described later in this document. sadb_msg_errno Should be set to zero by the sender. The replier stores the error code in this field if an error has occured. McDonald, Metz, and Phan Expires in 6 months [Page 8] Internet Draft PF_KEY, Version 2 17 March 1997 ******* [C. Metz: In some cases, it may be useful for the user-space program to send errnos. In the case of proxying key management, a EHOSTUNREACH may tell the kernel that there is no peer for this server. For that matter such errnos could work in the cases of no peer KMd being present. These are in the context of having received an ACQUIRE message.] ******* sadb_sa_type indicates the type of security association (e.g. AH, ESP, OSPF, etc). Valid Security Association types are declared in the file . The current set of Security Association types are enumerated later in this document. sadb_msg_len Contains the total length, in 32-bit words, of all data in the PF_KEY message including the base header length and additional data after the base header, if any. This length includes any padding or extra space that might exist. Unless otherwise stated, all other length fields are also measured in 32-bit words. sadb_sa_assocopts Contains a bitmap of options defined for the security assocation (e.g. replay protection, PFS, etc.). ******* [Dan McD: I may need to re-split these up into algorithm flags and association flags. Some of these span both, some don't. ] ******* sadb_msg_seq Contains the sequence number of this message. This field, along with sadb_msg_pid, SHOULD be used to uniquely identify requests to a process. The sender is responsible for filling in this field. This resposibility also includes matching the sadb_msg_seq of a request (e.g. SADB_ACQUIRE). This field is analogous to a transaction ID in a remote procedure call implementation. ******* [Dan McD.: It may turn out that both sequence number and transaction id are needed. In that case, I'll add another uint32_t.] ******* sadb_msg_pid Identifies the process which originated this message, or which process a message is bound for. For example: If McDonald, Metz, and Phan Expires in 6 months [Page 9] Internet Draft PF_KEY, Version 2 17 March 1997 process id 2112 sends a SADB_UPDATE message to the kernel, the message to the kernel MUST set its process id to 2112, and the SADB_UPDATE reply from the kernel will fill in this fields with 2112. This field, along with sadb_msg_seq, can be used to uniquely identify requests to a process. It is currently believed that a 32-bit quantity will hold an operating system's process ID space. If this assumption is not true, then sadb_msg_pid will have to be revisited. ******* [Dan McD.: The seq and pid fields semantics change explicitly from the routing socket semantics. This better facilitates asynchronous kernels, while not taking away anything from synchronous kernels. ] ******* sadb_sa_spi Contains the Security Parameters Index value for the Security Association. Although this is a 32-bit field, some types of Security Association might have an SPI or key identifier that is less than 32-bits long. In this case, the smaller value shall be stored in the least significant bits of this field and the unneeded bits shall be zero. This field MUST be in network byte order. ******* [Dan McD: ISAKMP can negotiate an SPI that's >32-bits. I may save this for v3, though.] ******* sadb_sa_replay_window_len Specifies the size of the replay window, if not zero. If zero, then no replay window is in use. sadb_sa_state Is a bitmask field containing the state of the Security Association. This field should be set to zero by the sending process and is set to the state of the Security Association when the message is received. The current set of State flags are enumerated later in this document. ******* [Dan McD: The following fields may get merged into one 16-bit sadb_sa_transform field, depending.] ******* sadb_sa_encrypt Identifies the encryption algorithm used for this security McDonald, Metz, and Phan Expires in 6 months [Page 10] Internet Draft PF_KEY, Version 2 17 March 1997 association. This can identify that no encryption is used for this association. See section 3.4 for values that can be placed in this field. sadb_sa_auth Identifies the authentication algorithm used for this security association. This can identify that no authentication is used for this association. See section 3.4 for values that can be placed in this field. The kernel MUST check sanity in these cases. For example AH with no authentication algorithm is probably an error. McDonald, Metz, and Phan Expires in 6 months [Page 11] Internet Draft PF_KEY, Version 2 17 March 1997 2.3 ADDITIONAL MESSAGE FIELDS The additional data following the base header consists of various type-length-values fields. The first 32-bits are of a constant form: struct sadb_ext_hdr { uint16_t ext_hdrtype; /* 0 is reserved */ uint16_t ext_len; /* In 32-bit words, inclusive */ }; There are currently seven types of extensions headers: Lifetime, Address, Key, Identity, Sensitivity, Proposal, and Supported. There SHOULD be only one instance of a extension type in a message. (e.g. Base, Key, Lifetime, Key is STRONGLY discouraged). All extensions MUST be implemented by a PF_KEY implementation. 2.3.1 LIFETIME EXTENSION The Lifetime extension specifies a lifetime 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. The Lifetime extension looks like: struct sadb_lifetime { uint16_t life_hdrtype; /* 1 */ uint16_t life_len; uint8_t life_type; /* Time, bytes, packets... */ uint8_t life_size; /* 2, 4, 8, 16, etc. octets */ uint16_t life_reserved; /* Or quantity */ /* uint64_t or uint32_t might follow. */ }; The life_size field is in octets, while the life_len field is in 32-bit words. The lifetime extension MAY be followed by a 32-bit aligned quantity if the life_size field is larger than 2 octets, otherwise the the lifetime itself can be stored in the 16-bit life_reserved field. Values for life_type are defined in the SYMBOLIC NAMES section. 2.3.2 ADDRESS EXTENSION The Address extension specifies one or more addresses that are associated with a security association. An Address extension MUST be present, and MUST specify at least the source and destination addresses. (The source address can be INADDR_ANY or it's IPv6 counterpart.) The format of an Address extension is: McDonald, Metz, and Phan Expires in 6 months [Page 12] Internet Draft PF_KEY, Version 2 17 March 1997 struct sadb_address { uint16_t addr_hdrtype; /* 2 */ uint16_t addr_len; uint8_t addr_which; /* Bitmask */ uint8_t addr_reserved[3]; /* Padding */ /* Followed by one or more struct sockaddr structures. */ }; The addr_which field contains a bitmask indicating what addresses; source, destination, inner-source, inner-destination, and proxy; follow. For each bit set in the addr_which field, a struct sockaddr follows. The sockaddr structure MUST conform to the sockaddr structure of the system implementing PF_KEY. (E.g. If the system has an sa_len field, so MUST the sockaddrs in the message. If the system has NO sa_len field, the sockaddrs MUST not have an sa_len field.) All non-address information in the sockaddrs MUST be zeroed out. 2.3.3 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_keyblk { uint16_t kb_hdrtype; /* 3 */ uint16_t kb_len; uint8_t kb_num_auth; /* # of auth. keys/ivs */ uint8_t kb_num_encrypt; /* # of encrypt. keys/ivs */ uint16_t kb_reserved; /* For 32-bit alignment */ /* Followed by sadb_key */ }; The Key extension is followed by the appropriate number of authentication or encryption keys. These keys are encoded as follows: struct sadb_key { uint8_t key_type; /* 3DES, DES, HMAC-MD5, etc. */ uint8_t key_flags; /* Right now, am I an IV? */ uint16_t key_length; /* Length of key in bits */ uint8_t key_key[4]; /* Actual key/iv. */ /* key_key is bounded by roundup(key_length / 8) */ }; The length of individual keys is in bits. Each key is padded to a 32-bit boundary. The key bits are arranged most-sigificant to least McDonald, Metz, and Phan Expires in 6 months [Page 13] Internet Draft PF_KEY, Version 2 17 March 1997 significant. For example, a 22-bit key would take up three octets, with the least significant two bits not containing key material. An additional octet would be used for padding to a 32-bit boundary. The key_flags field indicates currently if this key is actually a negotiated initialization vector. 2.3.4 IDENTITY EXTENSION The Identity extension contains endpoint identities. If this extension is not present, key management can assume that the addresses in the Address extension are the only identities for this Security Association. The Identity extension looks like: struct sadb_id_hdr { uint16_t idh_hdrtype; /* 4 */ uint16_t idh_len; uint32_t idh_which; /* bitmask */ /* Followed by one or more sadb_certids */ }; The idh_which field is a bitmask, indicating if source or destination certificate identities are present. Each identity is a 32-bit aligned quantity, specified as: struct sadb_certid { uint8_t certid_type; uint8_t certid_reserved[3]; /* May be used */ /* certid_reserved is unbounded */ }; Following each sadb_certid is 32-bit aligned data. Sometimes it is in the best interest to use the certid_reserved field for some of that data. The type of data can either be nothing (if the specified identity is the address), a null-terminated C string (for fully- qualified domain names, or mailbox identities), and address/mask pair (for address ranges), or a port-pair/protocol tuple, used in concert with the addresses. See the ILLUSTRATION OF MESSAGE LAYOUT section for details. 2.3.5 SENSITIVITY EXTENSION The Sensitiviy extension contains security labelling information for a security association. If this extension is not present, no sensitivity-related data can be obtained from this security association. If this extension is present, then the need for explicit security labelling on the packet is obviated. McDonald, Metz, and Phan Expires in 6 months [Page 14] Internet Draft PF_KEY, Version 2 17 March 1997 struct sadb_sens_hdr { uint16_t sens_hdrtype; /* 5 */ uint16_t sens_len; uint32_t sens_dpd; uint8_t sens_sens_level; uint8_t sens_sens_bitmap_len; /* bytes */ uint8_t sens_integ_level; uint8_t sens_integ_bitmap_len; /* bytes */ /* * followed by two uint8_t arrays * uint8_t sens_bitmap[sens_bitmap_len]; * uint8_t integ_bitmap[integ_bitmap_len]; */ }; The lengths of the bitmaps are in bytes. Following this field are the bitmaps. Only at the end of the second bitmap does padding to 32-bits occur. The sens_dpd describes the protection domain, which allows interpretation of the levels and compartment bitmaps. 2.3.6 PROPOSAL EXTENSION The Proposal extension contains a "proposed situation" of algorithm preferences. It looks like: struct sadb_prop_hdr { uint16_t proph_hdrtype; /* 6 */ uint16_t proph_len; uint8_t proph_num_auth; /* # of ordered auth algs */ uint8_t proph_num_encrypt; /* # of ordered encrypt algs */ uint8_t proph_algs[2]; /* proph_algs is bounded by num auth + num encrypt */ }; ******* [Dan McD.: As with the base header, this may become a list of transforms.] [C. Metz: An argument for the transform side of this is if I want to express: My preferences are: 1.) 3DES with HMAC-MD5 auth & replay 2.) 3DES with replay ... ] ******* McDonald, Metz, and Phan Expires in 6 months [Page 15] Internet Draft PF_KEY, Version 2 17 March 1997 Following the header are a list of one-octet algorithm identifiers, first authentication algorithms in preferential order, then encryption algorithms in preferential order. 2.3.7 SUPPORTED ALGORITHMS EXTENSION The Supported Algorithms extension contains a list of all algorithms supported by the kernel. This is useful for key management, as it knows what it can negotiate. Its format is: struct alg_hdr { uint16_t algh_hdrtype; /* 7 */ uint16_t algh_len; uint8_t algh_num_auth; /* # of auth algs supported */ uint8_t algh_num_encrypt; /* # of encrypt algs */ uint16_t algh_reserved; /* Followed by one or more alg_desc */ }; It is followed by one or more algorithm descriptors. An algorithm descriptor looks like: struct alg_desc { uint8_t algd_type; /* Algorithm type. */ uint8_t algd_flags; /* Algorithm properties (IV, etc.) */ uint8_t algd_ivlen; /* Algorithm IV len, if needed */ uint8_t algd_numkeys; /* Number of keys needed */ uint16_t algd_minlen; /* Minimum key length */ uint16_t algd_maxlen; /* Maximum key length */ }; 32-bit alignment is guaranteed by the fields automatically. The flags indicate properties such as an initialization vector. The minlen and maxlen are key lengths in bits. 2.3.8 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 spir_type; /* 8 */ uint16_t spir_len; uint32_t spi_low; uint32_t spi_hi; } McDonald, Metz, and Phan Expires in 6 months [Page 16] Internet Draft PF_KEY, Version 2 17 March 1997 2.4 ILLUSTRATION OF MESSAGE LAYOUT The following shows how the octets are layed out in a PF_KEY message. Optional fields are indicated as such. The base header is as follows: 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 +---------------+---------------+---------------+---------------+ | sadb_version | sadb_msg_type | sadb_msg_errno| sadb_sa_type | +---------------+---------------+---------------+---------------+ | sadb_msg_len | sadb_sa_assocopts | +---------------+---------------+---------------+---------------+ | sadb_msg_seq | +---------------+---------------+---------------+---------------+ | sadb_msg_pid (NOTE: Assuming pid_t is 32 bits) | +---------------+---------------+---------------+---------------+ | sadb_sa_spi | +---------------+---------------+---------------+---------------+ | ...replay... | sadb_sa_state |sadb_sa_encrypt| sadb_sa_auth | +---------------+---------------+---------------+---------------+ The base header may be followed by one or more of the following extension fields, depending on the values of various base header fields. The following fields are ordered such that if they appear, they SHOULD appear in the order presented below. An extension field MUST not be repeated. If there is a situation where an extension MUST be repeated, it should be brought to the attention of the authors. McDonald, Metz, and Phan Expires in 6 months [Page 17] Internet Draft PF_KEY, Version 2 17 March 1997 The Lifetime 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 +---------------+---------------+---------------+---------------+ | life_hdrtype (1) | life_len | +---------------+---------------+---------------+---------------+ | life_type | life_size | life_reserved | +---------------+---------------+---------------+---------------+ > lifetime_value, if 32-bit or 64-bit quantity < +---------------+---------------+---------------+---------------+ The Address extension +---------------+---------------+---------------+---------------+ | addr_hdrtype (2) | addr_len | +---------------+---------------+---------------+---------------+ | addr_which | addr_reserved | +---------------+---------------+---------------+---------------+ > 32-bit aligned struct sockaddr(s) < +---------------+---------------+---------------+---------------+ The Key extension +---------------+---------------+---------------+---------------+ | kbh_hdrtype (3) | kbh_len | +---------------+---------------+---------------+---------------+ | kbh_num_auth |kbh_num_encrypt| kbh_reserved | +---------------+---------------+---------------+---------------+ > One or more actual keys, encoded as follows... < +---------------+---------------+---------------+---------------+ An actual key +---------------+---------------+---------------+---------------+ | kh_type | kh_flags | kh_length | +---------------+---------------+---------------+---------------+ > A key, padded to 32-bits, most sigificant bits to least. < +---------------+---------------+---------------+---------------+ The Identity extension +---------------+---------------+---------------+---------------+ | idh_hdrtype (4) | idh_len | +---------------+---------------+---------------+---------------+ | idh_which | +---------------+---------------+---------------+---------------+ > One or more certificate identities of the following forms < +---------------+---------------+---------------+---------------+ McDonald, Metz, and Phan Expires in 6 months [Page 18] Internet Draft PF_KEY, Version 2 17 March 1997 IPv6 address or IPv4 address should look in the previous Address extension for actual values. +---------------+---------------+---------------+---------------+ | certid_type | certid_reserved | +---------------+---------------+---------------+---------------+ NOTE that certid_reserved gets filled with useful fields for some identity types. An IPv6 or IPv4 address range +---------------+---------------+---------------+---------------+ | certid_type |pref_len (bits)| certid_reserved | +---------------+---------------+---------------+---------------+ > 16-bytes of IPv6 or 4-bytes of IPv4 address prefix < +---------------+---------------+---------------+---------------+ A Fully-qualified domain name, or a mailbox ID. +---------------+---------------+---------------+---------------+ | certid_type | A null-terminated C-string | +---------------+---------------+---------------+---------------+ > which MUST be padded out for 32-bit alignment < +---------------+---------------+---------------+---------------+ A connection ID, which uses address plus port/protocol information. +---------------+---------------+---------------+---------------+ | certid_type | protocol_id | certid_reserved | +---------------+---------------+---------------+---------------+ | source_port | destination_port | +---------------+---------------+---------------+---------------+ The Sensitivity extension +---------------+---------------+---------------+---------------+ | sens_hdrtype (5) | sens_len | +---------------+---------------+---------------+---------------+ | sens_dpd | +---------------+---------------+---------------+---------------+ |sens_sens_level| ...bitmap_len |sens_integ_lev | ...bitmap_len | +---------------+---------------+---------------+---------------+ > The sensitivity bitmap, followed immediately by the integrity < < bitmap, padded to a 32-bit quantity. > +---------------+---------------+---------------+---------------+ The Proposal extension McDonald, Metz, and Phan Expires in 6 months [Page 19] Internet Draft PF_KEY, Version 2 17 March 1997 +---------------+---------------+---------------+---------------+ | proph_hdrtype (6) | proph_len | +---------------+---------------+---------------+---------------+ | proph_num_auth|proph_num_encr.| 1st auth alg | 2nd auth alg | +---------------+---------------+---------------+---------------+ > Nth auth alg... then 1st encrypt alg, etc. Padded for 32-bits< +---------------+---------------+---------------+---------------+ The Supported Algorithms extension +---------------+---------------+---------------+---------------+ | algh_hdrtype (7) | algh_len | +---------------+---------------+---------------+---------------+ | algh_num_auth |algh_num_encr. | algh_reserved | +---------------+---------------+---------------+---------------+ Followed by one or more Algorithm Descriptors +---------------+---------------+---------------+---------------+ | algd_type | algd_flags | algd_ivlen | algd_numkeys | +---------------+---------------+---------------+---------------+ | algd_minlen | algd_maxlen | +---------------+---------------+---------------+---------------+ The SPI Range extension +---------------+---------------+---------------+---------------+ | spir_hdrtype (8) | spir_len | +---------------+---------------+---------------+---------------+ | spir_hi | +---------------+---------------+---------------+---------------+ | spir_low | +---------------+---------------+---------------+---------------+ McDonald, Metz, and Phan Expires in 6 months [Page 20] Internet Draft PF_KEY, Version 2 17 March 1997 3. SYMBOLIC NAMES This section defines various symbols used with PF_KEY and the semantics associated with each symbol. Applications SHOULD use the symbolic name in order to be maximally portable. The numeric definitions shown are for illustrative purposes, unless explicitly stated otherwise. The numeric definition might vary on other systems. The symbolic name MUST be kept the same for all conforming implementations. ******* [Dan McD: Should I give a prefix, like SADB_X_*, so that implementation-specific hacks (i.e. policy) can fit in?] ******* 3.1 MESSAGE TYPES The following message types are used with PF_KEY. These are defined in the file . #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 by normal applications */ 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: McDonald, Metz, and Phan Expires in 6 months [Page 21] Internet Draft PF_KEY, Version 2 17 March 1997 In the case of an error, only the base header is returned. 3.1.1 SADB_GETSPI Message The SADB_GETSPI message allows a process to obtain a unique SPI value for given security association type, source address, and destination address. This message followed by a SADB_UPDATE is one way to create a security association (SADB_ADD is the other method). The process specifies the type in the base header, the source and destination address in address extension, and, if proxy key management is in use, the internal sockaddrs or the proxy sockaddr are also included in the address extension. If the SADB_GETSPI message is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq MUST be the same as the SADB_ACQUIRE message. The application may also specifiy the SPI. This is done by either setting the sadb_sa_spi field to a single SPI, or having the kernel select within a range of SPI values by using the SPI range extension. This use of the lifetime extension to specify SPI ranges is detailed later. 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. An 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. The kernel returns the SADB_GETSPI message to all listening processes. Errors: EINVAL Various message improprieties, including SPI ranges that are malformed. ENOBUFS No buffer space is available to process request. EEXIST Requested SPI or SPI range is not available/already used. McDonald, Metz, and Phan Expires in 6 months [Page 22] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.2 SADB_UPDATE Message The SADB_UPDATE message allows a process to update the information in an existing Security Association. Since SADB_GETSPI does not allow setting of certain parameters, this message is needed to fully form the larval security association created with SADB_GETSPI. The format of the update message is a base header, followed by the relevant extensions. If the keying material, lifetimes, compartment bitmaps, or certificate identities need to be updated, these extensions should be included. The kernel searches for the security association with the same type, spi, source address and destination address specified in the message and updates the Security Association information using the content of the SADB_UPDATE message. The kernel SHOULD perform sanity checking on various technical parameters passed in as part of the SADB_UPDATE message. One example is DES key parity bit checking. Other examples include key length checking, and checks for keys known to be weak for the specified algorithm. The kernel SHOULD NOT allow 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 message behavior of the SADB_UPDATE message is: Send a SADB_UPDATE message from a user process to the kernel. The kernel returns the SADB_UPDATE message to all listening processes. 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 Various message improprieties, including sanity check failures on keys. EACCES Insufficient privilege to update entry. Socket issuing McDonald, Metz, and Phan Expires in 6 months [Page 23] Internet Draft PF_KEY, Version 2 17 March 1997 the SADB_UPDATE is not creator of the entry to be updated. McDonald, Metz, and Phan Expires in 6 months [Page 24] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.3 SADB_ADD Message 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 optimal for manual keying applications, and other strategies where the uniqueness of the SPI is known immediately. An SADB_ADD message is also used when negotiation is finished, and the second of a pair of associations is added. The SPI for this association was determined by the peer machine. It MAY be useful to set the sadb_msg_seq to that of a kernel-generated SADB_ACQUIRE so that both associations in a pair are bound to the same ACQUIRE request. The message behavior of the SADB_ADD message is: Send a SADB_ADD message from a user process to the kernel. The kernel returns the SADB_ADD message to all listening processes. 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 Various message improprieties, including sanity check failures on keys. McDonald, Metz, and Phan Expires in 6 months [Page 25] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.4 SADB_DELETE Message The SADB_DELETE message causes the kernel to delete a Security Association from the key table. The delete message consists of the base header followed by the source sockaddr and the destination sockaddr in the address extension. The kernel deletes the security association matching the type, spi, source address, and destination address in the message. There are two message behaviors for SADB_DELETE. The first is a user- originated deletion Send a SADB_DELETE message from a user process to the kernel. The kernel returns the SADB_DELETE message to all listening processes. The second behavior is in the case of a hard-limit lifetime expiration. The kernel sends a SADB_DELETE message to all listening processes when a security association times out. Errors: ESRCH The security association to be deleted was not found. McDonald, Metz, and Phan Expires in 6 months [Page 26] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.5 SADB_GET Message The SADB_GET message allows a process to retrieve a copy of a Security Association from the kernel's key table. The get message consists of the base header follows by the relevant extension fields. The Security Association matching the type, spi, source address, and destination address is returned. The K_USED flag is set inside the Key Engine for the returned Security Association. The message behavior of the SADB_GET message is: Send a SADB_GET message from a user process to the kernel. The kernel returns the SADB_GET message to the socket that sent the SADB_GET message. Errors: ESRCH The sought security association was not found. McDonald, Metz, and Phan Expires in 6 months [Page 27] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.6 SADB_ACQUIRE Message The SADB_ACQUIRE message is typically sent only by the kernel to key socket listeners who have registered their key socket (see SADB_REGISTER message). SADB_ACQUIRE messages can be sent by application-level consumers of security associations (such as an OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE message is a base header along with an address extension, possibly a certificate identity extension, and if more than one algorithm and options is acceptable, a proposal extension. The proposed situation contains a list of desirable algorithms that can be used if the algorithms in the base header are not available. The values for the fields in the base header and in the security association data which follows the base header indicate the properties of the Security Association that the listening process should attempt to acquire. If the message originates from the kernel (i.e. the sadb_msg_pid is 0), the sadb_seq number MUST be used by a subsequent SADB_GETSPI message to bind a security association to the request. This avoids the race condition of two TCP connections between two IP hosts that each require unique associations, and having one steal another's security association. The sadb_errno and sadb_state fields should be ignored by the listening process. The SADB_ACQUIRE message is typically triggered by an outbound packet that needs security but for which there is no applicable Security Association existing in the key table. If the packet can be sufficiently protected by more than one algorithm or combination of options, the SADB_ACQUIRE message MUST order the preference of possibilities by placing the most preferred algorithm in the base header, and the subsequent ones in the proposed_situation field in order of preference. There are two messaging behaviors for SADB_ACQUIRE. The first is where the kernel needs a security association (e.g. for IPsec). The kernel sends a SADB_ACQUIRE message to registered sockets. The second is where an application-layer consumer of security associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security association. Send a SADB_ACQUIRE message from a user process to the kernel. The kernel returns a SADB_ACQUIRE message to registered sockets. McDonald, Metz, and Phan Expires in 6 months [Page 28] Internet Draft PF_KEY, Version 2 17 March 1997 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 the requested SA cannot be acquired. McDonald, Metz, and Phan Expires in 6 months [Page 29] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.7 SADB_REGISTER Message The SADB_REGISTER message allows an application to register its key socket as able to acquire new security associations for the kernel. SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for the type of security association specified in sadb_sa_type. The application specifies the type of security association that it can acquire for the kernel in the type field of its register message. If an application can acquire multiple types of security association, it MUST register each type in a separate message. Only the base header is needed for the register message. For portability reasons, key management applications MAY register for a type not known to the kernel. The reply of the SADB_REGISTER message contains a supported algorithm extension. That field contains an array of supported algorithm, one per octet. This allows key management applications to know what algorithm are supported by the kernel. In an enviroment where algorithms can be dynamically loaded and unloaded, an asyncryonous SADB_REGISTER reply MAY be generated. The list of supported algorithms MUST be a complete list, so the application can make note of omissions or additions. The messaging behavior of the SADB_REGISTER message is: Send a SADB_REGISTER message from a user process to the kernel. The kernel returns a SADB_REGISTER message, 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. McDonald, Metz, and Phan Expires in 6 months [Page 30] Internet Draft PF_KEY, Version 2 17 March 1997 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 of a Security Association has expired for a security protocol implemented inside the kernel, then the kernel MUST issue an SADB_EXPIRE message to all key socket listeners. A user application is responsible for tracking SA expirations for security protocols (e.g. OSPF Authentication) that are implemented inside that user application. If the soft limit of a Security Association has expired, the user application SHOULD issue a SADB_EXPIRE message. Regardless of where the security protocol is implemented, if both the soft limit and the hard limit expire at the same time, both SADB_DELETE and SADB_EXPIRE messages MUST be sent. 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 messaging behavior of the SADB_EXPIRE message is: The kernel sends a SADB_EXPIRE message when the soft limit of a security association has been expired. ERRORS: EINVAL Message Invalid for some reason. EPROTONOSUPPORT ??? McDonald, Metz, and Phan Expires in 6 months [Page 31] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.9 SADB_FLUSH Message The SADB_FLUSH message causes the kernel to delete all entries in its key table for a certain sadb_sa_type. Only the base header is required for a flush message. If sadb_sa_type is filled in with a specific value, only associations of that type are deleted. If it is filled in with SEC_TYPE_NONE, ALL associations are deleted. The messaging behavior for SADB_FLUSH is: Send a SADB_FLUSH message from a user process to the kernel. The kernel will return a SADB_FLUSH message to all listening sockets. The reply message happens only after the actual flushing of security associations has been attempted. McDonald, Metz, and Phan Expires in 6 months [Page 32] Internet Draft PF_KEY, Version 2 17 March 1997 3.1.10 SADB_DUMP Message The SADB_DUMP message causes the kernel to dump the operating system's entire Key Table to the requesting key socket. As in SADB_FLUSH, if a sadb_sa_type value is in the message, only associations of that type will be dumped. If SEC_TYPE_NONE is specified, all associations will be used. Each Security Association is returned in its own SADB_DUMP message. A SADB_DUMP message with a sadb_seq field of zero indicates the end of the dump transaction. Unlike other key messages, the dump message is returned only to the key socket originating the dump request because of the potentially large amount of data it can generate. The dump message is used for debugging purposes only and is not intended for production use. Support for the dump message MAY be discontinued in future versions of the key socket, hence key management applications MUST NOT depend on this message for basic operation. The messaging behavior for SADB_DUMP is: Send a SADB_DUMP message from a user process to the kernel. Several SADB_DUMP messages will return from the kernel to the sending socket. McDonald, Metz, and Phan Expires in 6 months [Page 33] Internet Draft PF_KEY, Version 2 17 March 1997 3.2 SECURITY ASSOCIATION STATE The Security Association's state is a bitmask field. The related symbolic definitions below should be used in order that applications will be maximally portable: #define SA_USED 0x01 /* SA used/not used */ #define SA_UNIQUE 0x02 /* SA unique/reusable */ #define SA_LARVAL 0x04 /* SPI assigned, but SA incomplete */ #define SA_ZOMBIE 0x08 /* SA expired but still useable */ #define SA_DEAD 0x10 /* SA marked for deletion */ #define SA_INBOUND 0x20 /* SA for packets destined here */ #define SA_OUTBOUND 0x40 /* SA for packets sourced here */ #define SA_FORWARD 0x80 /* SA for packets forwarded thru */ SA_USED is set by the operating system if the Security Association has been used. Otherwise this flag is not set. If SADB_GET is used to read an SA from the Key Engine, the Key Engine will set SA_USED on the SA that was read via SADB_GET. SA_UNIQUE is set by the operating system if the Security Association has been allocated uniquely to a single user (e.g. a particular network socket). If this is not set, then the Security Association is considered sharable. SA_LARVAL indicates that the operating system has assigned this SPI value but that there is no complete Security Association yet stored in the kernel. SA_ZOMBIE indicates a Security Association that has expired but is still useable until a replacement Security Association is added. This is primarily used with OSPFv2 and RIPv2 cryptographic authentication. SA_DEAD indicates a Security Association that exists but is marked for deletion. SA_INBOUND is set for an inbound Security Association and SA_OUTBOUND is set for an outbound Security Association. SA_FORWARD is used for a Security Association used only for packets originating elsewhere and destined elsewhere that have security processing on this node. All Security Associations used with PF_KEY are unidirectional. ******* [Dan McD.: Why SA_FORWARD? Isn't SA_OUTBOUND sufficient? I may implement forwarding such that it's hard or impossible for the key engine/SADB to tell the difference. ] McDonald, Metz, and Phan Expires in 6 months [Page 34] Internet Draft PF_KEY, Version 2 17 March 1997 ******* McDonald, Metz, and Phan Expires in 6 months [Page 35] Internet Draft PF_KEY, Version 2 17 March 1997 3.3 SECURITY ASSOCIATION TYPE This defines the type of Security Association in this message. The numeric definitions are those used in the prototype NRL implementation, but might be different on other implementations. 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 . #define SEC_TYPE_NONE 0 #define SEC_TYPE_AH 1 /* RFC-1826 */ #define SEC_TYPE_ESP 2 /* RFC-1827 */ #define SEC_TYPE_RSVP 3 /* RSVP Authentication */ #define SEC_TYPE_OSPFV2 4 /* OSPFv2 Authentication */ #define SEC_TYPE_RIPV2 5 /* RIPv2 Authentication */ #define SEC_TYPE_MIPV4 6 /* Mobile IPv4 Authentication */ #define SEC_TYPE_MAX 6 SEC_TYPE_NONE is defined for completeness and means no Security Association. This type is never used with PF_KEY. SEC_TYPE_AH is for the IP Authentication Header defined in [Atk95b]. SEC_TYPE_ESP is for the IP Encapsulating Security Payload defined in [Atk95c]. SEC_TYPE_RSVP is for the RSVP Integrity Object. SEC_TYPE_OSPFv2 is for OSPFv2 Cryptographic authentication, while SEC_TYPE_RIPv2 is for RIPv2 Cryptographic authentication. SEC_TYPE_MAX is never used with PF_KEY but is defined for completeness. It is always set to the highest valid numeric value. There MUST not be gaps in the numbering of security types; all numbers must be used sequentially. McDonald, Metz, and Phan Expires in 6 months [Page 36] Internet Draft PF_KEY, Version 2 17 March 1997 3.4 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 editor. The symbols below are defined in . /* Authentication algorithms */ #define SADB_AALG_NONE 0 #define SADB_AALG_MD5_HMAC 1 #define SADB_AALG_SHA1_HMAC 2 /* Encryption algorithms */ #define SADB_EALG_NONE 0 #define SADB_EALG_DES_CBC 1 #define SADB_EALG_3DES 2 ******* [Dan McD.: This whole section is in anticipation of IPsec departing from a pure "transform" model. This also allows security schemes that do not have a transform model at all. ] ******* The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The algorithm for SADB_AALG_SHA1_HMAC is defined in [CG96]. The algorithm for SADB_EALG_DES_CBC is defined in [Hug96]. 3.5 ASSOCIATION OPTIONS Security association types can have various options defined. Options are denoted by a bit setting in the "Type Options" field of the base header. The bitmasks for defined options MUST NOT vary between implementations. Bits not defined are RESERVED and MUST NOT be used. #define SA_OPTION_PFS 0x0001 /* Use Perfect Forward Secrecy */ #define SA_OPTION_REPLAY 0x0002 /* Replay Protection enabled */ McDonald, Metz, and Phan Expires in 6 months [Page 37] Internet Draft PF_KEY, Version 2 17 March 1997 The SEC_OPTION_PFS flag indicates to key management that this association should have perfect forward secrecy in its key. (In other words, the session key cannot be determined by cryptanalysis of previous keying material.) The SEC_OPTION_REPLAY specifies that replay protection should be enabled on this association. The sadb_sa_replay_window_len field will indicate the size of the replay field. 3.6 EXTENSION HEADER VALUES To briefly recap the extension header values: #define SA_EXT_RESERVED 0 /* Reserved */ #define SA_EXT_LIFETIME 1 #define SA_EXT_ADDRESS 2 #define SA_EXT_KEY 3 #define SA_EXT_IDENTITY 4 #define SA_EXT_SENSITIVITY 5 #define SA_EXT_PROPOSAL 6 #define SA_EXT_SUPPORTED 7 #define SA_EXT_SPI_RANGE 8 3.7 LIFETIME EXTENSION VALUES The life_type field can contain the following values: #define SA_LIFETYPE_TIME 0 #define SA_LIFETYPE_BYTES 1 #define SA_LIFETYPE_PACKETS 2 Each value specifies a type of association lifetime. 3.8 ADDRESS EXTENSION VALUES The addr_which field is a bitmask which can indicate what sockaddrs follow, and what they represent. These bit values are: #define SADB_ADDR_SRC 0x1 #define SADB_ADDR_DST 0x2 #define SADB_ADDR_INNER_SRC 0x4 #define SADB_ADDR_INNNER_DST 0x8 #define SADB_ADDR_PROXY 0x10 3.9 KEY EXTENSION VALUES These are already mentioned in the ALGORITHM TYPES section. McDonald, Metz, and Phan Expires in 6 months [Page 38] Internet Draft PF_KEY, Version 2 17 March 1997 3.10 IDENTITY EXTENSION VALUES The idh_which field is a bitmask which indicates what identities follow. #define SADB_ID_SRC 0x1 #define SADB_ID_DST 0x2 Each identity can have a certain type. #define SADB_IDT_IPV4_ADDR 1 #define SADB_IDT_IPV6_ADDR 2 #define SADB_IDT_IPV4_RANGE 3 #define SADB_IDT_IPV6_RANGE 4 #define SADB_IDT_FQDN 5 #define SADB_IDT_USER_FQDN 6 #define SADB_IDT_IPV4_CONNID 7 #define SADB_IDT_IPV6_CONNID 8 3.11 SENSITIVITY EXTENSION VALUES The only field currently defined in the sensitivity extension is the sens_dpd, which represents the data protection domain. The other data in the senstivity extension is based off the sens_dpd value. If the highest order bit of the DP/DOI is set to 1, then the DP/DOI is not necessarily globally unique and is from a number space set aside for private use among consenting users. If the highest order bit of the DP/DOI is set to zero, the DP/DOI is globally unique from a number space administered by the Internet Assigned Numbers Authority. In order to conserve the limited amount of globally unique DP/DOI number space, IANA will not normally permit any one organization to obtain very many DP/DOI values. The all zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is in use". #define SADB_DPD_NONE 0 #define SADB_DPD_DOD_GENSER 1 #define SADB_DPD_DOD_SCI 2 #define SADB_DPD_DOE 3 #define SADB_DPD_NATO 4 3.12 PROPOSAL EXTENSION VALUES These are already mentioned in the ALGORITHM TYPES section. McDonald, Metz, and Phan Expires in 6 months [Page 39] Internet Draft PF_KEY, Version 2 17 March 1997 3.12 PROPOSAL EXTENSION VALUES Values for algd_type are mentioned in the ALGORITHM TYPES section. Values for the bit vector algd_flags are as follows: #define SADB_ALGDF_NEED_IV 0x1 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. ******* [ALL: What else belongs here ? ] ******* McDonald, Metz, and Phan Expires in 6 months [Page 40] Internet Draft PF_KEY, Version 2 17 March 1997 5. SECURITY CONSIDERATIONS This draft discusses a method for creating, reading, and deleting Security Associations from an operating system. Only trusted, privileged users and processes should be able to perform any of these 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 41] Internet Draft PF_KEY, Version 2 17 March 1997 ACKNOWLEDGEMENTS The editors of this document are listed primarily in Alphabetical order. A side effect of this particular alphabetical listing is to also show the history (starting with the most recent) of text contribution to this document. Ran Atkinson also contributed much advice and wisdom toward this document. Finally, the editors would like to thank the PF_KEY reviewers list. 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. [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with Replay Prevention", Internet Draft, May 1996. [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode Workstation Specification", Technical Report DDS-2600-6243-87. [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay Prevention Security Transform", Internet Draft, April 1996. [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with Replay Prevention", Internet Draft, May 1996. [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for Berkeley UNIX", Proceedings of the Winter 1991 USENIX Conference, Dallas, TX, USENIX Association. 1991. pp. 93-103. DISCLAIMER The views and specification here are those of the editors and are not necessarily those of their employers. The employers have not passed judgement on the merits, if any, of this work. The editors and their employers specifically disclaim responsibility for any problems arising from correct or incorrect implementation or use of this specification. McDonald, Metz, and Phan Expires in 6 months [Page 42] Internet Draft PF_KEY, Version 2 17 March 1997 EDITOR INFORMATION Daniel L. McDonald Sun Microsystems, Inc. 2550 Garcia Avenue, MS UMPK17-202 Mountain View, CA 94043-1100 E-mail: danmcd@eng.sun.com Craig W. Metz The Inner Net Code 1123, Box 10314 Blacksburg, VA 24062-0314 E-mail: cmetz@inner.net Bao G. Phan U. S. Naval Research Laboratory Code 5544 4555 Overlook Ave. SW Washington, DC 20375 E-mail: phan@itd.nrl.navy.mil APPENDIX A: CHANGE LOG The following changes were made between 00 and 01: * Added this change log. * Simplified TLV header syntax. * Splitting of algorithms. This may be controversial, but it allows PF_KEY to be used for more than just IPsec. It also allows policy to be placed in the KMd easier. * Added solid definitions and formats for certificate identities, multiple keys, etc. * Specified how keys are to be layed out (most-to-least bits). * Changed sequence number semantics to be like an RPC transaction ID number. McDonald, Metz, and Phan Expires in 6 months [Page 43]