Network Working Group D. L. McDonald
Internet Draft C. W. Metz
draft-mcdonald-pf-key-v2-02.txt B. G. Phan
21 April 1997
PF_KEY Key Management API, Version 2
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 21 April 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. Theoretically, the messages defined in this document
could be used in a non-socket context (e.g. between two communicating
user-level processes), but this document will not discuss in detail
such possibilities.
Security policy is deliberately omitted from this interface.
PF_KEY is not a mechanism for tuning systemwide security policy, nor
is it intended to enforce any sort of key management policy. The
developers of PF_KEY believed that it was important to separate
security mechanisms (such as PF_KEY) from security policies. This
permits a single mechanism to more easily support multiple policies.
1.1 TERMINOLOGY
Even though this document is not intended to be a standard, the
words that are used to define the significance of particular features
of this proposal are usually capitalized. These words are:
- MUST
This word or the adjective "REQUIRED" means that the item is an
absolute requirement of the specification.
- 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 21 April 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 21 April 1997
+------------+ +-----------------+
| Key Engine | | TCP/IP, |
| or SADB |---| including IPsec |
+------------+ | |
+-----------------+
|
+-----------+
| Network |
| Interface |
+-----------+
Figure 1: Relationship of Key Mgmt to PF_KEY
For performance reasons, some security protocols (e.g. IP Security)
are usually implemented inside the operating system kernel. Other
security protocols (e.g. OSPFv2 Cryptographic Authentication) are
implemented in trusted privileged applications outside the kernel.
Figure 2 shows a trusted, privileged routing daemon using PF_INET to
communicate routing information with a remote routing daemon and
using PF_KEY to request, obtain, and delete Security Associations
used with a routing protocol.
+---------------+
|Routing Daemon|
+---------------+
| |
| |
| | Applications
======[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 21 April 1997
before, the key management daemon stores the SA into the Key Engine.
Then, the trusted privileged application uses a SADB_GET message to
obtain the SA from the Key Engine.
In some implementations, policy may be implemented in user-space,
even though the actually cryptographic processing takes place in the
kernel. Such policy communication between the kernel mechanisms and
the user-space policy MAY be implemented by PF_KEY extensions, or
other such mechanism. This document will not specify such
extensions.
Untrusted clients, for example a user's web browser or telnet
client, do not need to use PF_KEY. Mechanisms not specified here are
used by such untrusted client applications to request security
services (e.g. IPsec) from an operating system. For security
reasons, only trusted, privileged applications are permitted to open
a PF_KEY socket.
1.3 PF_KEY SOCKET DEFINITION
The PF_KEY protocol family (PF_KEY) symbol is defined in
<sys/socket.h> in the same manner that other protocol families are
defined. PF_KEY does not use any socket addresses. Applications
using PF_KEY MUST NOT depend on the availability of a symbol named
AF_KEY, but kernel implementations are encouraged to define that
symbol for completeness.
The key socket is created as follows:
#include <net/pfkeyv2.h>
int s;
s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2)
The PF_KEY domain currently supports only the SOCK_RAW socket type.
The protocol field MUST be set to PF_KEY_V2. Only a trusted,
privileged process can create a PF_KEY socket. On conventional UNIX
systems, a privileged process is a process with an effective userid
of zero. On non-MLS proprietary operating systems, the notion of a
"privileged process" is implementation-defined. On Compartmented
Mode Workstations (CMWs) or other systems that claim to provide
Multi-Level Security (MLS), a process MUST have the "key management
privilege" in order to open a PF_KEY socket[DIA]. MLS systems that
don't currently have such a specific privilege MUST add that special
privilege and enforce it with PF_KEY in order to comply and conform
with this specification. Some systems, most notably some popular
personal computers, do not have the concept of a privileged user.
These systems SHOULD take steps to restrict the programs allowed to
McDonald, Metz, and Phan Expires in 6 months [Page 5]
Internet Draft PF_KEY, Version 2 21 April 1997
access the PF_KEY API.
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.
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.
The second approach to add a new Security Association into the
kernel is for the application to first request an SPI value from the
kernel using the SADB_GETSPI message and then send a SADB_UPDATE
message with the complete Security Association data. This second
approach works well with key management daemons when the SPI values
need to be known before the entire Security Association data is known
(e.g. so the SPI value can be indicated to the remote end of the key
management session).
McDonald, Metz, and Phan Expires in 6 months [Page 6]
Internet Draft PF_KEY, Version 2 21 April 1997
An individual Security Association can be deleted using the
SADB_DELETE message. Categories of SAs or the entire kernel SA table
can be deleted using the SADB_FLUSH message.
The SADB_GET message is used by a trusted application-layer process
(e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF
SA) from the kernel's Key Engine.
The kernel or an application-layer can use the SADB_ACQUIRE message
to request that a Security Association be created by some
application-layer key management process that has registered with the
kernel via a SADB_REGISTER message. This ACQUIRE message will have a
sequence number associated with it. This sequence number MUST be
used by followup SADB_GETSPI and SADB_UPDATE messages, in order to
keep track of which request gets its keying material. The sequence
number (described below) is analogous to a transaction ID in a remote
procedure call.
The SADB_EXPIRE message is sent from the kernel to key management
applications when the "soft lifetime" or "hard lifetime" of a
Security Association has expired. Key management applications should
use receipt of a soft lifetime SADB_EXPIRE message as a hint to
negotiate a replacement SA so the replacement SA will be ready and in
the kernel before it is needed.
A SADB_DUMP message is also defined, but this is primarily intended
for PF_KEY implementor debugging and is not used in ordinary
operation of PF_KEY.
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.
An implementation MAY use the write() error number to indicate an error,
but an application MUST not depend on this behavior.
* The entire message isn't always reflected in the reply. An SADB_ADD is
a good example of this.
* The PID is not set by the kernel. The process that originates the
message MUST set the sadb_msg_pid to its own PID. If the kernel
McDonald, Metz, and Phan Expires in 6 months [Page 7]
Internet Draft PF_KEY, Version 2 21 April 1997
originates a message, it MUST set the sadb_msg_pid to 0.
2. PF_KEY MESSAGE FORMAT
PF_KEY messages consist of a base header followed by additional
data fields, some of which may be optional. The format of the
additional data is dependent on the type of message.
PF_KEY messages currently do not mandate any specific ordering for
non-network multi-octet fields. Fields that may go across the wire
(e.g. SPI) MUST be in network byte order.
2.1 BASE MESSAGE HEADER FORMAT
PF_KEY messages consist of the base message header followed by
security association specific data whose types and lengths are
specified by a generic type-length encoding.
This base header is shown below, using POSIX types. The fields are
arranged primarily for alignment, and where possible, for reasons of
clarity.
struct sadb_msg {
uint8_t sadb_msg_version;
uint8_t sadb_msg_type;
uint8_t sadb_msg_errno;
uint8_t sadb_msg_sa_type;
uint16_t sadb_msg_len;
uint16_t sadb_msg_reserved;
uint32_t sadb_msg_seq;
uint32_t sadb_msg_pid;
};
sadb_version The version field of this PF_KEY message. This MUST be
set to PF_KEY_V2.
sadb_msg_type Identifies the type of message. The valid message types
are described later in this document.
sadb_msg_errno Should be set to zero by the sender. The replier stores
the error code in this field if an error has occured.
This includes the case where the replier is in user
space. (E.g. User-space negotiation fails, an errno can
be returned.)
sadb_msg_sa_type
McDonald, Metz, and Phan Expires in 6 months [Page 8]
Internet Draft PF_KEY, Version 2 21 April 1997
Indicates the type of security association(s) (e.g. AH,
ESP, OSPF, etc). Valid Security Association types are
declared in the file <net/pfkeyv2.h>. The current set of
Security Association types are enumerated later in this
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.
If this field mismatches the actual length of data,
EMSGSIZE MUST be returned.
sadb_msg_reserved
Reserved value. It MUST be zeroed by the sender, and it
MUST be ignored by the receiver. All fields labelled
reserved later in the document have the same semantics
as this field.
sadb_msg_seq Contains the sequence number of this message. This
field, along with sadb_msg_pid, MUST be used to uniquely
identify requests to a process. The sender is
responsible for filling in this field. This
resposibility also includes matching the sadb_msg_seq of
a request (e.g. SADB_ACQUIRE).
This field is analogous to a transaction ID in a remote
procedure call implementation.
sadb_msg_pid Identifies the process which originated this message, or
which process a message is bound for. For example: If
process id 2112 sends a SADB_UPDATE message to the
kernel, the message to the kernel MUST set its process
id to 2112, and the SADB_UPDATE reply from the kernel
will fill in this fields with 2112. This field, along
with sadb_msg_seq, can be used to uniquely identify
requests to a process.
It is currently believed that a 32-bit quantity will
hold an operating system's process ID space. If this
assumption is not true, then sadb_msg_pid will have to
be revisited.
McDonald, Metz, and Phan Expires in 6 months [Page 9]
Internet Draft PF_KEY, Version 2 21 April 1997
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_hdr {
uint16_t sadb_hdr_len; /* In 32-bit words, inclusive */
uint16_t sadb_hdr_hdrtype; /* 0 is reserved */
};
Types of extensions headers include: Association, Lifetime(s),
Address, Key, Identity, Sensitivity, Proposal, and Supported. There
MUST be only one instance of a extension type in a message. (e.g.
Base, Key, Lifetime, Key is forbidden), an EINVAL will be returned if
there are duplicate extensions within a message. Implementations MAY
enforce ordering of extensions in the order presented in the
EXTENSION HEADER VALUES section.
All extensions documented in this section MUST be implemented by a
PF_KEY implementation.
2.3.1 ASSOCIATION EXTENSION
The Association extension specifies data specific to a single
security association. The only times this extension is not present
is when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being
passed.
struct sadb_sa {
uint16_t sadb_sa_len;
uint16_t sadb_sa_hdrtype; /* ASSOCIATION */
uint32_t sadb_sa_spi;
uint8_t sadb_sa_replay_window_len;
uint8_t sadb_sa_state;
uint8_t sadb_sa_encrypt;
uint8_t sadb_sa_auth;
uint32_t sadb_sa_flags;
};
The sadb_sa_spi field contains the Security Parameters Index value
for the Security Association. Although this is a 32-bit field, some
types of Security Association might have an SPI or key identifier
that is less than 32-bits long. In this case, the smaller value shall
be stored in the least significant bits of this field and the
unneeded bits shall be zero. This field MUST be in network byte
order.
The sadb_sa_replay_window_len specifies the size of the replay
McDonald, Metz, and Phan Expires in 6 months [Page 10]
Internet Draft PF_KEY, Version 2 21 April 1997
window, if not zero. If zero, then no replay window is in use.
The sadb_sa_state field is an integer field containing the state of
the Security Association. This field should be set to zero by the
sending process and is set to the state of the Security Association
when the message is received. The current set of States are
enumerated later in this document.
The sadb_sa_encrypt and sadb_sa_auth fields identify the encryption
and authentication algorithm(s) used for this security association.
This can identify that no encryption or authentication is used for
this association. See section 3.4 for values that can be placed in
this field. The kernel MUST check sanity where relevant. For
example IPsec AH with no authentication algorithm is probably an
error.
The sadb_sa_flags field contains a bitmap of options defined for the
security assocation (e.g. replay protection, PFS, EXPIRED, etc.).
These flags are enumerated later in this document.
2.3.2 LIFETIME EXTENSION
The Lifetime extension specifies one or more lifetime variants for
this security association. If no Lifetime extension is present the
association has an infinite lifetime. An association SHOULD have a
lifetime of some sort associated with it. Lifetime variants come in
three varieties, HARD - indicating the hard-limit expiration, SOFT -
indicating the soft-limit expiration, and CURRENT - indicating the
current state of limits in a given security association. The
Lifetime extension looks like:
struct sadb_lifetime {
uint16_t sadb_lifetime_len;
uint16_t sadb_lifetime_hdrtype; /* LIFETIME */
uint8_t sadb_lifetime_which; /* Bitmask */
uint8_t sadb_lifetime_reserved[3]; /* Padding */
};
The sadb_lifetime_which field contains a bitmask indicating what
lifetimes; hard, soft, and current; follow. A lifetime value is
encoded as follows:
struct sadb_lifetime_val {
/* The following corresponds to sadb_lifetime_which */
uint8_t sadb_lifetime_val_which;
uint8_t sadb_lifetime_val_reserved;
uint16_t sadb_lifetime_val_allocations;
McDonald, Metz, and Phan Expires in 6 months [Page 11]
Internet Draft PF_KEY, Version 2 21 April 1997
uint32_t sadb_lifetime_val_bytes;
time_t sadb_lifetime_val_absolute;
time_t sadb_lifetime_val_updatetime;
time_t sadb_lifetime_val_usetime;
};
The sadb_lifetime_val_bytes field contains how many bytes this
security association can consume before it expires for HARD and
SOFT. In the case of CURRENT, it indicates how many bytes have been
consumed. The sadb_lifetime_val_allocations field contains how many
different connections, endpoints, or flows an association can be
allocated towards, or in the case of CURRENT, how many times the
association has been allocated. (The concept of a connection, flow,
or endpoint is somewhat system-specific.) There are three time
fields, one indicating absolute expiration time, one indicating time
after SA update, and another inidicating time after first use of
this SA. The update time and use time will indicate remaining time
in the case of CURRENT, and the assigned limits in the case of HARD
or SOFT.
The semantics of lifetimes are inclusive-OR, first-to-expire
semantics. This means if values for bytes and time, or multiple
times, are passed in, the first of these values to be reached will
cause a lifetime expiration.
2.3.3 ADDRESS EXTENSION
The Address extension specifies one or more addresses that are
associated with a security association. An Address extension MUST
be present when an Association address is present, and MUST specify
at least the source and destination addresses. (The source address
can be INADDR_ANY or it's IPv6 counterpart.) The format of an
Address extension is:
struct sadb_address {
uint16_t sadb_address_len;
uint16_t sadb_address_hdrtype; /* ADDRESS */
uint8_t sadb_address_which; /* Bitmask */
uint8_t sadb_address_reserved[3]; /* Padding */
/* Followed by one or more sockaddr structures. */
};
The sadb_address_which field contains a bitmask indicating what
addresses; source, destination, inner-source, inner-destination, and
proxy; follow. For each bit set in the sadb_address_which field, a
struct sockaddr follows, in the order specified above. The sockaddr
structure SHOULD conform to the sockaddr structure of the system
implementing PF_KEY. (E.g. If the system has an sa_len field, so
McDonald, Metz, and Phan Expires in 6 months [Page 12]
Internet Draft PF_KEY, Version 2 21 April 1997
SHOULD the sockaddrs in the message. If the system has NO sa_len
field, the sockaddrs SHOULD not have an sa_len field.) All non-
address information in the sockaddrs MUST be zeroed out.
2.3.4 KEY EXTENSION
The Key extension specifies one or more keys that are associated
with a security association. A Key extension will not always be
present with messages, because of security risks. The format of a
Key extension is:
struct sadb_keyblk {
uint16_t sadb_keyblk_len;
uint16_t sadb_keyblk_hdrtype; /* KEY */
uint8_t sadb_keyblk_which; /* Bitmask, which keys? */
uint8_t sadb_keyblk_reserved[3]; /* Padding */
/* Followed by sadb_key */
};
The Key extension is followed by the appropriate number of keys,
which contain information to correspond it to which keys are in the
keyblock. These keys are encoded as follows:
struct sadb_key {
uint16_t sadb_key_len; /* Length of key in bits */
uint8_t sadb_key_which; /* Corresponds to keyblk_which */
uint8_t sadb_key_type; /* 3DES, DES, HMAC-MD5, etc. */
/* Actual key follows */
};
The length of individual keys is in bits, and is interpreted by the
algorithm. Each key is padded to a 32-bit boundary. The key bits
are arranged most-sigificant to least significant. For example, a
22-bit key would take up three octets, with the least significant
two bits not containing key material. An additional octet would be
used for padding to a 32-bit boundary.
The sadb_key_which field indicates what sort of key this is, and is
one bit out of the list of bits in sadb_keyblk_which. These values
are detailed later.
2.3.5 IDENTITY EXTENSION
The Identity extension contains endpoint identities. If this
extension is not present, key management MUST assume that the
addresses in the Address extension are the only identities for this
Security Association. The Identity extension looks like:
McDonald, Metz, and Phan Expires in 6 months [Page 13]
Internet Draft PF_KEY, Version 2 21 April 1997
struct sadb_id {
uint16_t sadb_id_len;
uint16_t sadb_id_hdrtype; /* IDENTITY */
uint8_t sadb_id_which; /* bitmask */
uint8_t sadb_id_reserved[3]; /* Padding */
/* Followed by one or more sadb_certids */
};
The sadb_id_which field is a bitmask, indicating if source or
destination certificate identities are present. Each identity is a
32-bit aligned quantity, specified as:
struct sadb_certid {
uint16_t sadb_certid_len; /* In 32-bit words */
uint16_t sadb_certid_type;
/* Cert id. follows */
};
Following each sadb_certid is 32-bit aligned data. The type of data
can either be nothing (if the specified identity is the address), a
null-terminated C string (for fully-qualified domain names, or
mailbox identities), and address/mask pair (for address ranges), or
a port-pair/protocol tuple, used in concert with the addresses. See
the ILLUSTRATION OF MESSAGE LAYOUT section for details.
2.3.6 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.
struct sadb_sens {
uint16_t sadb_sens_len;
uint16_t sadb_sens_hdrtype; /* SENSITIVITY */
uint32_t sadb_sens_dpd;
uint8_t sadb_sens_sens_level;
uint8_t sadb_sens_sens_bitmap_len; /* 32-bit words */
uint8_t sadb_sens_integ_level;
uint8_t sadb_sens_integ_bitmap_len; /* 32-bit words */
/*
* followed by two uint32_t arrays
* uint32_t sadb_sens_bitmap[sens_bitmap_len];
* uint32_t integ_bitmap[integ_bitmap_len];
*/
};
McDonald, Metz, and Phan Expires in 6 months [Page 14]
Internet Draft PF_KEY, Version 2 21 April 1997
The lengths of the bitmaps are in bytes. Following this field are
the bitmaps. Only at the end of the second bitmap does padding to
32-bits occur. The sadb_sens_dpd describes the protection domain,
which allows interpretation of the levels and compartment bitmaps.
2.3.7 PROPOSAL EXTENSION
The Proposal extension contains a "proposed situation" of
algorithm preferences. It looks like:
struct sadb_prop {
uint16_t sadb_prop_len;
uint16_t sadb_prop_hdrtype; /* PROPOSAL */
uint8_t sadb_prop_num;
uint8_t sadb_prop_replay; /* Replay win. size. */
uint16_t sadb_prop_reserved;
};
Following the header are a list of combinations in preferential
order. A combination contains an <auth, encrypt> algorithm, pair,
and some other parameters. These combinations look like:
struct sadb_comb {
uint8_t sadb_comb_auth;
uint8_t sadb_comb_encr;
uint16_t sadb_comb_flags;
uint16_t sadb_comb_auth_keylen_min;
uint16_t sadb_comb_auth_keylen_max;
uint16_t sadb_comb_encr_keylen_min;
uint16_t sadb_comb_encr_keylen_max;
};
Each combination has an authentication and encryption algorithm,
which may be 0, indicating none. A combination's flags are the same
as the flags in the Association extension. The minimum and maximum
keylengths are derived from possible a priori policy decisions,
along with basic properties of the algorithm.
2.3.8 SUPPORTED ALGORITHMS EXTENSION
The Supported Algorithms extension contains a list of all
algorithms supported by the system. This is useful for key
management, as it now knows what algorithms it can negotiate. Its
format is:
struct sadb_alg {
uint16_t sadb_alg_len;
uint16_t sadb_alg_hdrtype; /* SUPPORTED */
McDonald, Metz, and Phan Expires in 6 months [Page 15]
Internet Draft PF_KEY, Version 2 21 April 1997
uint8_t sadb_alg_num_auth; /* # of auth algs */
uint8_t sadb_alg_num_encrypt; /* # of encrypt algs */
uint16_t sadb_alg_reserved;
/* Followed by one or more alg_desc */
};
It is followed by one or more algorithm descriptors. An algorithm
descriptor looks like:
struct sadb_algd {
uint8_t sadb_algd_type; /* Algorithm type. */
uint8_t sadb_algd_ivlen; /* IV len, in bits */
uint16_t sadb_algd_minlen; /* Min. key len (in bits) */
uint16_t sadb_algd_maxlen; /* Max. key length */
uint16_t sadb_algd_reserved;
};
32-bit alignment is guaranteed by the fields automatically. The
initialization vector length is 0 if not needed, and 0 if needed.
The minlen and maxlen are key lengths in bits.
2.3.9 SPI RANGE EXTENSION
One PF_KEY message, SADB_GETSPI, might need a range of acceptable
SPI values. This extension performs such a function.
struct sadb_spirange {
uint16_t sadb_spirange_len;
uint16_t sadb_spirange_hdrtype; /* SPI_RANGE */
uint32_t sadb_spirange_low;
uint32_t sadb_spirange_hi;
}
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_msg_reserved |
+---------------+---------------+---------------+---------------+
| sadb_msg_seq |
McDonald, Metz, and Phan Expires in 6 months [Page 16]
Internet Draft PF_KEY, Version 2 21 April 1997
+---------------+---------------+---------------+---------------+
| sadb_msg_pid |
+---------------+---------------+---------------+---------------+
The base header may be followed by one or more of the following
extension fields, depending on the values of various base header
fields. The following fields are ordered such that if they appear,
they SHOULD appear in the order presented below.
An extension field MUST not be repeated. If there is a situation
where an extension MUST be repeated, it should be brought to the
attention of the authors.
The Association extension
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+---------------+---------------+---------------+---------------+
| sadb_sa_len | sadb_sa_hdrtype |
+---------------+---------------+---------------+---------------+
| sadb_sa_spi |
+---------------+---------------+---------------+---------------+
| ...replay... | sadb_sa_state |sadb_sa_encrypt| sadb_sa_auth |
+---------------+---------------+---------------+---------------+
| sadb_sa_flags |
+---------------+---------------+---------------+---------------+
The Lifetime extension
+---------------+---------------+---------------+---------------+
| sadb_lifetime_len | sadb_lifetime_hdrtype |
+---------------+---------------+---------------+---------------+
| ..._which | sadb_lifetime_reserved |
+---------------+---------------+---------------+---------------+
A lifetime value
+---------------+---------------+---------------+---------------+
| ..._val_which | ..._reserved | sadb_lifetime_val_allocations |
+---------------+---------------+---------------+---------------+
| sadb_lifetime_val_bytes |
+---------------+---------------+---------------+---------------+
> sadb_lifetime_val_absolute <
+---------------+---------------+---------------+---------------+
> sadb_lifetime_val_updatetime <
+---------------+---------------+---------------+---------------+
> sadb_lifetime_val_usetime <
+---------------+---------------+---------------+---------------+
McDonald, Metz, and Phan Expires in 6 months [Page 17]
Internet Draft PF_KEY, Version 2 21 April 1997
The Address extension
+---------------+---------------+---------------+---------------+
| sadb_address_len | sadb_address_hdrtype |
+---------------+---------------+---------------+---------------+
|sadb_addr_which| sadb_addr_reserved |
+---------------+---------------+---------------+---------------+
> 32-bit aligned struct sockaddr(s) <
+---------------+---------------+---------------+---------------+
The Key extension
+---------------+---------------+---------------+---------------+
| sadb_keyblk_len | sadb_keyblk_hdrtype |
+---------------+---------------+---------------+---------------+
|...keyblk_which| sadb_keyblk_reserved |
+---------------+---------------+---------------+---------------+
> One or more actual keys, encoded as follows... <
+---------------+---------------+---------------+---------------+
An actual key
+---------------+---------------+---------------+---------------+
| sadb_key_len | sadb_key_which| sadb_key_type |
+---------------+---------------+---------------+---------------+
> A key, padded to 32-bits, most sigificant bits to least. <
+---------------+---------------+---------------+---------------+
The Identity extension
+---------------+---------------+---------------+---------------+
| sadb_id_len | sadb_id_hdrtype |
+---------------+---------------+---------------+---------------+
| sadb_id_which | sadb_id_reserved |
+---------------+---------------+---------------+---------------+
> One or more certificate identities of the following forms <
+---------------+---------------+---------------+---------------+
IPv6 address or IPv4 address should look in the previous Address
extension for actual values.
+---------------+---------------+---------------+---------------+
| sadb_certid_len | sadb_certid_type |
+---------------+---------------+---------------+---------------+
> Certificate data <
+---------------+---------------+---------------+---------------+
NOTE that the Certificate data gets filled with useful fields for
McDonald, Metz, and Phan Expires in 6 months [Page 18]
Internet Draft PF_KEY, Version 2 21 April 1997
most identity types.
An IPv6 or IPv4 address prefix
+---------------+---------------+---------------+---------------+
| sadb_certid_len | sadb_certid_type |
+---------------+---------------+---------------+---------------+
|pref_len (bits)| reserved |
+---------------+---------------+---------------+---------------+
> 16-bytes of IPv6 or 4-bytes of IPv4 address prefix <
+---------------+---------------+---------------+---------------+
A Fully-qualified domain name, or a mailbox ID.
+---------------+---------------+---------------+---------------+
| sadb_certid_len | sadb_certid_type |
+---------------+---------------+---------------+---------------+
> A null-terminated C-string which MUST be padded out for 32- >
< bit alignment <
+---------------+---------------+---------------+---------------+
A connection ID, which uses address plus port/protocol information.
+---------------+---------------+---------------+---------------+
| sadb_certid_len | sadb_certid_type |
+---------------+---------------+---------------+---------------+
| protocol_id | reserved |
+---------------+---------------+---------------+---------------+
| source_port | destination_port |
+---------------+---------------+---------------+---------------+
The Sensitivity extension
+---------------+---------------+---------------+---------------+
| sadb_sens_len | sadb_sens_hdrtype |
+---------------+---------------+---------------+---------------+
| sadb_sens_dpd |
+---------------+---------------+---------------+---------------+
| ...sens_level | ...bitmap_len |..._integ_level| ...bitmap_len |
+---------------+---------------+---------------+---------------+
> The sensitivity bitmap, followed immediately by the integrity <
< bitmap, each is an array of uint32_t. >
+---------------+---------------+---------------+---------------+
The Proposal extension
+---------------+---------------+---------------+---------------+
| sadb_prop_len | sadb_prop_hdrtype |
McDonald, Metz, and Phan Expires in 6 months [Page 19]
Internet Draft PF_KEY, Version 2 21 April 1997
+---------------+---------------+---------------+---------------+
| sadb_prop_num | ..prop_replay | sadb_prop_reserved |
+---------------+---------------+---------------+---------------+
> One or more combinations, specified as follows... <
+---------------+---------------+---------------+---------------+
Combination
+---------------+---------------+---------------+---------------+
|sadb_comb_auth |sadb_comb_encr | sadb_comb_flags |
+---------------+---------------+---------------+---------------+
| sadb_comb_auth_keylen_min | sadb_comb_auth_keylen_max |
+---------------+---------------+---------------+---------------+
| sadb_comb_encr_keylen_min | sadb_comb_encr_keylen_max |
+---------------+---------------+---------------+---------------+
The Supported Algorithms extension
+---------------+---------------+---------------+---------------+
| sadb_alg_len | sadb_alg_hdrtype |
+---------------+---------------+---------------+---------------+
| ...num_auth | ...num_encr. | sadb_alg_reserved |
+---------------+---------------+---------------+---------------+
Followed by one or more Algorithm Descriptors
+---------------+---------------+---------------+---------------+
|sadb_algd_type |sadb_algd_ivlen| sadb_algd_minlen |
+---------------+---------------+---------------+---------------+
| sadb_algd_maxlen | sadb_algd_reserved |
+---------------+---------------+---------------+---------------+
The SPI Range extension
+---------------+---------------+---------------+---------------+
| sadb_spirange_len | sadb_spirange_hdrtype |
+---------------+---------------+---------------+---------------+
| sadb_spirange_low |
+---------------+---------------+---------------+---------------+
| sadb_spirange_hi |
+---------------+---------------+---------------+---------------+
3. SYMBOLIC NAMES
This section defines various symbols used with PF_KEY and the
semantics associated with each symbol. Applications MUST use the
symbolic names in order to be portable. The numeric definitions
McDonald, Metz, and Phan Expires in 6 months [Page 20]
Internet Draft PF_KEY, Version 2 21 April 1997
shown are for illustrative purposes, unless explicitly stated
otherwise. The numeric definition MAY vary on other systems. The
symbolic name MUST be kept the same for all conforming
implementations.
If an implementation has implementation specific extensions the
SADB_X_ prefix MUST be used to name such extensions.
3.1 MESSAGE TYPES
The following message types are used with PF_KEY. These are
defined in the file <net/pfkeyv2.h>.
#define SADB_GETSPI 1
#define SADB_UPDATE 2
#define SADB_ADD 3
#define SADB_DELETE 4
#define SADB_GET 5
#define SADB_ACQUIRE 6
#define SADB_REGISTER 7
#define SADB_EXPIRE 8
#define SADB_FLUSH 9
#define SADB_DUMP 10 /* not used normally */
#define SADB_MAX 10
Each message has a behavior. A behavior is defined as where the
initial message travels (e.g. user to kernel), and what subsequent
actions are expected to take place. Contents of messages are
illustrated as:
<base, REQUIRED EXTENSION, REQ., (OPTIONAL EXT.,) (OPT) >
The Lifetime extension is represented with one to three letters after
it, to represent (H)ard, (S)oft, or (C)urrent.
In the case of an error, only the base header is returned.
3.1.1 SADB_GETSPI Message
The SADB_GETSPI message allows a process to obtain a unique SPI
value for given security association type, source address, and
destination address. This message followed by a SADB_UPDATE is one
way to create a security association (SADB_ADD is the other method).
The process specifies the type in the base header, the source and
destination address in address extension, and, if proxy key
McDonald, Metz, and Phan Expires in 6 months [Page 21]
Internet Draft PF_KEY, Version 2 21 April 1997
management is in use, the internal sockaddrs or the proxy sockaddr
are also included in the address extension. If the SADB_GETSPI
message is in response to a kernel-generated SADB_ACQUIRE, the
sadb_msg_seq MUST be the same as the SADB_ACQUIRE message. The
application may also specifiy the SPI. This is done by having the
kernel select within a range of SPI values by using the SPI range
extension. To specify a single SPI value to be verified, the
application sets the high and low values to be equal. Permitting
range specification is important because the kernel can allocate an
SPI value based on what it knows about SPI values already in use.
The kernel returns the same message with the allocated SPI value
stored in the spi field of an association extension. An SADB_UPDATE
message can later be used to add an entry with the requested SPI
value.
The message behavior of the SADB_GETSPI message is:
Send a SADB_GETSPI message from a user process to the kernel.
<base, address, SPI range>
The kernel returns the SADB_GETSPI message to all listening
processes.
<base, association, address>
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.
3.1.2 SADB_UPDATE Message
The SADB_UPDATE message allows a process to update the information
in an existing Security Association. Since SADB_GETSPI does not
allow setting of certain parameters, this message is needed to fully
form the larval security association created with SADB_GETSPI. The
format of the update message is a base header, followed by an
association header and any relevant extensions. If the keying
material, lifetimes, compartment bitmaps, or certificate identities
need to be updated, these extensions should be included. The kernel
searches for the security association with the same type, spi, source
address and destination address specified in the message and updates
the Security Association information using the content of the
SADB_UPDATE message.
McDonald, Metz, and Phan Expires in 6 months [Page 22]
Internet Draft PF_KEY, Version 2 21 April 1997
The kernel SHOULD perform sanity checking on various technical
parameters passed in as part of the SADB_UPDATE message. One example
is DES key parity bit checking. Other examples include key length
checking, and checks for keys known to be weak for the specified
algorithm.
The kernel MAY disallow SADB_UPDATE to succeed unless the message
is issued from the same socket that created the security association.
Such enforcement significantly reduces the chance of accidental
changes to an in-use security associations. Malicious trusted
parties could still issue a SADB_FLUSH or SADB_DELETE message, but
deletion of associations is more easily detected and less likely to
occur accidentally than an erroneous SADB_UPDATE.
The counter argument involves the case where a user-space key
management application fails, and is restarted. The new instance of
the application will not have the same socket as the creator of the
security association.
The message behavior of the SADB_UPDATE message is:
Send a SADB_UPDATE message from a user process to the kernel.
<base, association, (lifetime (HS),) address, key, (identity,)
(sensitivity)>
The kernel returns the SADB_UPDATE message to all listening
processes.
<base, association, (lifetime (HSC),) address, (identity,)
(sensitivity)>
The keying material is not returned on the message from the kernel
to listening sockets because listeners might not have the privileges
to see such keying material.
Errors:
ESRCH The security association to be updated was not found.
EINVAL Various message improprieties, including sanity check
failures on keys.
EACCES Insufficient privilege to update entry. Socket issuing
the SADB_UPDATE is not creator of the entry to be updated.
3.1.3 SADB_ADD Message
The SADB_ADD message is nearly identical to the SADB_UPDATE
McDonald, Metz, and Phan Expires in 6 months [Page 23]
Internet Draft PF_KEY, Version 2 21 April 1997
message, except that it does not require a previous call to
SADB_GETSPI. The SADB_ADD message is used in manual keying
applications, and in other cases where the uniqueness of the SPI is
known immediately.
An SADB_ADD message is also used when negotiation is finished, and
the second of a pair of associations is added. The SPI for this
association was determined by the peer machine. It MAY be useful to
set the sadb_msg_seq to that of a kernel-generated SADB_ACQUIRE so
that both associations in a pair are bound to the same ACQUIRE
request.
The message behavior of the SADB_ADD message is:
Send a SADB_ADD message from a user process to the kernel.
<base, association, (lifetime (HS),) address, key, (identity,)
(sensitivity)>
The kernel returns the SADB_ADD message to all listening
processes.
<base, association, (lifetime (HSC),) address, (identity,)
(sensitivity)>
The keying material is not returned on the message from the kernel to
listening sockets because listeners may not have the privileges to see
such keying material.
Errors:
EEXIST The security association that was to be added already
exists.
EINVAL Various message improprieties, including sanity check
failures on keys.
3.1.4 SADB_DELETE Message
The SADB_DELETE message causes the kernel to delete a Security
Association from the key table. The delete message consists of the
base header followed by the association, and the source and
destination sockaddrs in the address extension. The kernel deletes
the security association matching the type, spi, source address, and
destination address in the message.
The message behavior for SADB_DELETE is as follows:
Send a SADB_DELETE message from a user process to the kernel.
McDonald, Metz, and Phan Expires in 6 months [Page 24]
Internet Draft PF_KEY, Version 2 21 April 1997
<base, association, address>
The kernel returns the SADB_DELETE message to all listening
processes.
<base, association, address>
3.1.5 SADB_GET Message
The SADB_GET message allows a process to retrieve a copy of a
Security Association from the kernel's key table. The get message
consists of the base header follows by the relevant extension fields.
The Security Association matching the type, spi, source address, and
destination address is returned. The K_USED flag is set inside the
Key Engine for the returned Security Association.
The message behavior of the SADB_GET message is:
Send a SADB_GET message from a user process to the kernel.
<base, association, address>
The kernel returns the SADB_GET message to the socket that sent
the SADB_GET message.
<base, association, (lifetime (HSC),) address, key, (identity,)
(sensitivity)>
Errors:
ESRCH The sought security association was not found.
3.1.6 SADB_ACQUIRE Message
The SADB_ACQUIRE message is typically sent only by the kernel to
key socket listeners who have registered their key socket (see
SADB_REGISTER message). SADB_ACQUIRE messages can be sent by
application-level consumers of security associations (such as an
OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE
message is a base header along with an address extension, possibly a
certificate identity extension, and if more than one algorithm and
options is acceptable, a proposal extension. The proposed situation
contains a list of desirable algorithms that can be used if the
algorithms in the base header are not available. The values for the
fields in the base header and in the security association data which
follows the base header indicate the properties of the Security
Association that the listening process should attempt to acquire. If
the message originates from the kernel (i.e. the sadb_msg_pid is 0),
McDonald, Metz, and Phan Expires in 6 months [Page 25]
Internet Draft PF_KEY, Version 2 21 April 1997
the sadb_seq number MUST be used by a subsequent SADB_GETSPI message
to bind a security association to the request. This avoids the race
condition of two TCP connections between two IP hosts that each
require unique associations, and having one steal another's security
association. The sadb_errno and sadb_state fields should be ignored
by the listening process.
The SADB_ACQUIRE message is typically triggered by an outbound
packet that needs security but for which there is no applicable
Security Association existing in the key table. If the packet can be
sufficiently protected by more than one algorithm or combination of
options, the SADB_ACQUIRE message MUST order the preference of
possibilities in the Proposal extension.
There are three messaging behaviors for SADB_ACQUIRE. The first is
where the kernel needs a security association (e.g. for IPsec).
The kernel sends a SADB_ACQUIRE message to registered sockets.
<base, address, (identity,) (sensitivity,) (proposal)>
The second is when, for some reason, key management fails, it can
send an ACQUIRE message with the same sadb_msg_seq as the initial
ACQUIRE with a non-zero errno.
Send an SADB_ACQUIRE to inidicate key management failure.
<base>
The third 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.
<base, address, (identity,) (sensitivity,) (proposal)>
The kernel returns a SADB_ACQUIRE message to registered sockets.
<base, address, (identity,) (sensitivity,) (proposal)>
The user-level consumer waits for a SADB_UPDATE or SADB_ADD
message for its particular type, and then can use that
association by using SADB_GET messages.
Errors:
EINVAL Invalid acquire request.
EPROTONOSUPPORT No KM application has registered with the Key
McDonald, Metz, and Phan Expires in 6 months [Page 26]
Internet Draft PF_KEY, Version 2 21 April 1997
Engine as being able to obtain the requested SA type, so
the requested SA cannot be acquired.
3.1.7 SADB_REGISTER Message
The SADB_REGISTER message allows an application to register its key
socket as able to acquire new security associations for the kernel.
SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for
the type of security association specified in sadb_sa_type. The
application specifies the type of security association that it can
acquire for the kernel in the type field of its register message. If
an application can acquire multiple types of security association, it
MUST register each type in a separate message. Only the base header
is needed for the register message. Key management applications MAY
register for a type not known to the kernel, because the consumer may
be in user-space (e.g. OSPFv2 security).
The reply of the SADB_REGISTER message contains a supported
algorithm extension. That field contains an array of supported
algorithm, one per octet. This allows key management applications to
know what algorithm are supported by the kernel.
In an enviroment where algorithms can be dynamically loaded and
unloaded, an asyncryonous SADB_REGISTER reply MAY be generated. The
list of supported algorithms MUST be a complete list, so the
application can make note of omissions or additions.
The messaging behavior of the SADB_REGISTER message is:
Send a SADB_REGISTER message from a user process to the kernel.
<base>
The kernel returns a SADB_REGISTER message to registered
sockets, with algorithm types supported by the kernel being
indicated in the supported algorithms field.
NOTE: This message may arrive asynchronously due to an algorithm
being loaded or unloaded into a dynamically linked kernel.
<base, supported>
3.1.8 SADB_EXPIRE Message
The operating system kernel is responsible for tracking SA
expirations for security protocols that are implemented inside the
kernel. If the soft limit or hard limit of a Security Association
has expired for a security protocol implemented inside the kernel,
McDonald, Metz, and Phan Expires in 6 months [Page 27]
Internet Draft PF_KEY, Version 2 21 April 1997
then the kernel MUST issue an SADB_EXPIRE message to all key socket
listeners. A user application is responsible for tracking SA
expirations for security protocols (e.g. OSPF Authentication) that
are implemented inside that user application. If the soft limit or
hard limit of a Security Association has expired, the user
application SHOULD issue a SADB_EXPIRE message.
The base header will contain the security association information
followed by the source sockaddr, destination sockaddr, (and, if
present, internal sockaddr,) (and, if present, one or both
compartment bitmaps).
The lifetime extension of an SADB_EXPIRE message is important to
indicate which lifetime expired. If a HARD lifetime extension is
included, it inidicates that the HARD lifetime expired. This means
the association MAY be deleted already from the SADB. If a SOFT
lifetime extension is included, it indicates that the SOFT lifetime
expired. The CURRENT lifetime extension will indicate the current
status, and comparisons to the HARD or SOFT lifetime will indicate
which limit was reached. HARD lifetimes MUST take precedence over
SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same,
the HARD lifetime will appear on the EXPIRE message. The
pathological case of HARD lifetimes being shorter than SOFT lifetimes
is handled such that the SOFT lifetime will never expire.
The messaging behavior of the SADB_EXPIRE message is:
The kernel sends a SADB_EXPIRE message to all listeners when the
soft limit of a security association has been expired.
<base, association, lifetime (HSC), address, (identity,)
(sensitivity)>
ERRORS:
EINVAL Message Invalid for some reason.
EPROTONOSUPPORT ???
3.1.9 SADB_FLUSH Message
The SADB_FLUSH message causes the kernel to delete all entries in
its key table for a certain sadb_sa_type. Only the base header is
required for a flush message. If sadb_sa_type is filled in with a
specific value, only associations of that type are deleted. If it is
filled in with SADB_SATYPE_NONE, ALL associations are deleted.
The messaging behavior for SADB_FLUSH is:
McDonald, Metz, and Phan Expires in 6 months [Page 28]
Internet Draft PF_KEY, Version 2 21 April 1997
Send a SADB_FLUSH message from a user process to the kernel.
<base>
The kernel will return a SADB_FLUSH message to all listening
sockets.
<base>
The reply message happens only after the actual flushing
of security associations has been attempted.
McDonald, Metz, and Phan Expires in 6 months [Page 29]
Internet Draft PF_KEY, Version 2 21 April 1997
3.1.10 SADB_DUMP Message
The SADB_DUMP message causes the kernel to dump the operating
system's entire Key Table to the requesting key socket. As in
SADB_FLUSH, if a sadb_sa_type value is in the message, only
associations of that type will be dumped. If SADB_SATYPE_NONE is
specified, all associations will be used. Each Security Association
is returned in its own SADB_DUMP message. A SADB_DUMP message with a
sadb_seq field of zero indicates the end of the dump transaction.
Unlike other key messages, the dump message is returned only to the
key socket originating the dump request because of the potentially
large amount of data it can generate. The dump message is used for
debugging purposes only and is not intended for production use.
Support for the dump message MAY be discontinued in future versions
of the key socket, hence key management applications MUST NOT depend
on this message for basic operation.
The messaging behavior for SADB_DUMP is:
Send a SADB_DUMP message from a user process to the kernel.
<base>
Several SADB_DUMP messages will return from the kernel to the
sending socket.
<base, association, (lifetime (HSC),) address, key, (identity,)
(sensitivity)>
McDonald, Metz, and Phan Expires in 6 months [Page 30]
Internet Draft PF_KEY, Version 2 21 April 1997
3.2 SECURITY ASSOCIATION FLAGS
The Security Association's flags are a bitmask field. These flags
also appear in a combination that is part of a PROPOSAL extension.
The related symbolic definitions below should be used in order that
applications will be portable:
#define SA_USED 0x1 /* SA used/not used */
#define SA_UNIQUE 0x2 /* SA unique/reusable */
#define SA_INBOUND 0x4 /* SA for packets destined here */
#define SA_OUTBOUND 0x8 /* SA for packets sourced here */
#define SA_FORWARD 0x10 /* SA for packets forwarded thru */
#define SA_PFS 0x20 /* Perfect forward secrecy? */
#define SA_REPLAY 0x40 /* Replay protection? */
SA_USED is set by the operating system if the Security Association
has been used. Otherwise this flag is not set. If SADB_GET is used
to read an SA from the Key Engine, the Key Engine will set SA_USED on
the SA that was read via SADB_GET.
SA_UNIQUE is set by the operating system if the Security
Association has been allocated uniquely to a single user (e.g. a
particular network socket). If this is not set, then the Security
Association is considered sharable.
SA_INBOUND is set for an inbound Security Association and
SA_OUTBOUND is set for an outbound Security Association. SA_FORWARD
is used for a Security Association used only for packets originating
elsewhere and destined elsewhere that have security processing on
this node. Both flags can be set in environments where bidirectional
security associations exist.
*******
[Dan McD.: Why SA_FORWARD? Isn't SA_OUTBOUND sufficient? I may
implement forwarding such that it's hard or impossible for
the key engine/SADB to tell the difference. ]
*******
The SA_PFS flag indicates to key management that this association
should have perfect forward secrecy in its key. (In other words, the
session key cannot be determined by cryptanalysis of previous keying
material.)
The SA_REPLAY specifies that replay protection should be enabled on
this association.
3.3 SECURITY ASSOCIATION STATE
The security association state field is an integer that describes
McDonald, Metz, and Phan Expires in 6 months [Page 31]
Internet Draft PF_KEY, Version 2 21 April 1997
the states of a security association. They are:
#define SA_STATE_LARVAL 0
#define SA_STATE_MATURE 1
#define SA_STATE_DYING 2
#define SA_STATE_DEAD 3
#define SA_STATE_MAX 3
A LARVAL security association is one that was created by the
SADB_GETSPI message. A MATURE association is one that was updated
with the SADB_UPDATE message or added with the SADB_ADD message. A
DYING association is one whose soft lifetime has expired. A DEAD
association is one whose hard lifetime has expired, but hasn't been
reaped by system garbage collection. If a consumer of security
associations has to extend an association beyond its normal lifetime
(e.g. OSPF Security) MUST only set the soft lifetime for an
association.
3.4 SECURITY ASSOCIATION TYPE
This defines the type of Security Association in this message. The
symbolic names are always the same, even on different
implementations. Applications SHOULD use the symbolic name in order
to have maximum portability across different implementations. These
are defined in the file <net/pfkeyv2.h>.
#define SADB_SATYPE_NONE 0
#define SADB_SATYPE_AH 1 /* RFC-1826 */
#define SADB_SATYPE_ESP 2 /* RFC-1827 */
#define SADB_SATYPE_RSVP 3 /* RSVP Authentication */
#define SADB_SATYPE_OSPFV2 4 /* OSPFv2 Authentication */
#define SADB_SATYPE_RIPV2 5 /* RIPv2 Authentication */
#define SADB_SATYPE_MIPV4 6 /* Mobile IPv4 Authentication */
#define SADB_SATYPE_MAX 6
SADB_SATYPE_NONE is defined for completeness and means no
Security Association. This type is never used with PF_KEY.
SADB_SATYPE_AH is for the IP Authentication Header defined in
[Atk95b]. SADB_SATYPE_ESP is for the IP Encapsulating Security
Payload defined in [Atk95c].
SADB_SATYPE_RSVP is for the RSVP Integrity Object.
McDonald, Metz, and Phan Expires in 6 months [Page 32]
Internet Draft PF_KEY, Version 2 21 April 1997
SADB_SATYPE_OSPFv2 is for OSPFv2 Cryptographic
authentication, while SADB_SATYPE_RIPv2 is for RIPv2 Cryptographic
authentication.
SADB_SATYPE_MAX is never used with PF_KEY but is defined for
completeness. It is always set to the highest valid numeric value.
There MUST not be gaps in the numbering of security types; all
numbers must be used sequentially.
3.5 ALGORITHM TYPES
The algorithm type is interpreted in the context of the Security
Association type defined above. The numeric value might vary between
implementations, but the symbolic name MUST NOT vary between
implementations. Applications should use the symbolic name in order
to have maximum portability to various implementations.
Some of the algorithm types defined below might not be standardized
or might be deprecated in the future. To obtain an assignment for a
symbolic name, contact the editor.
The symbols below are defined in <net/pfkeyv2.h>.
/* Authentication algorithms */
#define SADB_AALG_NONE 0
#define SADB_AALG_MD5_HMAC 1
#define SADB_AALG_SHA1_HMAC 2
#define SADB_AALG_MAX 2
/* Encryption algorithms */
#define SADB_EALG_NONE 0
#define SADB_EALG_DES_CBC 1
#define SADB_EALG_3DES 2
#define SADB_EALG_RC5 3
#define SADB_EALG_MAX 3
The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The
algorithm for SADB_AALG_SHA1_HMAC is defined in [CG96]. The
algorithm for SADB_EALG_DES_CBC is defined in [Hug96].
3.6 EXTENSION HEADER VALUES
To briefly recap the extension header values:
McDonald, Metz, and Phan Expires in 6 months [Page 33]
Internet Draft PF_KEY, Version 2 21 April 1997
#define SA_EXT_ASSOCIATION 1
#define SA_EXT_LIFETIME 2
#define SA_EXT_ADDRESS 3
#define SA_EXT_KEY 4
#define SA_EXT_IDENTITY 5
#define SA_EXT_SENSITIVITY 6
#define SA_EXT_PROPOSAL 7
#define SA_EXT_SUPPORTED 8
#define SA_EXT_SPI_RANGE 9
#define SA_EXT_MAX 9
3.7 ADDRESS EXTENSION VALUES
The sadb_address_which field is a bitmask which can indicate what
sockaddrs follow, and what they represent. These bit values are:
#define SADB_ADDR_SRC 0x1 /* Source */
#define SADB_ADDR_DST 0x2 /* Destination */
#define SADB_ADDR_INNER_SRC 0x4 /* Inner-packet src */
#define SADB_ADDR_INNNER_DST 0x8 /* Inner-packet dst */
#define SADB_ADDR_PROXY 0x10 /* Proxy address */
3.8 LIFETIME EXTENSION VALUES
The sadb_lifetime_which field is a bitmask which represents which
lifetime values are in the extension. These bit values are:
#define SADB_LIFETYPE_HARD 0x1 /* Hard lifetime */
#define SADB_LIFETYPE_SOFT 0x2 /* Soft lifetime */
#define SADB_LIFETYPE_CURRENT 0x4 /* Current lifetime left */
3.9 KEY EXTENSION VALUES
The sadb_keyblk_which field is a bitmask which represents which
keys are in the key block. These bit values are:
#define SADB_KEYBLK_AUTH 0x1 /* Authentication key */
#define SADB_KEYBLK_ENCRYPT 0x2 /* Encryption key */
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
McDonald, Metz, and Phan Expires in 6 months [Page 34]
Internet Draft PF_KEY, Version 2 21 April 1997
Each identity can have a certain type.
#define SADB_IDT_IPV4_ADDR 1
#define SADB_IDT_IPV6_ADDR 2
#define SADB_IDT_IPV4_RANGE 3
#define SADB_IDT_IPV6_RANGE 4
#define SADB_IDT_FQDN 5
#define SADB_IDT_USER_FQDN 6
#define SADB_IDT_IPV4_CONNID 7
#define SADB_IDT_IPV6_CONNID 8
#define SADB_IDT_MAX 8
3.11 SENSITIVITY EXTENSION VALUES
The only field currently defined in the sensitivity extension is
the sadb_sens_dpd, which represents the data protection domain. The
other data in the senstivity extension is based off the sadb_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
#define SADB_DPD_MAX 4
3.12 PROPOSAL EXTENSION VALUES
These are already mentioned in the ALGORITHM TYPES and ASSOCIATION
FLAGS sections.
McDonald, Metz, and Phan Expires in 6 months [Page 35]
Internet Draft PF_KEY, Version 2 21 April 1997
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 ? ]
*******
5. EXAMPLES
The following examples illustrate how PF_KEY is used. The first
example is an IP Security example, where the consumer of the security
associations is inside an operating system kernel. The second
example is an OSPF Security example, which illustrates a user-level
consumer of security associations. The third example covers things
not mentioned by the first two examples. A real system may closely
conform to one of these examples, or take parts of both. These
examples are purely illustrative, and are not intended to mandate a
particular implementation method.
5.1 IP SECURITY EXAMPLE
+---------------+ +-------------+
|Key Mgmt Daemon| | Application |
+---------------+ +-------------+
| | /
| | /
| | | Applications
======[PF_KEY]====[PF_INET]==========================
| | | OS Kernel
+------------+ +-----------------+
| Key Engine | | TCP/IP, |
| or SADB |---| including IPsec |
+------------+ | |
+-----------------+
When the Key Management daemon (KMd) begins. It must tell PF_KEY
that it is willing to accept message for the two IPsec services, AH
and ESP. It does this by sending down two SADB_REGISTER messages.
McDonald, Metz, and Phan Expires in 6 months [Page 36]
Internet Draft PF_KEY, Version 2 21 April 1997
KMd->Kernel: SADB_REGISTER for ESP
Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms
KMd->Kernel: SADB_REGISTER for AH
Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms
Each REGISTER message will cause a reply to go to all PF_KEY sockets
registered for ESP and AH respectively (including the requester).
Assume that no security associations currently exist for IPsec to
use. Consider when a network application begins transmitting data
(e.g. a TCP SYN). Because of policy, or the application's request,
the kernel IPsec module needs an AH security association for this
data. Since there is not one present, the following message is
generated:
Kernel->Registered: SADB_ACQUIRE for AH, addr, ID, sens, proposal
The KMd reads the ACQUIRE message, espcially the sadb_msg_seq
number. Before it begins the negotiation, it sends down an
SADB_GETSPI message with the sadb_msg_seq number equal to the one
received in the ACQUIRE. The kernel returns the results of the
GETSPI to all listening sockets.
KMd->Kernel: SADB_GETSPI for AH, addr, SPI range
Kernel->All: SADB_GETSPI for AH, assoc, addr
The KMd may perform a second GETSPI operation if it needs both
directions of IPsec SPI values. Now that the KMd has an SPI for at
least one of the security associations, it begins negotiation. After
deriving keying material, and negotiating other parameters, it sends
down one (or more) SADB_UPDATE messages.
Kebe
If a KMd has any error at all during its negotiation, it can send
down
KMd->Kernel: SADB_UPDATE for AH, assoc, addr, key, <etc.>
Kernel->All: SADB_UPDATE for AH, assoc, addr, <etc.>
The results of the UPDATE (minus the actual keying material) are sent
to all listening sockets. If only one SPI value was determined
locally, the other SPI (since IPsec SAs are unidirectional) must be
added with an SADB_ADD message.
KMd->Kernel: SADB_ADD for AH, assoc, addr, key, <etc.>
Kernel->All: SADB_ADD for AH, assoc, addr, <etc.>
If one of the extensions passed down was a Lifetime extension, it
McDonald, Metz, and Phan Expires in 6 months [Page 37]
Internet Draft PF_KEY, Version 2 21 April 1997
is possible at some point an SADB_EXPIRE message will arrive when one
of the lifetimes has expired.
Kernel->All: SADB_EXPIRE for AH, assoc, addr,
Hard or Soft, Current, <etc.>
The KMd can use this as a clue to begin negotiation, or, if it has
some say in policy, send an SADB_UPDATE down with a lifetime
extension.
5.2 OSPF SECURITY EXAMPLE
+---------------+ +-------------+
|Key Mgmt Daemon| | OSPF daemon |
+---------------+ +-------------+
| | / / |
| /------|----+ / |
| / | +---+ | Applications
======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================
| | | | OS Kernel
+------------+ +-----------------+ +---------+
| Key Engine | | TCP/IP, | | Routing |
| or SADB |---| including IPsec |--| Table |
+------------+ | | +---------+
+-----------------+
As in the previous example, the KMd registers itself. Even though
the consumer of the security associations is in user-space, the
PF_KEY implementation knows enough to store SAs and to relay
messages.
When the OSPF daemon needs to communicate securely with its peers,
it would perform an SADB_GET message and retreive the appropriate
association:
OSPFd->Kernel: SADB_GET of OSPF, assoc, address
Kernel->OSPFd: SADB_GET of OSPF, assoc, address, key, <etc.>
If this GET fails, the OSPFd may need to acquire a new security
association. This interaction is as follows:
OSPFd->Kernel: SADB_ACQUIRE of OSPF, addr, <ID, sens,> proposal
Kernel->Registered: SADB_ACQUIRE of OSPF, <same as sent message>
The KMd sees this and performs actions similar to the previous
example. One difference, however, is that when the UPDATE message
comes back, the OSPFd will then perform a GET of the updated SA to
retrieve ALL of its parameters.
McDonald, Metz, and Phan Expires in 6 months [Page 38]
Internet Draft PF_KEY, Version 2 21 April 1997
5.2.1 WHY INVOLVE THE KERNEL?
Some have suggested using the PF_KEY messages over something like a
UNIX pipe, or direct communication for situations like the one in
this example. It is a valid approach, but this document does not
pursue this possibility and leaves it to a willing party to document
it.
The two main reasons for involving the kernel are compatibility and
leverage. Compatibility is important so that a KMd can service as
many consumers of SAs as it can. Leverage means that an enhanced
kernel implementation (or specialized user-space OS components) can
provide common SA maintenance routines (such as expiration
generation).
5.3 MISCELLANY
Some messages work well only in system maintenance programs, for
debugging, or for auditing. In a system panic situation, such as a
detected compromise, an SADB_FLUSH message should be issued for a
particular SA type, or for ALL SA types.
Program->Kernel: SADB_FLUSH for ALL
<Kernel then flushes all internal SAs>
Kernel->All: SADB_FLUSH for ALL
Some SAs may need to be explicitly deleted, either my a KMd, or by
a system maintenance program.
Program->Kernel: SADB_DELETE for AH, association, address
Kernel->All: SADB_DELETE for AH, association, address
Common usage of the SADB_DUMP message is discouraged. For
debugging purposes, however, it can be quite useful. The output of a
DUMP message should be read quickly, in order to avoid socket buffer
overflows.
Program->Kernel: SADB_DUMP for ESP
Kernel->Program: SADB_DUMP for ESP, association, <all fields>
Kernel->Program: SADB_DUMP for ESP, association, <all fields>
Kernel->Program: SADB_DUMP for ESP, association, <all fields>
<ad nauseum...>
6. 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
McDonald, Metz, and Phan Expires in 6 months [Page 39]
Internet Draft PF_KEY, Version 2 21 April 1997
operations. It is unclear whether this mechanism provides any
security when used with operating systems not having the concept of a
trusted, privileged user.
If an unprivileged user is able to perform any of these operations,
then the operating system cannot actually provide the related
security services. If an adversary knows the keys and algorithms in
use, then cryptography cannot provide any form of protection.
This mechanism is not a panacea, but it does provide an important
operating system component that can be useful in creating a secure
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 40]
Internet Draft PF_KEY, Version 2 21 April 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 41]
Internet Draft PF_KEY, Version 2 21 April 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
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 01 and 02:
* Mentioned that people COULD use these same messages between user progs.
(Also mentioned why you still might want to use the actual socket.)
* Various wordsmithing changes.
* Took out netkey/ directory, and make net/pfkeyv2.h
* Inserted PF_KEY_V2 proto arguement per C. Metz.
* Mentioned other socket calls and how their PF_KEY behavior is undefined.
* SADB_EXPIRE now communicates both hard and soft lifetime expires.
* New "association" extension, even smaller base header.
* Lifetime extension improvements.
* Length now first in extensions.
* Errors can be sent from kernel to user, also.
* Examples section inserted.
McDonald, Metz, and Phan Expires in 6 months [Page 42]
Internet Draft PF_KEY, Version 2 21 April 1997
* Some bitfield cleanups, including STATE and SA_OPTIONS cleanup.
* Key splitting now only across auth algorithm and encryption algorithm.
Thanks for B. Sommerfeld for clues here.
The following changes were made between 00 and 01:
* Added this change log.
* Simplified TLV header syntax.
* Splitting of algorithms. This may be controversial, but it allows
PF_KEY to be used for more than just IPsec. It also allows policy to
be placed in the KMd easier.
* Added solid definitions and formats for certificate identities, multiple
keys, etc.
* Specified how keys are to be layed out (most-to-least bits).
* Changed sequence number semantics to be like an RPC transaction ID number.
McDonald, Metz, and Phan Expires in 6 months [Page 43]