NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES
#include <sys/types.h> #include <sys/socket.h> #include <net/pfkeyv2.h>int socket(PF_KEY,SOCK_RAW,PF_KEY_V2);
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.
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.
#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_PCHANGE /* Passive listener change (passive ACQUIRE) */
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 */ uint32_t sadb_msg_seq; /* For message originator */ uint32_t sadb_msg_pid; /* Identify originator */ };
#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 */
Extension headers include:
struct sadb_ext { uint16_t sadb_ext_len; /* In 64-bit words, inclusive */ uint16_t sadb_ext_type; /* 0 is reserved */ };
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; };
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; };
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. */ };
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. */ };
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. */ };
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]; */ };
struct sadb_prop { uint16_t sadb_prop_len; uint16_t sadb_prop_exttype; /* PROPOSAL */ uint8_t sadb_prop_replay; /* Replay win. size. */ uint8_t sadb_prop_reserved[3]; /* Followed by sadb_comb[] array. */ };
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; };
struct sadb_supported { uint16_t sadb_supported_len; uint16_t sadb_supported_exttype; uint32_t sadb_supported_reserved; };
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; };
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; };
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 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:
Various message improprieties, including SPI ranges that are malformed, weak keys, and others.
Needed memory was not available.
The message exceeds the maximum length allowed.
An SA (that is being added or created with GETSPI) already exists.
An SA could not be found.
The following are examples of message use and behavior:
<base, address, SPI range>
<base, SA(*), address (SD)>
<base, SA, (lifetime(HS),) address(SD), (address(P), key (AE), (identity(SD),) (sensitivity)>c
<base, SA(*), address (SD)>
<base, SA, (lifetime(HS),) address(SD), (address(P),) key (AE), (identity(SD),) (sensitivity)>
<base, SA, (lifetime(HS),) address (SD), (identity (SD),) (sensitivity)>
<base, SA (*), address (SD)>
<base, SA (*), address (SD)>
<base, SA (*), address (SD)>
<base, SA , (lifetime (HSC),) address SD), (address (P),) key (AE), (identity (SD),) (sensitivity)>
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>
<base>
<base>
<base, supported>
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)>
<base>
<base>
<base>
<base, SA, (lifetime (HSC),) address (SD), (address (P),) key (AE), (identity (SD),) sensitivity)>
<base>
<base>
<base>
The kernel sends a SADB_X_PCHANGE message to registered sockets. Note that 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), (identity (SD), ) (sensitivity,) (proposal)>
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Availability | SUNWcsr (32-bit) |
SUNWcsrx (64-bit) | |
Interface Stability | Evolving |
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.
Time-based lifetimes may not expire with exact precision in seconds because kernel load may affect the aging of SAs.
NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES