NAME
pf_key − security association database
SYNOPSIS
#include
<sys/types.h>
#include <sys/socket.h>
#include <net/pfkeyv2.h>
int socket(PF_KEY,SOCK_RAW,PF_KEY_V2);
DESCRIPTION
Keying information for IPsec security services is maintained in security association databases (SADBs). The security associations (SAs) are used to protect both inbound and outbound packets.
A user process (or possibly multiple co-operating processes) maintains SADBs by sending messages over a special kind of socket. This is analogous to the method described in route(7P). Only a superuser may access an SADB.
SunOS applications that use PF_KEY include ipseckey(1M) and in.iked(1M).
The operating system may spontaneously emit messages in response to external events, such as a request for a new SA for an outbound datagram, or to report the expiration of an existing SA.
One opens the channel for passing SADB control messages by using the socket call shown in the SYNOPSIS section above. More than one key socket can be open per system.
Messages are formed by a small base header, followed by a number, zero or more, of extension messages, some of which require additional data following them. The base message and all extensions must be eight-byte aligned. An example message is the GET message, which requires the base header, the SA extension, and the ADDRESS_DST extension.
Messages
Messages include:
#define SADB_GETSPI /* Get a new SPI value from the system. */
#define SADB_UPDATE /* Update an SA. */
#define SADB_ADD /* Add a fully-formed SA. */
#define SADB_DELETE /* Delete an SA. */
#define SADB_GET /* Get an SA */
#define SADB_ACQUIRE /* Kernel needs a new SA. */
#define SADB_REGISTER /* Register to receive ACQUIRE messages. */
#define SADB_EXPIRE /* SA has expired. */
#define SADB_FLUSH /* Flush all SAs. */
#define SADB_DUMP /* Get all SAs. (Unreliable) */
#define SADB_X_PROMISC /* Listen promiscuously */
#define SADB_X_INVERSE_ACQUIRE /* Query kernel policy,
get an ACQUIRE in return. */
The base message header consists of:
struct sadb_msg {
uint8_t sadb_msg_version; /* Set to PF_KEY_V2, for compatibility */
uint8_t sadb_msg_type; /* Message type */
uint8_t sadb_msg_errno; /* Why message failed */
uint8_t sadb_msg_satype; /* Which security service */
uint16_t sadb_msg_len; /* Length in 8-byte units */
uint16_t sadb_msg_reserved; /* Zero out */
#define sadb_x_msg_diagnostic sadb_msg_reserved
/* Extended diagnostics for errors */
uint32_t sadb_msg_seq; /* For message originator */
uint32_t sadb_msg_pid; /* Identify originator */
};
Extension types include:
#define SADB_EXT_SA /* SA information */ #define SADB_EXT_LIFETIME_HARD /* Hard lifetime */ #define SADB_EXT_LIFETIME_SOFT /* Soft lifetime */ #define SADB_EXT_ADDRESS_SRC /* Source address */ #define SADB_EXT_ADDRESS_DST /* Destination address */ #define SADB_EXT_ADDRESS_PROXY /* Proxy address */ #define SADB_EXT_KEY_AUTH /* Authentication key */ #define SADB_EXT_KEY_ENCRYPT /* Encryption key */ #define SADB_EXT_IDENTITY_SRC /* Source certificate ID */ #define SADB_EXT_IDENTITY_DST /* Destination certificate ID */ #define SADB_EXT_SENSITIVITY /* Sensitivity information */ #define SADB_EXT_PROPOSAL /* Security proposal */ #define SADB_EXT_SUPPORTED_AUTH /* Supported authentication algorithms */ #define SADB_EXT_SUPPORTED_ENCRYPT /* Supported encryption algorithms */ #define SADB_EXT_SPIRANGE /* Range of possible SPIs * #define SADB_X_EXT_EREG /* Register for extended ACQUIRE */ #define SADB_X_EXT_EPROP /* Extended ACQUIRE proposals */ #define SADB_X_EXT_KM_COOKIE /* Indicates which KM derived SA. */
Extension headers include:
Generic Extension Header
struct sadb_ext {
uint16_t sadb_ext_len; /* In 64-bit words, inclusive */
uint16_t sadb_ext_type; /* 0 is reserved */
};
Security Association Information Extension
struct sadb_sa {
uint16_t sadb_sa_len;
uint16_t sadb_sa_exttype; /* ASSOCIATION */
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;
};
Lifetime Extension
struct sadb_lifetime {
uint16_t sadb_lifetime_len;
uint16_t sadb_lifetime_exttype; /* SOFT, HARD, CURRENT */
uint32_t sadb_lifetime_allocations;
uint64_t sadb_lifetime_bytes;
uint64_t sadb_lifetime_addtime;
uint64_t sadb_lifetime_usetime;
};
Address Extension
struct sadb_address {
uint16_t sadb_address_len;
uint16_t sadb_address_exttype; /* SRC, DST, PROXY */
uint8_t sadb_address_proto; /* Proto for ports... */
uint8_t sadb_address_prefixlen; /* Prefix length. */
uint16_t sadb_address_reserved; /* Padding */
/* Followed by a sockaddr structure.*/
};
Keying Material Extension
struct sadb_key {
uint16_t sadb_key_len;
uint16_t sadb_key_exttype; /* AUTH, ENCRYPT */
uint16_t sadb_key_bits;
uint16_t sadb_key_reserved;
/* Followed by actual key(s) in canonical (outbound proc.) order. */
};
Indentity Extension
struct sadb_ident {
uint16_t sadb_ident_len;
uint16_t sadb_ident_exttype; /* SRC, DST, PROXY */
uint16_t sadb_ident_type; /* FQDN, USER_FQDN, etc. */
uint16_t sadb_ident_reserved; /* Padding */
uint64_t sadb_ident_id; /* For userid, etc. */
/* Followed by an identity null-terminate C string if present. */
};
Sensitivity/Integrity Extension
struct sadb_sens {
uint16_t sadb_sens_len;
uint16_t sadb_sens_exttype; /* SENSITIVITY */
uint32_t sadb_sens_dpd;
uint8_t sadb_sens_sens_level;
uint8_t sadb_sens_sens_len; /* 64-bit words */
uint8_t sadb_sens_integ_level;
uint8_t sadb_sens_integ_len; /* 64-bit words */
uint32_t sadb_sens_reserved;
/*
* followed by two uint64_t arrays
* uint64_t sadb_sens_bitmap[sens_bitmap_len];
* uint64_t integ_bitmap[integ_bitmap_len];
*/
};
Proposal Extension
struct sadb_prop {
uint16_t sadb_prop_len;
uint16_t sadb_prop_len;
uint16_t sadb_prop_exttype; /* PROPOSAL, X_EPROP */
union {
struct {
uint8_t sadb_prop_lenres_replay;
uint8_t sadb_prop_lenres_eres;
uint16_t sadb_prop_lenres_numecombs;
} sadb_prop_lenres;
struct {
uint8_t sadb_prop_oldres_replay;
uint8_t sadb_prop_oldres_reserved[3];
} sadb_prop_oldres;
} sadb_prop_u;
#define sadb_prop_replay sadb_prop_u.sadb_prop_lenres.sadb_prop_lenres_replay
#define sadb_prop_reserved
sadb_prop_u.sadb_prop_oldres.sadb_prop_oldres_reserved
#define sadb_x_prop_ereserved
sadb_prop_u.sadb_prop_lenres.sadb_prop_lenres_eres
#define sadb_x_prop_numecombs
sadb_prop_u.sadb_prop_lenres.sadb_prop_lenres_numecombs
/* Followed by sadb_comb[] array or sadb_ecomb[] array. */
};
};
Combination Instance for a Proposal
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;
};
Extended Combination
struct sadb_x_ecomb {
uint8_t sadb_x_ecomb_numalgs;
uint8_t sadb_x_ecomb_reserved;
uint16_t sadb_x_ecomb_flags; /* E.g. PFS? */
uint32_t sadb_x_ecomb_reserved2;
uint32_t sadb_x_ecomb_soft_allocations;
uint32_t sadb_x_ecomb_hard_allocations;
uint64_t sadb_x_ecomb_soft_bytes;
uint64_t sadb_x_ecomb_hard_bytes;
uint64_t sadb_x_ecomb_soft_addtime;
uint64_t sadb_x_ecomb_hard_addtime;
uint64_t sadb_x_ecomb_soft_usetime;
uint64_t sadb_x_ecomb_hard_usetime;
};
Extended Combination Algorithm Descriptors
struct sadb_x_algdesc {
uint8_t sadb_x_algdesc_satype; /* ESP, AH, etc. */
uint8_t sadb_x_algdesc_algtype; /* AUTH, CRYPT, COMPRESS */
uint8_t sadb_x_algdesc_alg; /* DES, 3DES, MD5, etc. */
uint8_t sadb_x_algdesc_reserved;
uint16_t sadb_x_algdesc_minbits; /* Bit strengths. */
uint16_t sadb_x_algdesc_maxbits;
/* XXX Any other junk here? */
};
Extended Register
struct sadb_x_ereg {
uint16_t sadb_x_ereg_len;
uint16_t sadb_x_ereg_exttype; /* X_EREG */
uint8_t sadb_x_ereg_satypes[4]; /* Array of SA types, 0-terminated.
|};
Key Management Cookie
struct sadb_x_kmc {
uint16_t sadb_x_kmc_len;
uint16_t sadb_x_kmc_exttype; /* X_KM_COOKIE */
uint32_t sadb_x_kmc_proto; /* KM protocol */
uint32_t sadb_x_kmc_cookie; /* KMP-specific */
uint32_t sadb_x_kmc_reserved; /* Reserved; must be zero */
};
Supported Algorithms Extension
struct sadb_supported {
uint16_t sadb_supported_len;
uint16_t sadb_supported_exttype;
uint32_t sadb_supported_reserved;
};
Algorithm Instance
struct sadb_alg {
uint8_t sadb_alg_id; /* Algorithm type. */
uint8_t sadb_alg_ivlen; /* IV len, in bits */
uint16_t sadb_alg_minbits; /* Min. key len (in bits) */
uint16_t sadb_alg_maxbits; /* Max. key length */
uint16_t sadb_alg_reserved;
};
SPI Extension Range
struct sadb_spirange {
uint16_t sadb_spirange_len;
uint16_t sadb_spirange_exttype; /* SPI_RANGE */
uint32_t sadb_spirange_min
uint32_t sadb_spirange_max;
uint32_t sadb_spirange_reserved;
};
Message Use
and Behavior
Each message has a behavior. A behavior is defined as where
the initial message travels, for example, user to kernel,
and what subsequent actions are expected to take place.
Contents of messages are illustrated as:
<base, REQUIRED EXTENSION, REQ., (OPTIONAL EXTENSION), (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 that when
an error occurs, only the base header is sent. Typical
errors include:
EINVAL
Various message improprieties, including SPI ranges that are malformed, weak keys, and others. If EINVAL is returned, an application should look at the sadb_x_msg_diagnostic field of the sadb_msg structure. It contains one of many possible causes for EINVAL. See net/pfkeyv2.h for values, all of the form SADB_X_DIAGNOSTIC_.
ENOMEM
Needed memory was not available.
ENSGSIZ
Message exceeds the maximum length allowed.
EEXIST
SA (that is being added or created with GETSPI) already exists.
|
ESRCH |
SA could not be found. |
The following are examples of message use and behavior:
SADB_GETSPI
Send a SADB_GETSPI message from a user process to the
kernel.
<base, address, SPI range>
The kernel returns the SADB_GETSPI message to all listening processes.
<base, SA(*), address (SD)>
SADB_UPDATE
Send a SADB_UPDATE message from a user process to the
kernel.
<base, SA, (lifetime(HS),) address(SD), (address(P), key (AE),
(identity(SD),) (sensitivity)>c
The kernel returns the SADB_UPDATE message to all listening processes.
<base, SA(*), address (SD)>
SADB_ADD
Send a 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)>
SADB_DELETE
Send a 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)>
SADB_GET
Send a 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)>
SADB_ACQUIRE
The kernel sends a SADB_ACQUIRE message to registered
sockets. Note that any GETSPI, ADD, or
UPDATE calls in reaction to an ACQUIRE must
fill in the sadb_msg_seq of those messages with the
one in the ACQUIRE message. The address (SD)
extensions must have the port fields filled in with the port
numbers of the session requiring keys if appropriate.
<base, address (SD), (address(P)), (identity(SD),)
(sensitivity,) proposal>
Extended ACQUIRE will have a slightly different format. The sadb_msg_satype field is 0, and the extension contains the desired combination(s) of security protocols.
<base, address (SD), (address(P)), (identity(SD),)
(sensitivity,) eprop>
If key management fails, send an SADB_ACQUIRE to indicate failure.
<base>
SADB_X_INVERSE_ACQUIRE
For inbound Key Management processing, a Key Management
application may wish to consult the kernel for its policy.
The application should send to the kernel:
<base, address (SD)>
The kernel returns a message similar to a kernel-generated extended ACQUIRE:
<base, address (SD), (address(P)), (identity(SD),)
(sensitivity,) eprop>
SADB_REGISTER
Send a SADB_REGISTER message from a user process to
the kernel.
<base>
The kernel returns the SADB_REGISTER message to registered sockets, with algorithm types supported by the kernel being indicated in the supported algorithms field. Note that this message may arrive asynchronously due to an algorithm being loaded or unloaded into a dynamically linked kernel.
<base, supported>
There is also the extended REGISTER, which will allow this process to receive extended ACQUIREs.
<base, ereg>
Which returns a series of SADB_REGISTER replies (one for each security protocol registered) from the kernel.
SADB_EXPIRE
The kernel sends a SADB_EXPIRE message to all
listeners when the soft lmit of a security association has
been expired.
<base, SA, lifetime (C and one of HS), address (SD)>
SADB_FLUSH
Send a SADB_FLUSH message from a user process to the
kernel.
<base>
The kernel returns the SADB_FLUSH message to all listening sockets.
<base>
SADB_DUMP
Send a SADB_DUMP message from a user process to the
kernel.
<base>
Several SADB_DUMP messages will return from the kernel to the sending socket.
<base, SA, (lifetime (HSC),) address (SD), (address (P),) key (AE),
(identity (SD),) sensitivity)>
To mark the end of a dump a single base header arrives with its sadb_mdg_seq set to 0.
<base>
SADB_X_PROMISC
Send a SADB_X_PROMISC message from a user process to
the kernel.
<base>
The kernel returns the SADB_X_PROMISC message to all listening processes.
<base>
ATTRIBUTES
See
attributes(5)
for descriptions of the following attributes:
SEE ALSO
in.iked(1M), ipseckey(1M), ipsec(7P), ipsecah(7P), ipsecesp(7P), route(7P)
McDonald, D.L., Metz, C.W., and Phan, B.G., RFC 2367, PF_KEY Key Management API, Version 2, The Internet Society, July 1998.
NOTES
Time-based lifetimes may not expire with exact precision in seconds because kernel load may affect the aging of SA’s.