pf_key(7P)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES

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.

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_PCHANGE  /* Passive listener change (passive ACQUIRE) */

---

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 */
    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 */

---

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_exttype;  /* PROPOSAL */
    uint8_t sadb_prop_replay;    /* Replay win. size. */ 
    uint8_t sadb_prop_reserved[3];
                                 /* Followed by sadb_comb[] array. */
};

---

A 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;
};

---

Supported Algorithms Extension

---

struct sadb_supported {
    uint16_t sadb_supported_len;         
    uint16_t sadb_supported_exttype;
    uint32_t sadb_supported_reserved;
};

---

An 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;
};

---

Range of SPIs Extension

---

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.

ENOMEM

Needed memory was not available.

ENSGSIZ

The message exceeds the maximum length allowed.

EEXIST

An SA (that is being added or created with GETSPI) already exists.

ESRCH

An 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>

---

If key management fails, the user process should send an SADB_ACQUIRE to indicate failure.

---

<base>

---

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>

---

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 will arrive 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>

---

SADB_X_PCHANGE

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)>

---

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsr (32-bit)
	SUNWcsrx (64-bit)
Interface Stability	Evolving

SEE ALSO

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 SAs.

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES