RFC2367 - 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.
2.3 Additional Message Fields
The additional data following the base header consists of various
length-type-values fields. The first 32-bits are of a constant form:
struct sadb_ext {
uint16_t sadb_ext_len;
uint16_t sadb_ext_type;
};
/* sizeof(struct sadb_ext) == 4 */
sadb_ext_len Length of the extension header in 64 bit words,
inclusive.
sadb_ext_type The type of extension header that follows. Values for
this field are detailed later. The value zero is
reserved.
Types of extension headers include: Association, Lifetime(s),
Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and
Supported. There MUST be only one instance of a extension type in a
message. (e.g. Base, Key, Lifetime, Key is forbidden). An EINVAL
will be returned if there are duplicate extensions within a message.
Implementations MAY enforce ordering of extensions in the order
presented in the EXTENSION HEADER VALUES section.
If an unknown extension type is encountered, it MUST be ignored.
Applications using extension headers not specified in this document
MUST be prepared to work around other system components not
processing those headers. Likewise, if an application encounters an
unknown extension from the kernel, it must be prepared to work around
it. Also, a kernel that generates extra extension header types MUST
NOT _depend_ on applications also understanding extra extension
header types.
All extension definitions include these two fields (len and exttype)
because they are instances of a generic extension (not unlike
sockaddr_in and sockaddr_in6 are instances of a generic sockaddr).
The sadb_ext header MUST NOT ever be present in a message without at
least four bytes of extension header data following it, and,
therefore, there is no problem with it being only four bytes long.
All extensions documented in this section MUST be implemented by a
PF_KEY implementation.
2.3.1 Association Extension
The Association extension specifies data specific to a single
security association. The only times this extension is not present is
when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being
passed and on the SADB_ACQUIRE message.
struct sadb_sa {
uint16_t sadb_sa_len;
uint16_t sadb_sa_exttype;
uint32_t sadb_sa_spi;
uint8_t sadb_sa_replay;
uint8_t sadb_sa_state;
uint8_t sadb_sa_auth;
uint8_t sadb_sa_encrypt;
uint32_t sadb_sa_flags;
};
/* sizeof(struct sadb_sa) == 16 */
sadb_sa_spi The Security Parameters Index value for the security
association. Although this is a 32-bit field, some
types of security associations might have 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.
sadb_sa_replay The size of the replay window, if not zero. If zero,
then no replay window is in use.
sadb_sa_state The state of the security association. The currently
defined states are described later in this document.
sadb_sa_auth The authentication algorithm to be used with this
security association. The valid authentication
algorithms are described later in this document. A
value of zero means that no authentication is used
for this security association.
sadb_sa_encrypt The encryption algorithm to be used with this
security association. The valid encryption algorithms
are described later in this document. A value of zero
means that no encryption is used for this security
association.
sadb_sa_flags A bitmap of options defined for the security
association. The currently defined flags are
described later in this document.
The kernel MUST check these values where appropriate. For example,
IPsec AH with no authentication algorithm is probably an error.
When used with some messages, the values in some fields in this
header should be ignored.
2.3.2 Lifetime Extension
The Lifetime extension specifies one or more lifetime variants for
this security association. If no Lifetime extension is present the
association has an infinite lifetime. An association SHOULD have a
lifetime of some sort associated with it. Lifetime variants come in
three varieties, HARD - indicating the hard-limit expiration, SOFT -
indicating the soft-limit expiration, and CURRENT - indicating the
current state of a given security association. The Lifetime
extension looks like:
struct sadb_lifetime {
uint16_t sadb_lifetime_len;
uint16_t sadb_lifetime_exttype;
uint32_t sadb_lifetime_allocations;
uint64_t sadb_lifetime_bytes;
uint64_t sadb_lifetime_addtime;
uint64_t sadb_lifetime_usetime;
};
/* sizeof(struct sadb_lifetime) == 32 */
sadb_lifetime_allocations
For CURRENT, the number of different connections,
endpoints, or flows that the association has been
allocated towards. For HARD and SOFT, the number of
these the association may be allocated towards
before it expires. The concept of a connection,
flow, or endpoint is system specific.
sadb_lifetime_bytes
For CURRENT, how many bytes have been processed
using this security association. For HARD and SOFT,
the number of bytes that may be processed using
this security association before it expires.
sadb_lifetime_addtime
For CURRENT, the time, in seconds, when the
association was created. For HARD and SOFT, the
number of seconds after the creation of the
association until it expires.
For such time fields, it is assumed that 64-bits is
sufficiently large to hold the POSIX time_t value.
If this assumption is wrong, this field will have to
be revisited.
sadb_lifetime_usetime
For CURRENT, the time, in seconds, when association
was first used. For HARD and SOFT, the number of
seconds after the first use of the association until
it expires.
The semantics of lifetimes are inclusive-OR, first-to-expire. This
means that if values for bytes and time, or multiple times, are
passed in, the first of these values to be reached will cause a
lifetime expiration.
2.3.3 Address Extension
The Address extension specifies one or more addresses that are
associated with a security association. Address extensions for both
source and destination MUST be present when an Association extension
is present. The format of an Address extension is:
struct sadb_address {
uint16_t sadb_address_len;
uint16_t sadb_address_exttype;
uint8_t sadb_address_proto;
uint8_t sadb_address_prefixlen;
uint16_t sadb_address_reserved;
};
/* sizeof(struct sadb_address) == 8 */
/* followed by some form of struct sockaddr */
The sockaddr structure SHOULD conform to the sockaddr structure of
the system implementing PF_KEY. If the system has an sa_len field, so
SHOULD the sockaddrs in the message. If the system has NO sa_len
field, the sockaddrs SHOULD NOT have an sa_len field. All non-address
information in the sockaddrs, such as sin_zero for AF_INET sockaddrs,
and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out. The
zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all
messages except for originating SADB_ACQUIRE messages, which SHOULD
fill them in with ports from the relevant TCP or UDP session which
generates the ACQUIRE message. If the ports are non-zero, then the
sadb_address_proto field, normally zero, MUST be filled in with the
transport protocol"s number. If the sadb_address_prefixlen is non-
zero, then the address has a prefix (often used in KM access control
decisions), with length specified in sadb_address_prefixlen. These
additional fields may be useful to KM applications.
The SRC and DST addresses for a security association MUST be in the
same protocol family and MUST always be present or absent together in
a message. The PROXY address MAY be in a different protocol family,
and for most security protocols, represents an actual originator of a
packet. (For example, the inner-packets"s source address in a
tunnel.)
The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY)
address. The DST address can be any valid destination address
(unicast, multicast, or even broadcast). The PROXY address SHOULD be
a unicast address (there are experimental security protocols where
PROXY semantics may be different than described above).
2.3.4 Key Extension
The Key extension specifies one or more keys that are associated with
a security association. A Key extension will not always be present
with messages, because of security risks. The format of a Key
extension is:
struct sadb_key {
uint16_t sadb_key_len;
uint16_t sadb_key_exttype;
uint16_t sadb_key_bits;
uint16_t sadb_key_reserved;
};
/* sizeof(struct sadb_key) == 8 */
/* followed by the key data */
sadb_key_bits The length of the valid key data, in bits. A value of
zero in sadb_key_bits MUST cause an error.
The key extension comes in two varieties. The AUTH version is used
with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT
version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals
only with fully formed cryptographic keys, not with "raw key
material". For example, when ISAKMP/Oakley is in use, the key
management daemon is always responsible for transforming the result
of the Diffie-Hellman computation into distinct fully formed keys
PRIOR to sending those keys into the kernel via PF_KEY. This rule is
made because PF_KEY is designed to support multiple security
protocols (not just IP Security) and also multiple key management
schemes including manual keying, which does not have the concept of
"raw key material". A clean, protocol-independent interface is
important for portability to different operating systems as well as
for portability to different security protocols.
If an algorithm defines its key to include parity bits (e.g. DES)
then the key used with PF_KEY MUST also include those parity bits.
For example, this means that a single DES key is always a 64-bit
quantity.
When a particular security protocol only requires one authentication
and/or one encryption key, the fully formed key is transmitted using
the appropriate key extension. When a particular security protocol
requires more than one key for the same function (e.g. Triple-DES
using 2 or 3 keys, and asymmetric algorithms), then those two fully
formed keys MUST be concatenated together in the order used for
outbound packet processing. In the case of multiple keys, the
algorithm MUST be able to determine the lengths of the individual
keys based on the information provided. The total key length (when
combined with knowledge of the algorithm in use) usually provides
sufficient information to make this determination.
Keys are always passed through the PF_KEY interface in the order that
they are used for outbound packet processing. For inbound processing,
the correct order that keys are used might be different from this
canonical concatenation order used with the PF_KEY interface. It is
the responsibility of the implementation to use the keys in the
correct order for both inbound and outbound processing.
For example, consider a pair of nodes communicating unicast using an
ESP three-key Triple-DES Security Association. Both the outbound SA
on the sender node, and the inbound SA on the receiver node will
contain key-A, followed by key-B, followed by key-C in their
respective ENCRYPT key extensions. The outbound SA will use key-A
first, followed by key-B, then key-C when encrypting. The inbound SA
will use key-C, followed by key-B, then key-A when decrypting.
(NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.)
The canonical ordering of key-A, key-B, key-C is used for 3DES, and
should be documented. The order of "encryption" is the canonical
order for this example. [Sch96]
The key data bits are arranged most-significant to least significant.
For example, a 22-bit key would take up three octets, with the least
significant two bits not containing key material. Five additional
octets would then be used for padding to the next 64-bit boundary.
While not directly related to PF_KEY, there is a user interface issue
regarding odd-digit hexadecimal representation of keys. Consider the
example of the 16-bit number:
0x123
That will require two octets of storage. In the absence of other
information, however, unclear whether the value shown is stored as:
01 23 OR 12 30
It is the opinion of the authors that the former (0x123 == 0x0123) is
the better way to interpret this ambiguity. Extra information (for
example, specifying 0x0123 or 0x1230, or specifying that this is only
a twelve-bit number) would solve this problem.
2.3.5 Identity Extension
The Identity extension contains endpoint identities. This
information is used by key management to select the identity
certificate that is used in negotiations. This information may also
be provided by a kernel to network security aware applications to
identify the remote entity, possibly for access control purposes. If
this extension is not present, key management MUST assume that the
addresses in the Address extension are the only identities for this
Security Association. The Identity extension looks like:
struct sadb_ident {
uint16_t sadb_ident_len;
uint16_t sadb_ident_exttype;
uint16_t sadb_ident_type;
uint16_t sadb_ident_reserved;
uint64_t sadb_ident_id;
};
/* sizeof(struct sadb_ident) == 16 */
/* followed by the identity string, if present */
sadb_ident_type The type of identity information that follows.
Currently defined identity types are described later
in this document.
sadb_ident_id An identifier used to aid in the construction of an
identity string if none is present. A POSIX user id
value is one such identifier that will be used in this
field. Use of this field is described later in this
document.
A C string containing a textual representation of the identity
information optionally follows the sadb_ident extension. The format
of this string is determined by the value in sadb_ident_type, and is
described later in this document.
2.3.6 Sensitivity Extension
The Sensitivity extension contains security labeling information for
a security association. If this extension is not present, no
sensitivity-related data can be obtained from this security
association. If this extension is present, then the need for
explicit security labeling on the packet is obviated.
struct sadb_sens {
uint16_t sadb_sens_len;
uint16_t sadb_sens_exttype;
uint32_t sadb_sens_dpd;
uint8_t sadb_sens_sens_level;
uint8_t sadb_sens_sens_len;
uint8_t sadb_sens_integ_level;
uint8_t sadb_sens_integ_len;
uint32_t sadb_sens_reserved;
};
/* sizeof(struct sadb_sens) == 16 */
/* followed by:
uint64_t sadb_sens_bitmap[sens_len];
uint64_t sadb_integ_bitmap[integ_len]; */
sadb_sens_dpd Describes the protection domain, which allows
interpretation of the levels and compartment
bitmaps.
sadb_sens_sens_level
The sensitivity level.
sadb_sens_sens_len
The length, in 64 bit words, of the sensitivity
bitmap.
sadb_sens_integ_level
The integrity level.
sadb_sens_integ_len
The length, in 64 bit words, of the integrity
bitmap.
This sensitivity extension is designed to support the Bell-LaPadula
[BL74] security model used in compartmented-mode or multi-level
secure systems, the Clark-Wilson [CW87] commercial security model,
and/or the Biba integrity model [Biba77]. These formal models can be
used to implement a wide variety of security policies. The definition
of a particular security policy is outside the scope of this
document. Each of the bitmaps MUST be padded to a 64-bit boundary if
they are not implicitly 64-bit aligned.
2.3.7 Proposal Extension
The Proposal extension contains a "proposed situation" of algorithm
preferences. It looks like:
struct sadb_prop {
uint16_t sadb_prop_len;
uint16_t sadb_prop_exttype;
uint8_t sadb_prop_replay;
uint8_t sadb_prop_reserved[3];
};
/* sizeof(struct sadb_prop) == 8 */
/* followed by:
struct sadb_comb sadb_combs[(sadb_prop_len *
sizeof(uint64_t) - sizeof(struct sadb_prop)) /
sizeof(struct sadb_comb)]; */
Following the header is a list of proposed parameter combinations in
preferential order. The values in these fields have the same
definition as the fields those values will move into if the
combination is chosen.
NOTE: Some algorithms in some security protocols will have
variable IV lengths per algorithm. Variable length IVs
are not supported by PF_KEY v2. If they were, however,
proposed IV lengths would go in the Proposal Extension.
These combinations look like:
struct sadb_comb {
uint8_t sadb_comb_auth;
uint8_t sadb_comb_encrypt;
uint16_t sadb_comb_flags;
uint16_t sadb_comb_auth_minbits;
uint16_t sadb_comb_auth_maxbits;
uint16_t sadb_comb_encrypt_minbits;
uint16_t sadb_comb_encrypt_maxbits;
uint32_t sadb_comb_reserved;
uint32_t sadb_comb_soft_allocations;
uint32_t sadb_comb_hard_allocations;
uint64_t sadb_comb_soft_bytes;
uint64_t sadb_comb_hard_bytes;
uint64_t sadb_comb_soft_addtime;
uint64_t sadb_comb_hard_addtime;
uint64_t sadb_comb_soft_usetime;
uint64_t sadb_comb_hard_usetime;
};
/* sizeof(struct sadb_comb) == 72 */
sadb_comb_auth If this combination is accepted, this will be the
value of sadb_sa_auth.
sadb_comb_encrypt
If this combination is accepted, this will be the
value of sadb_sa_encrypt.
sadb_comb_auth_minbits;
sadb_comb_auth_maxbits;
The minimum and maximum acceptable authentication
key lengths, respectably, in bits. If sadb_comb_auth
is zero, both of these values MUST be zero. If
sadb_comb_auth is nonzero, both of these values MUST
be nonzero. If this combination is accepted, a value
between these (inclusive) will be stored in the
sadb_key_bits field of KEY_AUTH. The minimum MUST
NOT be greater than the maximum.
sadb_comb_encrypt_minbits;
sadb_comb_encrypt_maxbits;
The minimum and maximum acceptable encryption key
lengths, respectably, in bits. If sadb_comb_encrypt
is zero, both of these values MUST be zero. If
sadb_comb_encrypt is nonzero, both of these values
MUST be nonzero. If this combination is accepted, a
value between these (inclusive) will be stored in
the sadb_key_bits field of KEY_ENCRYPT. The minimum
MUST NOT be greater than the maximum.
sadb_comb_soft_allocations
sadb_comb_hard_allocations
If this combination is accepted, these are proposed
values of sadb_lifetime_allocations in the SOFT and
HARD lifetimes, respectively.
sadb_comb_soft_bytes
sadb_comb_hard_bytes
If this combination is accepted, these are proposed
values of sadb_lifetime_bytes in the SOFT and HARD
lifetimes, respectively.
sadb_comb_soft_addtime
sadb_comb_hard_addtime
If this combination is accepted, these are proposed
values of sadb_lifetime_addtime in the SOFT and HARD
lifetimes, respectively.
sadb_comb_soft_usetime
sadb_comb_hard_usetime
If this combination is accepted, these are proposed
values of sadb_lifetime_usetime in the SOFT and HARD
lifetimes, respectively.
Each combination has an authentication and encryption algorithm,
which may be 0, indicating none. A combination"s flags are the same
as the flags in the Association extension. The minimum and maximum
key lengths (which are in bits) are derived from possible a priori
policy decisions, along with basic properties of the algorithm.
Lifetime attributes are also included in a combination, as some
algorithms may know something about their lifetimes and can suggest
lifetime limits.
2.3.8 Supported Algorithms Extension
The Supported Algorithms extension contains a list of all algorithms
supported by the system. This tells key management what algorithms it
can negotiate. Available authentication algorithms are listed in the
SUPPORTED_AUTH extension and available encryption algorithms are
listed in the SUPPORTED_ENCRYPT extension. The format of these
extensions is:
struct sadb_supported {
uint16_t sadb_supported_len;
uint16_t sadb_supported_exttype;
uint32_t sadb_supported_reserved;
};
/* sizeof(struct sadb_supported) == 8 */
/* followed by:
struct sadb_alg sadb_algs[(sadb_supported_len *
sizeof(uint64_t) - sizeof(struct sadb_supported)) /
sizeof(struct sadb_alg)]; */
This header is followed by one or more algorithm descriptions. An
algorithm description looks like:
struct sadb_alg {
uint8_t sadb_alg_id;
uint8_t sadb_alg_ivlen;
uint16_t sadb_alg_minbits;
uint16_t sadb_alg_maxbits;
uint16_t sadb_alg_reserved;
};
/* sizeof(struct sadb_alg) == 8 */
sadb_alg_id The algorithm identification value for this
algorithm. This is the value that is stored in
sadb_sa_auth or sadb_sa_encrypt if this algorithm is
selected.
sadb_alg_ivlen The length of the initialization vector to be used
for the algorithm. If an IV is not needed, this
value MUST be set to zero.
sadb_alg_minbits
The minimum acceptable key length, in bits. A value
of zero is invalid.
sadb_alg_maxbits
The maximum acceptable key length, in bits. A value
of zero is invalid. The minimum MUST NOT be greater
than the maximum.
2.3.9 SPI Range Extension
One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI
values. This extension performs such a function.
struct sadb_spirange {
uint16_t sadb_spirange_len;
uint16_t sadb_spirange_exttype;
uint32_t sadb_spirange_min;
uint32_t sadb_spirange_max;
uint32_t sadb_spirange_reserved;
};
/* sizeof(struct sadb_spirange) == 16 */
sadb_spirange_min
The minimum acceptable SPI value.
sadb_spirange_max
The maximum acceptable SPI value. The maximum MUST
be greater than or equal to the minimum.
2.4 Illustration of Message Layout
The following shows how the octets are laid out in a PF_KEY message.
Optional fields are indicated as such.
The base header is as follows:
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+---------------+---------------+---------------+---------------+
...version sadb_msg_type sadb_msg_errno ...msg_satype
+---------------+---------------+---------------+---------------+
sadb_msg_len sadb_msg_reserved
+---------------+---------------+---------------+---------------+
sadb_msg_seq
+---------------+---------------+---------------+---------------+
sadb_msg_pid
+---------------+---------------+---------------+---------------+
The base header may be followed by one or more of the following
extension fields, depending on the values of various base header
fields. The following fields are ordered such that if they appear,
they SHOULD appear in the order presented below.
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_exttype
+---------------+---------------+---------------+---------------+
sadb_sa_spi
+---------------+---------------+---------------+---------------+
...replay sadb_sa_state sadb_sa_auth sadb_sa_encrypt
+---------------+---------------+---------------+---------------+
sadb_sa_flags
+---------------+---------------+---------------+---------------+
The Lifetime extension
+---------------+---------------+---------------+---------------+
sadb_lifetime_len sadb_lifetime_exttype
+---------------+---------------+---------------+---------------+
sadb_lifetime_allocations
+---------------+---------------+---------------+---------------+
+---------------+---------------+---------------+---------------+
sadb_lifetime_bytes
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_lifetime_addtime
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_lifetime_usetime
(64 bits)
+---------------+---------------+---------------+---------------+
The Address extension
+---------------+---------------+---------------+---------------+
sadb_address_len sadb_address_exttype
+---------------+---------------+---------------+---------------+
_address_proto ..._prefixlen sadb_address_reserved
+---------------+---------------+---------------+---------------+
> Some form of 64-bit aligned struct sockaddr goes here. <
+---------------+---------------+---------------+---------------+
The Key extension
+---------------+---------------+---------------+---------------+
sadb_key_len sadb_key_exttype
+---------------+---------------+---------------+---------------+
sadb_key_bits sadb_key_reserved
+---------------+---------------+---------------+---------------+
> A key, padded to 64-bits, most significant bits to least. >
+---------------+---------------+---------------+---------------+
The Identity extension
+---------------+---------------+---------------+---------------+
sadb_ident_len sadb_ident_exttype
+---------------+---------------+---------------+---------------+
sadb_ident_type sadb_ident_reserved
+---------------+---------------+---------------+---------------+
sadb_ident_id
(64 bits)
+---------------+---------------+---------------+---------------+
> A null-terminated C-string which MUST be padded out for >
< 64-bit alignment. <
+---------------+---------------+---------------+---------------+
The Sensitivity extension
+---------------+---------------+---------------+---------------+
sadb_sens_len sadb_sens_exttype
+---------------+---------------+---------------+---------------+
sadb_sens_dpd
+---------------+---------------+---------------+---------------+
...sens_level ...sens_len ..._integ_level ..integ_len
+---------------+---------------+---------------+---------------+
sadb_sens_reserved
+---------------+---------------+---------------+---------------+
> The sensitivity bitmap, followed immediately by the <
< integrity bitmap, each is an array of uint64_t. >
+---------------+---------------+---------------+---------------+
The Proposal extension
+---------------+---------------+---------------+---------------+
sadb_prop_len sadb_prop_exttype
+---------------+---------------+---------------+---------------+
...prop_replay sadb_prop_reserved
+---------------+---------------+---------------+---------------+
> One or more combinations, specified as follows... <
+---------------+---------------+---------------+---------------+
Combination
+---------------+---------------+---------------+---------------+
sadb_comb_auth sadb_comb_encr sadb_comb_flags
+---------------+---------------+---------------+---------------+
sadb_comb_auth_minbits sadb_comb_auth_maxbits
+---------------+---------------+---------------+---------------+
sadb_comb_encrypt_minbits sadb_comb_encrypt_maxbits
+---------------+---------------+---------------+---------------+
sadb_comb_reserved
+---------------+---------------+---------------+---------------+
sadb_comb_soft_allocations
+---------------+---------------+---------------+---------------+
sadb_comb_hard_allocations
+---------------+---------------+---------------+---------------+
sadb_comb_soft_bytes
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_comb_hard_bytes
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_comb_soft_addtime
(64 bits)
+---------------+---------------+---------------+---------------+
+---------------+---------------+---------------+---------------+
sadb_comb_hard_addtime
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_comb_soft_usetime
(64 bits)
+---------------+---------------+---------------+---------------+
sadb_comb_hard_usetime
(64 bits)
+---------------+---------------+---------------+---------------+
The Supported Algorithms extension
+---------------+---------------+---------------+---------------+
sadb_supported_len sadb_supported_exttype
+---------------+---------------+---------------+---------------+
sadb_supported_reserved
+---------------+---------------+---------------+---------------+
Followed by one or more Algorithm Descriptors
+---------------+---------------+---------------+---------------+
sadb_alg_id sadb_alg_ivlen sadb_alg_minbits
+---------------+---------------+---------------+---------------+
sadb_alg_maxbits sadb_alg_reserved
+---------------+---------------+---------------+---------------+
The SPI Range extension
+---------------+---------------+---------------+---------------+
sadb_spirange_len sadb_spirange_exttype
+---------------+---------------+---------------+---------------+
sadb_spirange_min
+---------------+---------------+---------------+---------------+
sadb_spirange_max
+---------------+---------------+---------------+---------------+
sadb_spirange_reserved
+---------------+---------------+---------------+---------------+
3 Symbolic Names
This section defines various symbols used with PF_KEY and the
semantics associated with each symbol. Applications MUST use the
symbolic names in order to be portable. The numeric definitions
shown are for illustrative purposes, unless explicitly stated
otherwise. The numeric definition MAY vary on other systems. The
symbolic name MUST be kept the same for all conforming
implementations.
3.1 Message Types
The following message types are used with PF_KEY. These are defined
in the file <net/pfkeyv2.h>.
#define SADB_RESERVED 0
#define SADB_GETSPI 1
#define SADB_UPDATE 2
#define SADB_ADD 3
#define SADB_DELETE 4
#define SADB_GET 5
#define SADB_ACQUIRE 6
#define SADB_REGISTER 7
#define SADB_EXPIRE 8
#define SADB_FLUSH 9
#define SADB_DUMP 10 /* not used normally */
#define SADB_MAX 10
Each message has a behavior. A behavior is defined as where the
initial message travels (e.g. user to kernel), and what subsequent
actions are expected to take place. Contents of messages are
illustrated as:
<base, REQUIRED EXTENSION, REQ., (OPTIONAL EXT.,) (OPT)>
The SA extension is sometimes used only for its SPI field. If all
other fields MUST be ignored, this is represented by "SA(*)".
The lifetime extensions are represented with one to three letters
after the word "lifetime," representing (H)ARD, (S)OFT, and
(C)URRENT.
The address extensions are represented with one to three letters
after the word "address," representing (S)RC, (D)ST, (P)ROXY.
NOTE: Some security association types do not use a source
address for SA identification, where others do. This may
cause EEXIST errors for some SA types where others do not
report collisions. It is expected that application
authors know enough about the underlying security
association types to understand these differences.
The key extensions are represented with one or two letters after the
word "key," representing (A)UTH and (E)NCRYPT.
The identity extensions are represented with one or two letters after
the word "identity," representing (S)RC and (D)ST.
In the case of an error, only the base header is returned.
Note that any standard error could be returned for any message.
Typically, they will be either one of the errors specifically listed
in the description for a message or one of the following:
EINVAL Various me