As per Relevance of the word association, we have this rfc below:
Network Working Group D.
Request for Comments: 2367 C.
Category: Informational B.
July 1998
PF_KEY Key Management API, Version 2
Status of this
This memo provides information for the Internet community. It
not specify an Internet standard of any kind. Distribution of
memo is unlimited
Copyright
Copyright (C) The Internet Society (1998). All Rights Reserved
A generic key management API that can be used not only for
Security [Atk95a] [Atk95b] [Atk95c] but also for other
security services is presented in this document. Version 1 of
API was implemented inside 4.4-Lite BSD as part of the U. S.
Research Laboratory's freely distributable and usable IPv6 and
implementation[AMPMC96]. It is documented here for the benefit
others who might also adopt and use the API, thus providing
portability of key management applications (e.g. a manual
application, an ISAKMP daemon, a GKMP daemon [HM97a][HM97b],
Photuris daemon, or a SKIP certificate discovery protocol daemon).
Table of
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
McDonald, et. al. Informational [Page 1]
RFC 2367 PF_KEY Key Management API July 1998
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
McDonald, et. al. Informational [Page 2]
RFC 2367 PF_KEY Key Management API July 1998
1
PF_KEY is a new socket protocol family used by trusted privileged
management applications to communicate with an operating system's
management internals (referred to here as the "Key Engine" or
Security Association Database (SADB)). The Key Engine and
structures incorporate the required security attributes for a
and are instances of the "Security Association" (SA)
described in [Atk95a]. The names PF_KEY and Key Engine thus refer
more than cryptographic keys and are retained for consistency
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
implemented in the first five alpha test versions of the
IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the
ISAKMP/Oakley key management daemon. Version 2 extends and
this interface. Theoretically, the messages defined in this
could be used in a non-socket context (e.g. between two
communicating user-level processes), but this document will
discuss in detail such possibilities
Security policy is deliberately omitted from this interface. PF_
is not a mechanism for tuning systemwide security policy, nor is
intended to enforce any sort of key management policy. The
of PF_KEY believe that it is important to separate
mechanisms (such as PF_KEY) from security policies. This permits
single mechanism to more easily support multiple policies
1.1
Even though this document is not intended to be an actual
standard, the words that are used to define the significance
particular features of this interface are usually capitalized.
of these words, including MUST, MAY, and SHOULD, are detailed
[Bra97].
- CONFORMANCE and
Conformance to this specification has the same meaning as
to this specification. In either case, the mandatory-to-implement
or MUST, items MUST be fully implemented as specified here. If
mandatory item is not implemented as specified here,
implementation is not conforming and not compliant with
specification
McDonald, et. al. Informational [Page 3]
RFC 2367 PF_KEY Key Management API July 1998
This specification also uses many terms that are commonly used in
context of network security. Other documents provide
definitions and background information on these [VK83, HA94, Atk95a].
Two terms deserve special mention
- (Encryption/Authentication)
For PF_KEY purposes, an algorithm, whether encryption
authentication, is the set of operations performed on a packet
complete authentication or encryption as indicated by the SA type.
PF_KEY algorithm MAY consist of more than one
algorithm. Another possibility is that the same basic
algorithm may be applied with different modes of operation or
other implementation difference. These differences, henceforth
_algorithm differentiators_, distinguish between different PF_
algorithms, and options to the same algorithm.
differentiators will often cause fundamentally different
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
differentiator. There are therefore separate PF_KEY algorithms
DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same hash function,
construct their message authentication codes differently. The use
HMAC is an algorithm differentiator. DES-ECB and DES-CBC are
same cryptographic algorithm, but use a different mode. Mode (e.g.,
chaining vs. code-book) is an algorithm differentiator. Blowfish
a 128-bit key, however, is similar to Blowfish with a 384-bit key
because the algorithm's workings are otherwise the same and
the key length is not an algorithm differentiator
In terms of IP Security, a general rule of thumb is that
might be labeled the "encryption" part of an ESP transform
probably a PF_KEY encryption algorithm. Whatever might be
the "authentication" part of an AH or ESP transform is probably
PF_KEY authentication algorithm
1.2 Conceptual
This section describes the conceptual model of an operating
that implements the PF_KEY key management application
interface. This section is intended to provide background
useful to understand the rest of this document. Presentation of
conceptual model does not constrain a PF_KEY implementation
strictly adhere to the conceptual components discussed in
subsection
McDonald, et. al. Informational [Page 4]
RFC 2367 PF_KEY Key Management API July 1998
Key management is most commonly implemented in whole or in part
the application layer. For example, the ISAKMP/Oakley, GKMP,
Photuris proposals for IPsec key management are all application-
protocols. Manual keying is also done at the application layer
Even parts of the SKIP IP-layer keying proposal can be implemented
the application layer. Figure 1 shows the relationship between a
Management daemon and PF_KEY. Key management daemons use PF_KEY
communicate with the Key Engine and use PF_INET (or PF_INET6 in
case of IPv6) to communicate, via the network, with a remote
management entity
The "Key Engine" or "Security Association Database (SADB)" is
logical entity in the kernel that stores, updates, and
Security Association data for various security protocols. There
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
Associations
In the case of IPsec, if by policy a particular outbound packet
processing, then the IPsec implementation requests an
Security Association from the Key Engine via the kernel-
interface. If the Key Engine has an appropriate SA, it allocates
SA to this session (marking it as used) and returns the SA to
IPsec implementation for use. If the Key Engine has no such SA but
key management application has previously indicated (via a PF_
SADB_REGISTER message) that it can obtain such SAs, then the
Engine requests that such an SA be created (via a PF_KEY SADB_
message). When the key management daemon creates a new SA, it
it into the Key Engine for future use
McDonald, et. al. Informational [Page 5]
RFC 2367 PF_KEY Key Management API July 1998
+---------------+
|Key Mgmt Daemon
+---------------+
| |
| |
| |
======[PF_KEY]====[PF_INET]==========================
| | OS
+------------+ +-----------------+
| Key Engine | | TCP/IP, |
| or SADB |---| including IPsec |
+------------+ | |
+-----------------+
|
+-----------+
| Network |
| Interface |
+-----------+
Figure 1: Relationship of Key Mgmt to PF_
For performance reasons, some security protocols (e.g. IP Security
are usually implemented inside the operating system kernel.
security protocols (e.g. OSPFv2 Cryptographic Authentication)
implemented in trusted privileged applications outside the kernel
Figure 2 shows a trusted, privileged routing daemon using PF_INET
communicate routing information with a remote routing daemon
using PF_KEY to request, obtain, and delete Security
used with a routing protocol
McDonald, et. al. Informational [Page 6]
RFC 2367 PF_KEY Key Management API July 1998
+---------------+
|Routing Daemon
+---------------+
| |
| |
| |
======[PF_KEY]====[PF_INET]==========================
| | OS
+------------+ +---------+
| Key Engine | | TCP/IP |
| or SADB |---| |
+------------+ +---------+
|
+-----------+
| Network |
| Interface |
+-----------+
Figure 2: Relationship of Trusted Application to PF_
When a trusted privileged application is using the Key Engine
implements the security protocol within itself, then operation
slightly. In this case, the application needing an SA sends a PF_
SADB_ACQUIRE message down to the Key Engine, which then
returns an error or sends a similar SADB_ACQUIRE message up to one
more key management applications capable of creating such SAs.
before, the key management daemon stores the SA into the Key Engine
Then, the trusted privileged application uses an SADB_GET message
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
kernel. Such policy communication between the kernel mechanisms
the user-space policy MAY be implemented by PF_KEY extensions,
other such mechanism. This document does not specify
extensions. A PF_KEY implementation specified by the memo does
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
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
McDonald, et. al. Informational [Page 7]
RFC 2367 PF_KEY Key Management API July 1998
1.3 PF_KEY Socket
The PF_KEY protocol family (PF_KEY) symbol is defined
in the same manner that other protocol families
defined. PF_KEY does not use any socket addresses.
using PF_KEY MUST NOT depend on the availability of a symbol
AF_KEY, but kernel implementations are encouraged to define
symbol for completeness
The key management socket is created as follows
#include
#include
#include
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
will be returned. Only a trusted, privileged process can create
PF_KEY socket. On conventional UNIX systems, a privileged process
a process with an effective userid of zero. On non-MLS
operating systems, the notion of a "privileged process"
implementation-defined. On Compartmented Mode Workstations (CMWs)
other systems that claim to provide Multi-Level Security (MLS),
process MUST have the "key management privilege" in order to open
PF_KEY socket[DIA]. MLS systems that don't currently have such
specific privilege MUST add that special privilege and enforce
with PF_KEY in order to comply and conform with this specification
Some systems, most notably some popular personal computers, do
have the concept of an unprivileged user. These systems SHOULD
steps to restrict the programs allowed to access the PF_KEY API
1.4 Overview of PF_KEY Messaging
A process interacts with the key engine by sending and
messages using the PF_KEY socket. Security association
can be inserted into and retrieved from the kernel's
association table using a set of predefined messages. In the
case, all properly-formed messages sent to the kernel are returned
all open PF_KEY sockets, including the sender. Improperly
messages will result in errors, and an implementation MUST check
a properly formed message before returning it to the
listeners. Unlike the routing socket, most errors are sent in
messages, not the errno field when write() or send() fails. PF_
message delivery is not guaranteed, especially in cases where
or socket buffers are exhausted and messages are dropped
McDonald, et. al. Informational [Page 8]
RFC 2367 PF_KEY Key Management API July 1998
Some messages are generated by the operating system to indicate
actions need to be taken, and are not necessarily in response to
message sent down by the user. Such messages are not received by
PF_KEY sockets, but by sockets which have indicated that kernel
originated messages are to be received. These messages are
because of the expected frequency at which they will occur. Also,
implementation may further wish to restrict return messages from
kernel, in cases where not all PF_KEY sockets are in the same
domain
Many of the normal BSD socket calls have undefined behavior on PF_
sockets. These include: bind(), connect(), socketpair(), accept(),
getpeername(), getsockname(), ioctl(), and listen().
1.5 Common PF_KEY
There are two basic ways to add a new Security Association into
kernel. The simplest is to send a single SADB_ADD message
containing all of the SA information, from the application into
kernel's Key Engine. This approach works particularly well
manual key management, which is required for IPsec, and
security protocols
The second approach to add a new Security Association into the
is for the application to first request a Security Parameters
(SPI) value from the kernel using the SADB_GETSPI message and
send an SADB_UPDATE message with the complete Security
data. This second approach works well with key management
when the SPI values need to be known before the entire
Association data is known (e.g. so the SPI value can be indicated
the remote end of the key management session).
An individual Security Association can be deleted using
SADB_DELETE message. Categories of SAs or the entire kernel SA
can be deleted using the SADB_FLUSH message
The SADB_GET message is used by a trusted application-layer
(e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or
SA) from the kernel's Key Engine
The kernel or an application-layer can use the SADB_ACQUIRE
to request that a Security Association be created by
application-layer key management process that has registered with
kernel via an SADB_REGISTER message. This ACQUIRE message will
a sequence number associated with it. This sequence number MUST
used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages,
order to keep track of which request gets its keying material.
sequence number (described below) is similar to a transaction ID in
McDonald, et. al. Informational [Page 9]
RFC 2367 PF_KEY Key Management API July 1998
remote procedure call
The SADB_EXPIRE message is sent from the kernel to key
applications when the "soft lifetime" or "hard lifetime" of
Security Association has expired. Key management applications
use receipt of a soft lifetime SADB_EXPIRE message as a hint
negotiate a replacement SA so the replacement SA will be ready and
the kernel before it is needed
A SADB_DUMP message is also defined, but this is primarily
for PF_KEY implementor debugging and is not used in
operation of PF_KEY
1.6 Differences Between PF_KEY and PF_
The following bullets are points of difference between the
socket and PF_KEY. Programmers who are used to the routing
semantics will find some differences in PF_KEY
* PF_KEY message errors are usually returned in PF_KEY
instead of causing write() operations to fail and returning
error number in errno. This means that other listeners on a PF_
socket can be aware that requests from another process failed
which can be useful for auditing purposes. This also means
applications that fail to read PF_KEY messages cannot do
checking
An implementation MAY return the errors EINVAL, ENOMEM, and
by causing write() operations to fail and returning the
number in errno. This is an optimization for common error cases
which it does not make sense for any other process to receive
error. An application MUST NOT depend on such errors being set
the write() call, but it SHOULD check for such errors, and
them in an appropriate manner
* The entire message isn't always reflected in the reply. A SADB_
message is an example of this
* The PID is not set by the kernel. The process that originates
message MUST set the sadb_msg_pid to its own PID. If the
ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A
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
to the pid value of the original SADB_ADD message.)
McDonald, et. al. Informational [Page 10]
RFC 2367 PF_KEY Key Management API July 1998
1.7 Name
All PF_KEYv2 preprocessor symbols and structure definitions
defined as a result of including the header file .
There is exactly one exception to this rule: the symbol "PF_KEY" (
exceptions if "AF_KEY" is also counted), which is defined as a
of including the header file . All PF_KEYv
preprocessor symbols start with the prefix "SADB_" and all
names start with "sadb_". There are exactly two exceptions to
rule: the symbol "PF_KEY_V2" and the symbol "PFKEYV2_REVISION".
The symbol "PFKEYV2_REVISION" is a date-encoded value not
certain values defined by POSIX and X/Open. The current value
PFKEYV2_REVISION is 199806L, where 1998 is the year and 06 is
month
Inclusion of the file MUST NOT define symbols
structures in the PF_KEYv2 name space that are not described in
document without the explicit prior permission of the authors.
symbols or structures in the PF_KEYv2 name space that are
described in this document MUST start with "SADB_X_" or "sadb_x_".
implementation that fails to obey these rules IS NOT COMPLIANT
THIS SPECIFICATION and MUST NOT make any claim to be. These
also apply to any files that might be included as a result
including the file . This rule provides
with some assurance that they will not encounter namespace-
surprises
1.8 On Manual
Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows
application full-reign over the security associations in a
that implements PF_KEY. A PF_KEY implementation MUST have some
of manual interface to PF_KEY, which SHOULD allow all of
functionality of the programmatic interface described here
2. PF_KEY Message
PF_KEY messages consist of a base header followed by additional
fields, some of which may be optional. The format of the
data is dependent on the type of message
PF_KEY messages currently do not mandate any specific ordering
non-network multi-octet fields. Unless otherwise specified (e.g.
values), fields MUST be in host-specific byte order
McDonald, et. al. Informational [Page 11]
RFC 2367 PF_KEY Key Management API July 1998
2.1 Base Message Header
PF_KEY messages consist of the base message header followed
security association specific data whose types and lengths
specified by a generic type-length encoding
This base header is shown below, using POSIX types. The fields
arranged primarily for alignment, and where possible, for reasons
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_
The version field of this PF_KEY message. This
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
the application might not understand the
of the messages arriving from the kernel
sadb_msg_type Identifies the type of message. The valid
types are described later in this document
sadb_msg_errno Should be set to zero by the sender. The
stores the error code in this field if an error
occurred. This includes the case where the
is in user space. (e.g. user-space
fails, an errno can be returned.)
sadb_msg_satype Indicates the type of security association(s).
Security Association types are declared in the
. The current set of
Association types is enumerated later in
document
McDonald, et. al. Informational [Page 12]
RFC 2367 PF_KEY Key Management API July 1998
sadb_msg_len Contains the total length, in 64-bit words, of
data in the PF_KEY message including the base
length and additional data after the base header,
any. This length includes any padding or extra
that might exist. Unless otherwise stated, all
length fields are also measured in 64-bit words
On user to kernel messages, this field MUST
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
likely the result of the user not providing a
enough buffer for the message. In these cases,
user application SHOULD drop the message, but it
try and extract what information it can out of
message
sadb_msg_
Reserved value. It MUST be zeroed by the sender.
fields labeled reserved later in the document
the same semantics as this field
sadb_msg_seq Contains the sequence number of this message.
field, along with sadb_msg_pid, MUST be used
uniquely identify requests to a process. The
is responsible for filling in this field.
responsibility also includes matching
sadb_msg_seq of a request (e.g. SADB_ACQUIRE).
This field is similar to a transaction ID in
remote procedure call implementation
sadb_msg_pid Identifies the process which originated this message
or which process a message is bound for.
example, if process id 2112 sends an SADB_
message to the kernel, the process MUST set
field to 2112 and the kernel will set this
to 2112 in its reply to that SADB_
message. This field, along with sadb_msg_seq,
be used to uniquely identify requests to
process
It is currently assumed that a 32-bit quantity
hold an operating system's process ID space
McDonald, et. al. Informational [Page 13]
RFC 2367 PF_KEY Key Management API July 1998
2.2 Alignment of Headers and Extension
The base message header is a multiple of 64 bits and fields after
in memory will be 64 bit aligned if the base itself is 64
aligned. Some of the subsequent extension headers have 64 bit
in them, and as a consequence need to be 64 bit aligned in
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
its length in a message is a multiple of 64 bits
* All length fields are, unless otherwise specified, in units
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
padding. Implementations MUST NOT insert any extra fields,
hidden padding, into any structure in this document. This
implementations from "extending" or "enhancing" existing
without changing the extension header type. As a guard against
insertion of silent padding, each structure in this document
labeled with its size in bytes. The size of these structures in
implementation MUST match the size listed
2.3 Additional Message
The additional data following the base header consists of
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
McDonald, et. al. Informational [Page 14]
RFC 2367 PF_KEY Key Management API July 1998
sadb_ext_type The type of extension header that follows. Values
this field are detailed later. The value zero
reserved
Types of extension headers include: Association, Lifetime(s),
Address(s), Key(s), Identity(ies), Sensitivity, Proposal,
Supported. There MUST be only one instance of a extension type in
message. (e.g. Base, Key, Lifetime, Key is forbidden). An
will be returned if there are duplicate extensions within a message
Implementations MAY enforce ordering of extensions in the
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
MUST be prepared to work around other system components
processing those headers. Likewise, if an application encounters
unknown extension from the kernel, it must be prepared to work
it. Also, a kernel that generates extra extension header types
NOT _depend_ on applications also understanding extra
header types
All extension definitions include these two fields (len and exttype
because they are instances of a generic extension (not
sockaddr_in and sockaddr_in6 are instances of a generic sockaddr).
The sadb_ext header MUST NOT ever be present in a message without
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
PF_KEY implementation
2.3.1 Association
The Association extension specifies data specific to a
security association. The only times this extension is not present
when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are
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
};
McDonald, et. al. Informational [Page 15]
RFC 2367 PF_KEY Key Management API July 1998
/* sizeof(struct sadb_sa) == 16 */
sadb_sa_spi The Security Parameters Index value for the
association. Although this is a 32-bit field,
types of security associations might have an SPI
key identifier that is less than 32-bits long.
this case, the smaller value shall be stored in
least significant bits of this field and the
bits shall be zero. This field MUST be in
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
defined states are described later in this document
sadb_sa_auth The authentication algorithm to be used with
security association. The valid
algorithms are described later in this document.
value of zero means that no authentication is
for this security association
sadb_sa_encrypt The encryption algorithm to be used with
security association. The valid encryption
are described later in this document. A value of
means that no encryption is used for this
association
sadb_sa_flags A bitmap of options defined for the
association. The currently defined flags
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
header should be ignored
2.3.2 Lifetime
The Lifetime extension specifies one or more lifetime variants
this security association. If no Lifetime extension is present
association has an infinite lifetime. An association SHOULD have
lifetime of some sort associated with it. Lifetime variants come
three varieties, HARD - indicating the hard-limit expiration, SOFT -
indicating the soft-limit expiration, and CURRENT - indicating
current state of a given security association. The
McDonald, et. al. Informational [Page 16]
RFC 2367 PF_KEY Key Management API July 1998
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_
For CURRENT, the number of different connections
endpoints, or flows that the association has
allocated towards. For HARD and SOFT, the number
these the association may be allocated
before it expires. The concept of a connection
flow, or endpoint is system specific
sadb_lifetime_
For CURRENT, how many bytes have been
using this security association. For HARD and SOFT
the number of bytes that may be processed
this security association before it expires
sadb_lifetime_
For CURRENT, the time, in seconds, when
association was created. For HARD and SOFT,
number of seconds after the creation of
association until it expires
For such time fields, it is assumed that 64-bits
sufficiently large to hold the POSIX time_t value
If this assumption is wrong, this field will have
be revisited
sadb_lifetime_
For CURRENT, the time, in seconds, when
was first used. For HARD and SOFT, the number
seconds after the first use of the association
it expires
The semantics of lifetimes are inclusive-OR, first-to-expire.
means that if values for bytes and time, or multiple times,
passed in, the first of these values to be reached will cause
lifetime expiration
McDonald, et. al. Informational [Page 17]
RFC 2367 PF_KEY Key Management API July 1998
2.3.3 Address
The Address extension specifies one or more addresses that
associated with a security association. Address extensions for
source and destination MUST be present when an Association
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
the system implementing PF_KEY. If the system has an sa_len field,
SHOULD the sockaddrs in the message. If the system has NO sa_
field, the sockaddrs SHOULD NOT have an sa_len field. All non-
information in the sockaddrs, such as sin_zero for AF_INET sockaddrs
and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out.
zeroing of ports (e.g. sin_port and sin6_port) MUST be done for
messages except for originating SADB_ACQUIRE messages, which
fill them in with ports from the relevant TCP or UDP session
generates the ACQUIRE message. If the ports are non-zero, then
sadb_address_proto field, normally zero, MUST be filled in with
transport protocol's number. If the sadb_address_prefixlen is non
zero, then the address has a prefix (often used in KM access
decisions), with length specified in sadb_address_prefixlen.
additional fields may be useful to KM applications
The SRC and DST addresses for a security association MUST be in
same protocol family and MUST always be present or absent together
a message. The PROXY address MAY be in a different protocol family
and for most security protocols, represents an actual originator of
packet. (For example, the inner-packets's source address in
tunnel.)
The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY
address. The DST address can be any valid destination
(unicast, multicast, or even broadcast). The PROXY address SHOULD
a unicast address (there are experimental security protocols
PROXY semantics may be different than described above).
McDonald, et. al. Informational [Page 18]
RFC 2367 PF_KEY Key Management API July 1998
2.3.4 Key
The Key extension specifies one or more keys that are associated
a security association. A Key extension will not always be
with messages, because of security risks. The format of a
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
zero in sadb_key_bits MUST cause an error
The key extension comes in two varieties. The AUTH version is
with authentication keys (e.g. IPsec AH, OSPF MD5) and the
version is used with encryption keys (e.g. IPsec ESP). PF_KEY
only with fully formed cryptographic keys, not with "raw
material". For example, when ISAKMP/Oakley is in use, the
management daemon is always responsible for transforming the
of the Diffie-Hellman computation into distinct fully formed
PRIOR to sending those keys into the kernel via PF_KEY. This rule
made because PF_KEY is designed to support multiple
protocols (not just IP Security) and also multiple key
schemes including manual keying, which does not have the concept
"raw key material". A clean, protocol-independent interface
important for portability to different operating systems as well
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-
quantity
When a particular security protocol only requires one
and/or one encryption key, the fully formed key is transmitted
the appropriate key extension. When a particular security
requires more than one key for the same function (e.g. Triple-
using 2 or 3 keys, and asymmetric algorithms), then those two
formed keys MUST be concatenated together in the order used
outbound packet processing. In the case of multiple keys,
algorithm MUST be able to determine the lengths of the
McDonald, et. al. Informational [Page 19]
RFC 2367 PF_KEY Key Management API July 1998
keys based on the information provided. The total key length (
combined with knowledge of the algorithm in use) usually
sufficient information to make this determination
Keys are always passed through the PF_KEY interface in the order
they are used for outbound packet processing. For inbound processing
the correct order that keys are used might be different from
canonical concatenation order used with the PF_KEY interface. It
the responsibility of the implementation to use the keys in
correct order for both inbound and outbound processing
For example, consider a pair of nodes communicating unicast using
ESP three-key Triple-DES Security Association. Both the outbound
on the sender node, and the inbound SA on the receiver node
contain key-A, followed by key-B, followed by key-C in
respective ENCRYPT key extensions. The outbound SA will use key-
first, followed by key-B, then key-C when encrypting. The inbound
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,
should be documented. The order of "encryption" is the
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
significant two bits not containing key material. Five
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
regarding odd-digit hexadecimal representation of keys. Consider
example of the 16-bit number
0x123
That will require two octets of storage. In the absence of
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)
the better way to interpret this ambiguity. Extra information (
example, specifying 0x0123 or 0x1230, or specifying that this is
a twelve-bit number) would solve this problem
McDonald, et. al. Informational [Page 20]
RFC 2367 PF_KEY Key Management API July 1998
2.3.5 Identity
The Identity extension contains endpoint identities.
information is used by key management to select the
certificate that is used in negotiations. This information may
be provided by a kernel to network security aware applications
identify the remote entity, possibly for access control purposes.
this extension is not present, key management MUST assume that
addresses in the Address extension are the only identities for
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
in this document
sadb_ident_id An identifier used to aid in the construction of
identity string if none is present. A POSIX user
value is one such identifier that will be used in
field. Use of this field is described later in
document
A C string containing a textual representation of the
information optionally follows the sadb_ident extension. The
of this string is determined by the value in sadb_ident_type, and
described later in this document
2.3.6 Sensitivity
The Sensitivity extension contains security labeling information
a security association. If this extension is not present,
sensitivity-related data can be obtained from this
association. If this extension is present, then the need
explicit security labeling on the packet is obviated
struct sadb_sens {
uint16_t sadb_sens_len
uint16_t sadb_sens_exttype
McDonald, et. al. Informational [Page 21]
RFC 2367 PF_KEY Key Management API July 1998
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
interpretation of the levels and
bitmaps
sadb_sens_sens_
The sensitivity level
sadb_sens_sens_
The length, in 64 bit words, of the
bitmap
sadb_sens_integ_
The integrity level
sadb_sens_integ_
The length, in 64 bit words, of the
bitmap
This sensitivity extension is designed to support the Bell-
[BL74] security model used in compartmented-mode or multi-
secure systems, the Clark-Wilson [CW87] commercial security model
and/or the Biba integrity model [Biba77]. These formal models can
used to implement a wide variety of security policies. The
of a particular security policy is outside the scope of
document. Each of the bitmaps MUST be padded to a 64-bit boundary
they are not implicitly 64-bit aligned
2.3.7 Proposal
The Proposal extension contains a "proposed situation" of
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 */
McDonald, et. al. Informational [Page 22]
RFC 2367 PF_KEY Key Management API July 1998
/* 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
preferential order. The values in these fields have the
definition as the fields those values will move into if
combination is chosen
NOTE: Some algorithms in some security protocols will
variable IV lengths per algorithm. Variable length
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
value of sadb_sa_auth
sadb_comb_
If this combination is accepted, this will be
value of sadb_sa_encrypt
McDonald, et. al. Informational [Page 23]
RFC 2367 PF_KEY Key Management API July 1998
sadb_comb_auth_minbits
sadb_comb_auth_maxbits
The minimum and maximum acceptable
key lengths, respectably, in bits. If sadb_comb_
is zero, both of these values MUST be zero.
sadb_comb_auth is nonzero, both of these values
be nonzero. If this combination is accepted, a
between these (inclusive) will be stored in
sadb_key_bits field of KEY_AUTH. The minimum
NOT be greater than the maximum
sadb_comb_encrypt_minbits
sadb_comb_encrypt_maxbits
The minimum and maximum acceptable encryption
lengths, respectably, in bits. If sadb_comb_
is zero, both of these values MUST be zero.
sadb_comb_encrypt is nonzero, both of these
MUST be nonzero. If this combination is accepted,
value between these (inclusive) will be stored
the sadb_key_bits field of KEY_ENCRYPT. The
MUST NOT be greater than the maximum
sadb_comb_soft_
sadb_comb_hard_
If this combination is accepted, these are
values of sadb_lifetime_allocations in the SOFT
HARD lifetimes, respectively
sadb_comb_soft_
sadb_comb_hard_
If this combination is accepted, these are
values of sadb_lifetime_bytes in the SOFT and
lifetimes, respectively
sadb_comb_soft_
sadb_comb_hard_
If this combination is accepted, these are
values of sadb_lifetime_addtime in the SOFT and
lifetimes, respectively
sadb_comb_soft_
sadb_comb_hard_
If this combination is accepted, these are
values of sadb_lifetime_usetime in the SOFT and
lifetimes, respectively
McDonald, et. al. Informational [Page 24]
RFC 2367 PF_KEY Key Management API July 1998
Each combination has an authentication and encryption algorithm
which may be 0, indicating none. A combination's flags are the
as the flags in the Association extension. The minimum and
key lengths (which are in bits) are derived from possible a
policy decisions, along with basic properties of the algorithm
Lifetime attributes are also included in a combination, as
algorithms may know something about their lifetimes and can
lifetime limits
2.3.8 Supported Algorithms
The Supported Algorithms extension contains a list of all
supported by the system. This tells key management what algorithms
can negotiate. Available authentication algorithms are listed in
SUPPORTED_AUTH extension and available encryption algorithms
listed in the SUPPORTED_ENCRYPT extension. The format of
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.
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
algorithm. This is the value that is stored
sadb_sa_auth or sadb_sa_encrypt if this algorithm
selected
McDonald, et. al. Informational [Page 25]
RFC 2367 PF_KEY Key Management API July 1998
sadb_alg_ivlen The length of the initialization vector to be
for the algorithm. If an IV is not needed,
value MUST be set to zero
sadb_alg_
The minimum acceptable key length, in bits. A
of zero is invalid
sadb_alg_
The maximum acceptable key length, in bits. A
of zero is invalid. The minimum MUST NOT be
than the maximum
2.3.9 SPI Range
One PF_KEY message, SADB_GETSPI, might need a range of acceptable
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_
The minimum acceptable SPI value
sadb_spirange_
The maximum acceptable SPI value. The maximum
be greater than or equal to the minimum
McDonald, et. al. Informational [Page 26]
RFC 2367 PF_KEY Key Management API July 1998
2.4 Illustration of Message
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
extension fields, depending on the values of various base
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
where an extension MUST be repeated, it should be brought to
attention of the authors
The Association
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
+---------------+---------------+---------------+---------------+
| sadb_lifetime_len | sadb_lifetime_exttype |
+---------------+---------------+---------------+---------------+
| sadb_lifetime_allocations |
+---------------+---------------+---------------+---------------+
McDonald, et. al. Informational [Page 27]
RFC 2367 PF_KEY Key Management API July 1998
+---------------+---------------+---------------+---------------+
| sadb_lifetime_bytes |
| (64 bits) |
+---------------+---------------+---------------+---------------+
| sadb_lifetime_addtime |
| (64 bits) |
+---------------+---------------+---------------+---------------+
| sadb_lifetime_usetime |
| (64 bits) |
+---------------+---------------+---------------+---------------+
The Address
+---------------+---------------+---------------+---------------+
| sadb_address_len | sadb_address_exttype |
+---------------+---------------+---------------+---------------+
| _address_proto| ..._prefixlen | sadb_address_reserved |
+---------------+---------------+---------------+---------------+
> Some form of 64-bit aligned struct sockaddr goes here. <
+---------------+---------------+---------------+---------------+
The Key
+---------------+---------------+---------------+---------------+
| 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
+---------------+---------------+---------------+---------------+
| 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. <
+---------------+---------------+---------------+---------------+
McDonald, et. al. Informational [Page 28]
RFC 2367 PF_KEY Key Management API July 1998
The Sensitivity
+---------------+---------------+---------------+---------------+
| 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
+---------------+---------------+---------------+---------------+
| sadb_prop_len | sadb_prop_exttype |
+---------------+---------------+---------------+---------------+
|...prop_replay | sadb_prop_reserved |
+---------------+---------------+---------------+---------------+
> One or more combinations, specified as follows... <
+---------------+---------------+---------------+---------------+
+---------------+---------------+---------------+---------------+
|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) |
+---------------+---------------+---------------+---------------+
McDonald, et. al. Informational 