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 message improprieties, including SPI ranges
that are malformed.
ENOMEM Needed memory was not available.
ENOBUFS Needed memory was not available.
EMSGSIZ The message exceeds the maximum length allowed.
3.1.1 SADB_GETSPI
The SADB_GETSPI message allows a process to obtain a unique SPI value
for given security association type, source address, and destination
address. This message followed by an SADB_UPDATE is one way to
create a security association (SADB_ADD is the other method). The
process specifies the type in the base header, the source and
destination address in address extension. If the SADB_GETSPI message
is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq
MUST be the same as the SADB_ACQUIRE message. The application may
also specify the SPI. This is done by having the kernel select
within a range of SPI values by using the SPI range extension. To
specify a single SPI value to be verified, the application sets the
high and low values to be equal. Permitting range specification is
important because the kernel can allocate an SPI value based on what
it knows about SPI values already in use. The kernel returns the
same message with the allocated SPI value stored in the spi field of
an association extension. The allocate SPI (and destination address)
refer to a LARVAL security association. An SADB_UPDATE message can
later be used to add an entry with the requested SPI value.
It is recommended that associations that are created with SADB_GETSPI
SHOULD be automatically deleted within a fixed amount of time if they
are not updated by an SADB_UPDATE message. This allows SA storage
not to get cluttered with larval associations.
The message behavior of the SADB_GETSPI message is:
Send an SADB_GETSPI message from a user process to the kernel.
<base, address, SPI range>
The kernel returns the SADB_GETSPI message to all listening
processes.
<base, SA(*), address(SD)>
Errors:
EEXIST Requested SPI or SPI range is not available or already
used.
3.1.2 SADB_UPDATE Message
The SADB_UPDATE message allows a process to update the information in
an existing Security Association. Since SADB_GETSPI does not allow
setting of certain parameters, this message is needed to fully form
the SADB_SASTATE_LARVAL security association created with
SADB_GETSPI. The format of the update message is a base header,
followed by an association header and possibly by several extension
headers. The kernel searches for the security association with the
same type, spi, source address and destination address specified in
the message and updates the Security Association information using
the content of the SADB_UPDATE message.
The kernel MAY disallow SADB_UPDATE to succeed unless the message is
issued from the same socket that created the security association.
Such enforcement significantly reduces the chance of accidental
changes to an in-use security association. Malicious trusted parties
could still issue an SADB_FLUSH or SADB_DELETE message, but deletion
of associations is more easily detected and less likely to occur
accidentally than an erroneous SADB_UPDATE. The counter argument to
supporting this behavior involves the case where a user-space key
management application fails and is restarted. The new instance of
the application will not have the same socket as the creator of the
security association.
The kernel MUST sanity check all significant values submitted in an
SADB_UPDATE message before changing the SA in its database and MUST
return EINVAL if any of the values are invalid. Examples of checks
that should be performed are DES key parity bits, key length
checking, checks for keys known to be weak for the specified
algorithm, and checks for flags or parameters known to be
incompatible with the specified algorithm.
Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_UPDATE
message. If the original SA is an SADB_SASTATE_LARVAL SA, then any
value in the SA may be changed except for the source address,
destination address, and SPI. If the original SA is an
SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA
MUST return EINVAL. It is not valid for established keying or
algorithm information to change without the SPI changing, which would
require creation of a new SA rather than a change to an existing SA.
Once keying and algorithm information is negotiated, address and
identity information is fixed for the SA. Therefore, if the original
SA is an SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state
field in the SA header and lifetimes (hard, soft, and current) may be
changed and any attempt to change other values MUST result in an
error return of EINVAL.
The message behavior of the SADB_UPDATE message is:
Send an SADB_UPDATE message from a user process to the kernel.
<base, SA, (lifetime(HSC),) address(SD), (address(P),)
key(AE), (identity(SD),) (sensitivity)>
The kernel returns the SADB_UPDATE message to all listening
processes.
<base, SA, (lifetime(HSC),) address(SD), (address(P),)
(identity(SD),) (sensitivity)>
The keying material is not returned on the message from the kernel to
listening sockets because listeners might not have the privileges to
see such keying material.
Errors:
ESRCH The security association to be updated was not found.
EINVAL In addition to other possible causes, this error is
returned if sanity checking on the SA values (such
as the keys) fails.
EACCES Insufficient privilege to update entry. The socket
issuing the SADB_UPDATE is not creator of the entry
to be updated.
3.1.3 SADB_ADD
The SADB_ADD message is nearly identical to the SADB_UPDATE message,
except that it does not require a previous call to SADB_GETSPI. The
SADB_ADD message is used in manual keying applications, and in other
cases where the uniqueness of the SPI is known immediately.
An SADB_ADD message is also used when negotiation is finished, and
the second of a pair of associations is added. The SPI for this
association was determined by the peer machine. The sadb_msg_seq
MUST be set to the value set in a kernel-generated SADB_ACQUIRE so
that both associations in a pair are bound to the same ACQUIRE
request.
The kernel MUST sanity check all used fields in the SA submitted in
an SADB_ADD message before adding the SA to its database and MUST
return EINVAL if any of the values are invalid.
Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_ADD message.
SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is not
sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state.
Therefore, the sadb_sa_state field of all submitted SAs MUST be
SADB_SASTATE_MATURE and the kernel MUST return an error if this is
not true.
The message behavior of the SADB_ADD message is:
Send an SADB_ADD message from a user process to the kernel.
<base, SA, (lifetime(HS),) address(SD), (address(P),)
key(AE), (identity(SD),) (sensitivity)>
The kernel returns the SADB_ADD message to all listening
processes.
<base, SA, (lifetime(HS),) address(SD), (identity(SD),)
(sensitivity)>
The keying material is not returned on the message from the kernel to
listening sockets because listeners may not have the privileges to
see such keying material.
Errors:
EEXIST The security association that was to be added already
exists.
EINVAL In addition to other possible causes, this error is
returned if sanity checking on the SA values (such
as the keys) fails.
3.1.4 SADB_DELETE
The SADB_DELETE message causes the kernel to delete a Security
Association from the key table. The delete message consists of the
base header followed by the association, and the source and
destination sockaddrs in the address extension. The kernel deletes
the security association matching the type, spi, source address, and
destination address in the message.
The message behavior for SADB_DELETE is as follows:
Send an SADB_DELETE message from a user process to the kernel.
<base, SA(*), address(SD)>
The kernel returns the SADB_DELETE message to all listening
processes.
<base, SA(*), address(SD)>
3.1.5 SADB_GET
The SADB_GET message allows a process to retrieve a copy of a
Security Association from the kernel's key table. The get message
consists of the base header follows by the relevant extension fields.
The Security Association matching the type, spi, source address, and
destination address is returned.
The message behavior of the SADB_GET message is:
Send an SADB_GET message from a user process to the kernel.
<base, SA(*), address(SD)>
The kernel returns the SADB_GET message to the socket that sent
the SADB_GET message.
<base, SA, (lifetime(HSC),) address(SD), (address(P),) key(AE),
(identity(SD),) (sensitivity)>
Errors:
ESRCH The sought security association was not found.
3.1.6 SADB_ACQUIRE
The SADB_ACQUIRE message is typically sent only by the kernel to key
socket listeners who have registered their key socket (see
SADB_REGISTER message). SADB_ACQUIRE messages can be sent by
application-level consumers of security associations (such as an
OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE
message is a base header along with an address extension, possibly an
identity extension, and a proposal extension. The proposed situation
contains a list of desirable algorithms that can be used if the
algorithms in the base header are not available. The values for the
fields in the base header and in the security association data which
follows the base header indicate the properties of the Security
Association that the listening process should attempt to acquire. If
the message originates from the kernel (i.e. the sadb_msg_pid is 0),
the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and
SADB_UPDATE, or subsequent SADB_ADD message to bind a security
association to the request. This avoids the race condition of two
TCP connections between two IP hosts that each require unique
associations, and having one steal another's security association.
The sadb_msg_errno and sadb_msg_state fields should be ignored by the
listening process.
The SADB_ACQUIRE message is typically triggered by an outbound packet
that needs security but for which there is no applicable Security
Association existing in the key table. If the packet can be
sufficiently protected by more than one algorithm or combination of
options, the SADB_ACQUIRE message MUST order the preference of
possibilities in the Proposal extension.
There are three messaging behaviors for SADB_ACQUIRE. The first is
where the kernel needs a security association (e.g. for IPsec).
The kernel sends an SADB_ACQUIRE message to registered sockets.
<base, address(SD), (address(P)), (identity(SD),) (sensitivity,)
proposal>
NOTE: The address(SD) extensions MUST have the port fields
filled in with the port numbers of the session requiring
keys if appropriate.
The second is when, for some reason, key management fails, it can
send an ACQUIRE message with the same sadb_msg_seq as the initial
ACQUIRE with a non-zero errno.
Send an SADB_ACQUIRE to indicate key management failure.
<base>
The third is where an application-layer consumer of security
associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security
association.
Send an SADB_ACQUIRE message from a user process to the kernel.
<base, address(SD), (address(P),) (identity(SD),) (sensitivity,)
proposal>
The kernel returns an SADB_ACQUIRE message to registered
sockets.
<base, address(SD), (address(P),) (identity(SD),) (sensitivity,)
proposal>
The user-level consumer waits for an SADB_UPDATE or SADB_ADD
message for its particular type, and then can use that
association by using SADB_GET messages.
Errors:
EINVAL Invalid acquire request.
EPROTONOSUPPORT No KM application has registered with the Key
Engine as being able to obtain the requested SA type, so
the requested SA cannot be acquired.
3.1.7 SADB_REGISTER
The SADB_REGISTER message allows an application to register its key
socket as able to acquire new security associations for the kernel.
SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for
the type of security association specified in sadb_msg_satype. The
application specifies the type of security association that it can
acquire for the kernel in the type field of its register message. If
an application can acquire multiple types of security association, it
MUST register each type in a separate message. Only the base header
is needed for the register message. Key management applications MAY
register for a type not known to the kernel, because the consumer may
be in user-space (e.g. OSPFv2 security).
The reply of the SADB_REGISTER message contains a supported algorithm
extension. That field contains an array of supported algorithms, one
per octet. This allows key management applications to know what
algorithm are supported by the kernel.
In an environment where algorithms can be dynamically loaded and
unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The
list of supported algorithms MUST be a complete list, so the
application can make note of omissions or additions.
The messaging behavior of the SADB_REGISTER message is:
Send an SADB_REGISTER message from a user process to the kernel.
<base>
The kernel returns an SADB_REGISTER message to registered
sockets, with algorithm types supported by the kernel being
indicated in the supported algorithms field.
NOTE: This message may arrive asynchronously due to an
algorithm being loaded or unloaded into a dynamically
linked kernel.
<base, supported>
3.1.8 SADB_EXPIRE Message
The operating system kernel is responsible for tracking SA
expirations for security protocols that are implemented inside the
kernel. If the soft limit or hard limit of a Security Association
has expired for a security protocol implemented inside the kernel,
then the kernel MUST issue an SADB_EXPIRE message to all key socket
listeners. If the soft limit or hard limit of a Security Association
for a user-level security protocol has expired, the user-level
protocol SHOULD issue an SADB_EXPIRE message.
The base header will contain the security association information
followed by the source sockaddr, destination sockaddr, (and, if
present, internal sockaddr,) (and, if present, one or both
compartment bitmaps).
The lifetime extension of an SADB_EXPIRE message is important to
indicate which lifetime expired. If a HARD lifetime extension is
included, it indicates that the HARD lifetime expired. This means
the association MAY be deleted already from the SADB. If a SOFT
lifetime extension is included, it indicates that the SOFT lifetime
expired. The CURRENT lifetime extension will indicate the current
status, and comparisons to the HARD or SOFT lifetime will indicate
which limit was reached. HARD lifetimes MUST take precedence over
SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same,
the HARD lifetime will appear on the EXPIRE message. The
pathological case of HARD lifetimes being shorter than SOFT lifetimes
is handled such that the SOFT lifetime will never expire.
The messaging behavior of the SADB_EXPIRE message is:
The kernel sends an SADB_EXPIRE message to all listeners when
the soft limit of a security association has been expired.
<base, SA, lifetime(C and one of HS), address(SD)>
Note that the SADB_EXPIRE message is ONLY sent by the kernel to the
KMd. It is a one-way informational message that does not have a
reply.
3.1.9 SADB_FLUSH
The SADB_FLUSH message causes the kernel to delete all entries in its
key table for a certain sadb_msg_satype. Only the base header is
required for a flush message. If sadb_msg_satype is filled in with a
specific value, only associations of that type are deleted. If it is
filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted.
The messaging behavior for SADB_FLUSH is:
Send an SADB_FLUSH message from a user process to the kernel.
<base>
The kernel will return an SADB_FLUSH message to all listening
sockets.
<base>
The reply message happens only after the actual flushing
of security associations has been attempted.
3.1.10 SADB_DUMP
The SADB_DUMP message causes the kernel to dump the operating
system's entire Key Table to the requesting key socket. As in
SADB_FLUSH, if a sadb_msg_satype value is in the message, only
associations of that type will be dumped. If SADB_SATYPE_UNSPEC is
specified, all associations will be dumped. Each Security Association
is returned in its own SADB_DUMP message. A SADB_DUMP message with a
sadb_seq field of zero indicates the end of the dump transaction. The
dump message is used for debugging purposes only and is not intended
for production use.
Support for the dump message MAY be discontinued in future versions
of PF_KEY. Key management applications MUST NOT depend on this
message for basic operation.
The messaging behavior for SADB_DUMP is:
Send an SADB_DUMP message from a user process to the kernel.
<base>
Several SADB_DUMP messages will return from the kernel to the
sending socket.
<base, SA, (lifetime (HSC),) address(SD), (address(P),)
key(AE), (identity(SD),) (sensitivity)>
3.2 Security Association Flags
The Security Association's flags are a bitmask field. These flags
also appear in a combination that is part of a PROPOSAL extension.
The related symbolic definitions below should be used in order that
applications will be portable:
#define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */
The SADB_SAFLAGS_PFS flag indicates to key management that this
association should have perfect forward secrecy in its key. (In
other words, any given session key cannot be determined by
cryptanalysis of previous session keys or some master key.)
3.3 Security Association States
The security association state field is an integer that describes the
states of a security association. They are:
#define SADB_SASTATE_LARVAL 0
#define SADB_SASTATE_MATURE 1
#define SADB_SASTATE_DYING 2
#define SADB_SASTATE_DEAD 3
#define SADB_SASTATE_MAX 3
A SADB_SASTATE_LARVAL security association is one that was created by
the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one
that was updated with the SADB_UPDATE message or added with the
SADB_ADD message. A DYING association is one whose soft lifetime has
expired. A SADB_SASTATE_DEAD association is one whose hard lifetime
has expired, but hasn't been reaped by system garbage collection. If
a consumer of security associations has to extend an association
beyond its normal lifetime (e.g. OSPF Security) it MUST only set the
soft lifetime for an association.
3.4 Security Association Types
This defines the type of Security Association in this message. The
symbolic names are always the same, even on different
implementations. Applications SHOULD use the symbolic name in order
to have maximum portability across different implementations. These
are defined in the file <net/pfkeyv2.h>.
#define SADB_SATYPE_UNSPEC 0
#define SADB_SATYPE_AH 2 /* RFC-1826 */
#define SADB_SATYPE_ESP 3 /* RFC-1827 */
#define SADB_SATYPE_RSVP 5 /* RSVP Authentication */
#define SADB_SATYPE_OSPFV2 6 /* OSPFv2 Authentication */
#define SADB_SATYPE_RIPV2 7 /* RIPv2 Authentication */
#define SADB_SATYPE_MIP 8 /* Mobile IP Auth. */
#define SADB_SATYPE_MAX 8
SADB_SATYPE_UNSPEC is defined for completeness and means no specific
type of security association. This type is never used with PF_KEY
SAs.
SADB_SATYPE_AH is for the IP Authentication Header [Atk95b].
SADB_SATYPE_ESP is for the IP Encapsulating Security Payload
[Atk95c].
SADB_SATYPE_RSVP is for the RSVP Integrity Object.
SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication
[Moy98].
SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97].
SADB_SATYPE_MIP is for Mobile IP's authentication extensions [Per97].
SADB_SATYPE_MAX is always set to the highest valid numeric value.
3.5 Algorithm Types
The algorithm type is interpreted in the context of the Security
Association type defined above. The numeric value might vary between
implementations, but the symbolic name MUST NOT vary between
implementations. Applications should use the symbolic name in order
to have maximum portability to various implementations.
Some of the algorithm types defined below might not be standardized
or might be deprecated in the future. To obtain an assignment for a
symbolic name, contact the authors.
The symbols below are defined in <net/pfkeyv2.h>.
/* Authentication algorithms */
#define SADB_AALG_NONE 0
#define SADB_AALG_MD5HMAC 2
#define SADB_AALG_SHA1HMAC 3
#define SADB_AALG_MAX 3
/* Encryption algorithms */
#define SADB_EALG_NONE 0
#define SADB_EALG_DESCBC 2
#define SADB_EALG_3DESCBC 3
#define SADB_EALG_NULL 11
#define SADB_EALG_MAX 11
The algorithm for SADB_AALG_MD5_HMAC is defined in [MG98a]. The
algorithm for SADB_AALG_SHA1HMAC is defined in [MG98b]. The
algorithm for SADB_EALG_DESCBC is defined in [MD98]. SADB_EALG_NULL
is the NULL encryption algorithm, defined in [GK98]. The
SADB_EALG_NONE value is not to be used in any security association
except those which have no possible encryption algorithm in them
(e.g. IPsec AH).
3.6 Extension Header Values
To briefly recap the extension header values:
#define SADB_EXT_RESERVED 0
#define SADB_EXT_SA 1
#define SADB_EXT_LIFETIME_CURRENT 2
#define SADB_EXT_LIFETIME_HARD 3
#define SADB_EXT_LIFETIME_SOFT 4
#define SADB_EXT_ADDRESS_SRC 5
#define SADB_EXT_ADDRESS_DST 6
#define SADB_EXT_ADDRESS_PROXY 7
#define SADB_EXT_KEY_AUTH 8
#define SADB_EXT_KEY_ENCRYPT 9
#define SADB_EXT_IDENTITY_SRC 10
#define SADB_EXT_IDENTITY_DST 11
#define SADB_EXT_SENSITIVITY 12
#define SADB_EXT_PROPOSAL 13
#define SADB_EXT_SUPPORTED_AUTH 14
#define SADB_EXT_SUPPORTED_ENCRYPT 15
#define SADB_EXT_SPIRANGE 16
#define SADB_EXT_MAX 16
3.7 Identity Extension Values
Each identity can have a certain type.
#define SADB_IDENTTYPE_RESERVED 0
#define SADB_IDENTTYPE_PREFIX 1
#define SADB_IDENTTYPE_FQDN 2
#define SADB_IDENTTYPE_USERFQDN 3
#define SADB_IDENTTYPE_MAX 3
The PREFIX identity string consists of a network address followed by a
forward slash and a prefix length. The network address is in a
printable numeric form appropriate for the protocol family. The
prefix length is a decimal number greater than or equal to zero and
less than the number of bits in the network address. It indicates the
number of bits in the network address that are significant; all bits
in the network address that are not significant MUST be set to zero.
Note that implementations MUST parse the contents of the printable
address into a binary form for comparison purposes because multiple
printable strings are valid representations of the same address in
many protocol families (for example, some allow leading zeros and some
have letters that are case insensitive). Examples of PREFIX identities
are "199.33.248.64/27" and "3ffe::1/128". If the source or destination
identity is a PREFIX identity, the source or destination address for
the SA (respectively) MUST be within that prefix. The sadb_ident_id
field is zeroed for these identity types.
The FQDN identity string contains a fully qualified domain name. An
example FQDN identity is "ministry-of-truth.inner.net". The
sadb_ident_id field is zeroed for these identity types.
The UserFQDN identity consists of a text string in the format commonly
used for Internet-standard electronic mail. The syntax is the text
username, followed by the "@" character, followed in turn by the
appropriate fully qualified domain name. This identity specifies both
a username and an associated FQDN. There is no requirement that this
string specify a mailbox valid for SMTP or other electronic mail
use. This identity is useful with protocols supporting user-oriented
keying. It is a convenient identity form because the DNS Security
extensions can be used to distribute signed public key values by
associating KEY and SIG records with an appropriate MB DNS record. An
example UserFQDN identity is "julia@ministry-of-love.inner.net". The
sadb_ident_id field is used to contain a POSIX user id in the absence
of an identity string itself so that a user-level application can use
the getpwuid{,_r}() routine to obtain a textual user login id. If a
string is present, it SHOULD match the numeric value in the
sadb_ident_id field. If it does not match, the string SHOULD override
the numeric value.
3.8 Sensitivity Extension Values
The only field currently defined in the sensitivity extension is the
sadb_sens_dpd, which represents the data protection domain. The other
data in the sensitivity extension is based off the sadb_sens_dpd
value.
The DP/DOI is defined to be the same as the "Labeled Domain Identifier
Value" of the IP Security DOI specification [Pip98]. As noted in that
specification, values in the range 0x80000000 to 0xffffffff
(inclusive) are reserved for private use and values in the range
0x00000001 through 0x7fffffff are assigned by IANA. The all-zeros
DP/DOI value is permanently reserved to mean that "no DP/DOI is in
use".
3.9 Proposal Extension Values
These are already mentioned in the Algorithm Types and Security
Association Flags sections.
4 Future Directions
While the current specification for the Sensitivity and Integrity
Labels is believed to be general enough, if a case should arise that
can't work with the current specification then this might cause a
change in a future version of PF_KEY.
Similarly, PF_KEY might need extensions to work with other kinds of
Security Associations in future. It is strongly desirable for such
extensions to be made in a backwards-compatible manner should they be
needed.
When more experience is gained with certificate management, it is
possible that the IDENTITY extension will have to be revisited to
allow a finer grained selection of certificate identities.
5. Examples
The following examples illustrate how PF_KEY is used. The first
example is an IP Security example, where the consumer of the security
associations is inside an operating system kernel. The second example
is an OSPF Security example, which illustrates a user-level consumer
of security associations. The third example covers things not
mentioned by the first two examples. A real system may closely
conform to one of these examples, or take parts of them. These
examples are purely illustrative, and are not intended to mandate a
particular implementation method.
5.1 Simple IP Security Example
+---------------+ +-------------+
|Key Mgmt Daemon| | Application |
+---------------+ +-------------+
| | /
| | /
| | | Applications
======[PF_KEY]====[PF_INET]==========================
| | | OS Kernel
+------------+ +-----------------+
| Key Engine | | TCP/IP, |
| or SADB |---| including IPsec |
+------------+ | |
+-----------------+
When the Key Management daemon (KMd) begins. It must tell PF_KEY
that it is willing to accept message for the two IPsec services, AH
and ESP. It does this by sending down two SADB_REGISTER messages.
KMd->Kernel: SADB_REGISTER for ESP
Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms
KMd->Kernel: SADB_REGISTER for AH
Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms
Each REGISTER message will cause a reply to go to all PF_KEY sockets
registered for ESP and AH respectively (including the requester).
Assume that no security associations currently exist for IPsec to
use. Consider when a network application begins transmitting data
(e.g. a TCP SYN). Because of policy, or the application's request,
the kernel IPsec module needs an AH security association for this
data. Since there is not one present, the following message is
generated:
Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens,
proposals
The KMd reads the ACQUIRE message, especially the sadb_msg_seq
number. Before it begins the negotiation, it sends down an
SADB_GETSPI message with the sadb_msg_seq number equal to the one
received in the ACQUIRE. The kernel returns the results of the
GETSPI to all listening sockets.
KMd->Kernel: SADB_GETSPI for AH, addr, SPI range
Kernel->All: SADB_GETSPI for AH, assoc, addrs
The KMd may perform a second GETSPI operation if it needs both
directions of IPsec SPI values. Now that the KMd has an SPI for at
least one of the security associations, it begins negotiation. After
deriving keying material, and negotiating other parameters, it sends
down one (or more) SADB_UPDATE messages with the same value in
sadb_msg_seq.
If a KMd has any error at all during its negotiation, it can send
down:
KMd->Kernel: SADB_ACQUIRE for AH, assoc (with an error)
Kernel->All: SADB_ACQUIRE for AH, assoc (same error)
but if it succeeds, it can instead:
KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys,
<etc.>
Kernel->All: SADB_UPDATE for AH, assoc, addrs, <etc.>
The results of the UPDATE (minus the actual keys) are sent to all
listening sockets. If only one SPI value was determined locally, the
other SPI (since IPsec SAs are unidirectional) must be added with an
SADB_ADD message.
KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, <etc.>
Kernel->All: SADB_ADD for AH, assoc, addrs, <etc.>
If one of the extensions passed down was a Lifetime extension, it is
possible at some point an SADB_EXPIRE message will arrive when one of
the lifetimes has expired.
Kernel->All: SADB_EXPIRE for AH, assoc, addrs,
Hard or Soft, Current, <etc.>
The KMd can use this as a clue to begin negotiation, or, if it has
some say in policy, send an SADB_UPDATE down with a lifetime
extension.
5.2 Proxy IP Security Example
Many people are interested in using IP Security in a "proxy" or
"firewall" configuration in which an intermediate system provides
security services for "inside" hosts. In these environments, the
intermediate systems can use PF_KEY to communicate with key
management applications almost exactly as they would if they were the
actual endpoints. The messaging behavior of PF_KEY in these cases is
exactly the same as the previous example, but the address information
is slightly different.
Consider this case:
A ========= B --------- C
Key:
A "outside" host that implements IPsec
B "firewall" that implements IPsec
C "inside" host that does not implement IPsec
=== IP_{A<->B} ESP [ IP_{A<->C} ULP ]
--- IP_{A<->C} ULP
A is a single system that wishes to communicate with the "inside"
system C. B is a "firewall" between C and the outside world that
will do ESP and tunneling on C's behalf. A discovers that it needs
to send traffic to C via B through methods not described here (Use of
the DNS' KX record might be one method for discovering this).
For packets that flow from left to right, A and B need an IPsec
Security Association with:
SA type of ESP tunnel-mode
Source Identity that dominates A (e.g. A's address)
Destination Identity that dominates B (e.g. B's address)
Source Address of A
Destination Address of B
For packets to flow from right to left, A and B need an IPsec
Security Association with:
SA type of ESP tunnel-mode
Source Identity that dominates C
Destination Identity that dominates A
Source Address of B
Destination Address of A
Proxy Address of C
For this second SA (for packets flowing from C towards A), node A
MUST verify that the inner source address is dominated by the Source
Identity for the SA used with those packets. If node A does not do
this, an adversary could forge packets with an arbitrary Source
Identity and defeat the packet origin protections provided by IPsec.
Now consider a slightly more complex case:
A_1 --| |-- D_1
|--- B ====== C ---|
A_2 --| |-- D_2
Key:
A_n "inside" host on net 1 that does not do IPsec.
B "firewall" for net 1 that supports IPsec.
C "firewall" for net 2 that supports IPsec.
D_n "inside" host on net 2 that does not do IPsec.
=== IP_{B<->C} ESP [ IP_{A<->C} ULP ]
--- IP_{A<->C} ULP
For A_1 to send a packet to D_1, B and C need an SA with:
SA Type of ESP
Source Identity that dominates A_1
Destination Identity that dominates C
Source Address of B
Destination Address of C
Proxy Address of A_1
For D_1 to send a packet to A_1, C and B need an SA with:
SA Type of ESP Tunnel-mode
Source Identity that dominates D_1
Destination Identity that dominates B
Source Address of C
Destination Address of B
Proxy Address of D_1
Note that A_2 and D_2 could be substituted for A_1 and D_1
(respectively) here; the association of an SA with a particular pair
of ends or group of those pairs is a policy decision on B and/or C
and not necessarily a function of key management. The same check of
the Source Identity against the inner source IP address MUST also be
performed in this case for the same reason.
For a more detailed discussion of the use of IP Security in complex
cases, please see [Atk97].
NOTE: The notion of identity domination might be unfamiliar. Let H
represent some node. Let Hn represent H's fully qualified domain
name. Let Ha represent the IP address of H. Let Hs represent the IP
subnet containing Ha. Let Hd represent a fully qualified domain
name that is a parent of the fully qualified domain name of H. Let
M be a UserFQDN identity that whose right-hand part is Hn or Ha.
Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the
example above. Hs dominates any node having an IP address within
the IP address range represented by Hs. Hd dominates any node
having a fully qualified domain name within underneath Hd.
5.3 OSPF Security Example
+---------------+ +-------------+
|Key Mgmt Daemon| | OSPF daemon |
+---------------+ +-------------+
| | / / |
| /------|----+ / |
| / | +---+ | Applications
======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================
| | | | OS Kernel
+------------+ +-----------------+ +---------+
| Key Engine | | TCP/IP, | | Routing |
| or SADB |---| including IPsec |--| Table |
+------------+ | | +---------+
+-----------------+
As in the previous examples, the KMd registers itself with the Key
Engine via PF_KEY. Even though the consumer of the security
associations is in user-space, the PF_KEY and Key Engine
implementation knows enough to store SAs and to relay messages.
When the OSPF daemon needs to communicate securely with its peers, it
would perform an SADB_GET message and retrieve the appropriate
association:
OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs
Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, <etc.>
If this GET fails, the OSPFd may need to acquire a new security
association. This interaction is as follows:
OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, <ID, sens,>