RFC 2367
PF_KEY Key Management API, Version 2
Network Working Group D. McDonald Request for Comments: 2367 C. Metz Category: Informational B. Phan July 1998 PF_KEY Key Management API, Version 2 Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. 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). Table of Contents 1 Introduction ............................................. 3 1.1 Terminology .............................................. 3 1.2 Conceptual Model ......................................... 4 1.3 PF_KEY Socket Definition ................................. 8 1.4 Overview of PF_KEY Messaging Behavior .................... 8 1.5 Common PF_KEY Operations ................................. 9 1.6 Differences Between PF_KEY and PF_ROUTE .................. 10 1.7 Name Space ............................................... 11 1.8 On Manual Keying ..........................................11 2 PF_KEY Message Format .................................... 11 2.1 Base Message Header Format ............................... 12 2.2 Alignment of Headers and Extension Headers ............... 14 2.3 Additional Message Fields ................................ 14 2.3.1 Association Extension .................................... 15 2.3.2 Lifetime Extension ....................................... 16
2.3.3 Address Extension ........................................ 18 2.3.4 Key Extension ............................................ 19 2.3.5 Identity Extension ....................................... 21 2.3.6 Sensitivity Extension .................................... 21 2.3.7 Proposal Extension ....................................... 22 2.3.8 Supported Algorithms Extension ........................... 25 2.3.9 SPI Range Extension ...................................... 26 2.4 Illustration of Message Layout ........................... 27 3 Symbolic Names ........................................... 30 3.1 Message Types ............................................ 31 3.1.1 SADB_GETSPI .............................................. 32 3.1.2 SADB_UPDATE .............................................. 33 3.1.3 SADB_ADD ................................................. 34 3.1.4 SADB_DELETE .............................................. 35 3.1.5 SADB_GET ................................................. 36 3.1.6 SADB_ACQUIRE ............................................. 36 3.1.7 SADB_REGISTER ............................................ 38 3.1.8 SADB_EXPIRE .............................................. 39 3.1.9 SADB_FLUSH ............................................... 40 3.1.10 SADB_DUMP ................................................ 40 3.2 Security Association Flags ............................... 41 3.3 Security Association States .............................. 41 3.4 Security Association Types ............................... 41 3.5 Algorithm Types .......................................... 42 3.6 Extension Header Values .................................. 43 3.7 Identity Extension Values ................................ 44 3.8 Sensitivity Extension Values ............................. 45 3.9 Proposal Extension Values ................................ 45 4 Future Directions ........................................ 45 5 Examples ................................................. 45 5.1 Simple IP Security Example ............................... 46 5.2 Proxy IP Security Example ................................ 47 5.3 OSPF Security Example .................................... 50 5.4 Miscellaneous ............................................ 50 6 Security Considerations .................................. 51 Acknowledgments ............,............................. 52 References ............................................... 52 Disclaimer ............................................... 54 Authors' Addresses ....................................... 54 A. Promiscuous Send/Receive Extension ....................... 55 B. Passive Change Message Extension ......................... 57 C. Key Management Private Data Extension .................... 58 D. Sample Header File ....................................... 59 E. Change Log ............................................... 64 F. Full Copyright Statement ................................. 68
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 Security Association Database (SADB)). The Key Engine and its structures incorporate the required security attributes for a session and are instances of the "Security Association" (SA) 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 five 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 believe that it is 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. Some of these words, including MUST, MAY, and SHOULD, are detailed in [Bra97]. - 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]. Two 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 separate 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 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 in 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. Key management daemons use PF_KEY to communicate with the Key Engine and use PF_INET (or PF_INET6 in the case of IPv6) 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
+------------+ +-----------------+
| 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
before, the key management daemon stores the SA into the Key Engine.
Then, the trusted privileged application uses an 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. A PF_KEY implementation specified by the memo does NOT
have to support configuring systemwide policy using PF_KEY.
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 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 <sys/types.h> #include <sys/socket.h> #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 because of the expected frequency at which they will occur. Also, an implementation may further wish to restrict return messages 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 a Security Parameters Index (SPI) value from the kernel using the SADB_GETSPI message and then send an 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 an 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 similar to a transaction ID in a
remote procedure call. The SADB_EXPIRE message is sent from the kernel to key management applications when the "soft lifetime" or "hard lifetime" of a Security Association has expired. Key management applications should use receipt of a soft lifetime SADB_EXPIRE message as a hint to negotiate a replacement SA so the replacement SA will be ready and in the kernel before it is needed. A SADB_DUMP message is also defined, but this is primarily intended for PF_KEY implementor debugging and is not used in ordinary operation of PF_KEY. 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 it SHOULD check for such errors, and handle them in an appropriate manner. * 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" (two exceptions if "AF_KEY" is also counted), which is defined as a result of including the header file <sys/socket.h>. All PF_KEYv2 preprocessor symbols start with the 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 199806L, where 1998 is the year and 06 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. 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. Unless otherwise specified (e.g. SPI values), fields MUST be in host-specific 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. sadb_msg_errno Should be set to zero by the sender. The responder stores the error code in this field if an error has occurred. This includes the case where the responder is in user space. (e.g. user-space negotiation fails, an errno can be returned.) sadb_msg_satype Indicates the type of security association(s). Valid Security Association types are declared in the file <net/pfkeyv2.h>. The current set of Security Association types is enumerated later in this document.
sadb_msg_len Contains the total length, in 64-bit words, of all
data in the PF_KEY message including the base header
length and additional data after the base header, if
any. This length includes any padding or extra space
that might exist. Unless otherwise stated, all other
length fields are also measured in 64-bit words.
On user to kernel messages, this field MUST be
verified against the length of the inbound message.
EMSGSIZE MUST be returned if the verification fails.
On kernel to user messages, a size mismatch is most
likely the result of the user not providing a large
enough buffer for the message. In these cases, the
user application SHOULD drop the message, but it MAY
try and extract what information it can out of the
message.
sadb_msg_reserved
Reserved value. It MUST be zeroed by the sender. All
fields labeled reserved later in the document have
the same semantics as this field.
sadb_msg_seq Contains the sequence number of this message. This
field, along with sadb_msg_pid, MUST be used to
uniquely identify requests to a process. The sender
is responsible for filling in this field. This
responsibility also includes matching the
sadb_msg_seq of a request (e.g. SADB_ACQUIRE).
This field is similar to a transaction ID in a
remote procedure call implementation.
sadb_msg_pid Identifies the process which originated this message,
or which process a message is bound for. For
example, if process id 2112 sends an SADB_UPDATE
message to the kernel, the process MUST set this
field to 2112 and the kernel will set this field
to 2112 in its reply to that SADB_UPDATE
message. This field, along with sadb_msg_seq, can
be used to uniquely identify requests to a
process.
It is currently assumed that a 32-bit quantity will
hold an operating system's process ID space.
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.
(page 14 continued on part 2)
