JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
man pages section 7: Device and Network Interfaces     Oracle Solaris 11 Information Library
search filter icon
search icon

Document Information

Preface

Introduction

Device and Network Interfaces

1394(7D)

aac(7D)

adpu320(7D)

afe(7D)

agpgart_io(7I)

AH(7P)

ahci(7D)

allkmem(7D)

amd8111s(7D)

arcmsr(7D)

arn(7D)

ARP(7P)

arp(7P)

ast(7D)

asy(7D)

ata(7D)

atge(7D)

ath(7D)

atu(7D)

audio1575(7D)

audio(7D)

audio(7I)

audio810(7D)

audiocmi(7D)

audiocs(7D)

audioemu10k(7D)

audioens(7D)

audiohd(7D)

audioixp(7D)

audiols(7D)

audiop16x(7D)

audiopci(7D)

audiosolo(7D)

audiots(7D)

audiovia823x(7D)

av1394(7D)

bbc_beep(7D)

bcm_sata(7D)

bfe(7D)

bge(7D)

blkdev(7D)

bmc(7D)

bnx(7D)

bnxe(7D)

bpf(7D)

bscbus(7D)

bscv(7D)

bufmod(7M)

cdio(7I)

chxge(7D)

cmdk(7D)

connld(7M)

console(7D)

cpqary3(7D)

cpr(7)

cpuid(7D)

ctfs(7FS)

ctsmc(7D)

cvc(7D)

cvcredir(7D)

cxge(7D)

dad(7D)

daplt(7D)

dca(7D)

dcam1394(7D)

dcfs(7FS)

dev(7FS)

devchassis(7FS)

devfs(7FS)

devinfo(7D)

dkio(7I)

dlcosmk(7ipp)

dlpi(7P)

dm2s(7D)

dmfe(7D)

dnet(7D)

dr(7d)

drmach(7d)

dscpmk(7ipp)

dsp(7I)

dtrace(7D)

e1000(7D)

e1000g(7D)

ecpp(7D)

efb(7D)

ehci(7D)

eibnx(7D)

eiob(7D)

elxl(7D)

emlxs(7D)

eri(7D)

ESP(7P)

fas(7D)

fasttrap(7D)

fbio(7I)

fbt(7D)

fcip(7D)

fcoe(7D)

fcoei(7D)

fcoet(7D)

fcp(7D)

fctl(7D)

fipe(7D)

firewire(7D)

flowacct(7ipp)

fp(7d)

FSS(7)

gld(7D)

glm(7D)

gpio_87317(7D)

grbeep(7d)

hci1394(7D)

hdio(7I)

heci(7D)

hermon(7D)

hid(7D)

hme(7D)

hsfs(7FS)

hubd(7D)

hwa1480_fw(7D)

hwahc(7D)

hwarc(7D)

hxge(7D)

i2bsc(7D)

i915(7d)

ib(7D)

ibcm(7D)

ibdm(7D)

ibdma(7D)

ibmf(7)

ibp(7D)

ibtl(7D)

icmp6(7P)

ICMP(7P)

icmp(7P)

idn(7d)

iec61883(7I)

ieee1394(7D)

if(7P)

ifp(7D)

if_tcp(7P)

igb(7D)

igbvf(7D)

ii(7D)

imraid_sas(7D)

inet6(7P)

inet(7P)

ip6(7P)

IP(7P)

ip(7P)

ipgpc(7ipp)

ipmi(7D)

ipnat(7I)

ipnet(7D)

ipqos(7ipp)

iprb(7D)

ipsec(7P)

ipsecah(7P)

ipsecesp(7P)

ipw(7D)

iscsi(7D)

isdnio(7I)

iser(7D)

isp(7D)

iwh(7D)

iwi(7D)

iwk(7D)

iwp(7D)

ixgb(7d)

ixgbe(7D)

ixgbevf(7D)

kb(7M)

kdmouse(7D)

kmdb(7d)

kmem(7D)

kstat(7D)

ksyms(7D)

ldterm(7M)

llc1(7D)

llc2(7D)

lo0(7D)

lockstat(7D)

lofi(7D)

lofs(7FS)

log(7D)

marvell88sx(7D)

mc-opl(7D)

mcxe(7D)

md(7D)

mediator(7D)

mega_sas(7D)

mem(7D)

mhd(7i)

mixer(7I)

mpt(7D)

mpt_sas(7D)

mr_sas(7D)

msglog(7D)

mt(7D)

mtio(7I)

mwl(7D)

mxfe(7D)

myri10ge(7D)

n2cp(7d)

n2rng(7d)

nca(7d)

ncp(7D)

ngdr(7d)

ngdrmach(7d)

nge(7D)

npe(7D)

ntwdt(7D)

ntxn(7D)

null(7D)

nulldriver(7D)

nv_sata(7D)

nxge(7D)

objfs(7FS)

oce(7D)

ohci(7D)

openprom(7D)

oplkmdrv(7D)

oplmsu(7D)

oplpanel(7D)

packet(7P)

pcan(7D)

pcata(7D)

pcfs(7FS)

pcic(7D)

pcicmu(7D)

pcie_pci(7D)

pcipsy(7D)

pcisch(7D)

pckt(7M)

pcmcia(7D)

pcn(7D)

pcser(7D)

pcwl(7D)

pf_key(7P)

pfmod(7M)

PF_PACKET(7P)

physmem(7D)

pipemod(7M)

pm(7D)

poll(7d)

prnio(7I)

profile(7D)

ptem(7M)

ptm(7D)

pts(7D)

pty(7D)

qfe(7d)

qlc(7D)

qlcnic(7D)

qlge(7D)

quotactl(7I)

radeon(7d)

ral(7D)

ramdisk(7D)

random(7D)

RARP(7P)

rarp(7P)

rge(7D)

route(7P)

routing(7P)

rtls(7D)

rtw(7D)

rum(7D)

rwd(7D)

rwn(7D)

sad(7D)

sata(7D)

scfd(7D)

schpc(7D)

scsa1394(7D)

scsa2usb(7D)

scsi_vhci(7D)

SCTP(7P)

sctp(7P)

scu(7D)

sd(7D)

sda(7D)

SDC(7)

sdcard(7D)

sdhost(7D)

sdp(7D)

sdt(7D)

se(7D)

se_hdlc(7D)

ses(7D)

sesio(7I)

sf(7D)

sfe(7D)

sgen(7D)

sharefs(7FS)

si3124(7D)

sip(7P)

slp(7P)

smbfs(7FS)

smbios(7D)

smbus(7D)

smp(7D)

snca(7d)

socal(7D)

sockio(7I)

sol_ofs(7D)

sol_ucma(7D)

sol_umad(7D)

sol_uverbs(7D)

sppptun(7M)

srpt(7D)

ssd(7D)

st(7D)

streamio(7I)

su(7D)

sv(7D)

sxge(7D)

sysmsg(7D)

systrace(7D)

tavor(7D)

TCP(7P)

tcp(7P)

termio(7I)

termiox(7I)

ticlts(7D)

ticots(7D)

ticotsord(7D)

timod(7M)

tirdwr(7M)

tmpfs(7FS)

todopl(7D)

tokenmt(7ipp)

tsalarm(7D)

tswtclmt(7ipp)

ttcompat(7M)

tty(7D)

ttymux(7D)

tzmon(7d)

uata(7D)

uath(7D)

udfs(7FS)

UDP(7P)

udp(7P)

ufs(7FS)

ugen(7D)

uhci(7D)

ural(7D)

urandom(7D)

urtw(7D)

usb(7D)

usba(7D)

usb_ac(7D)

usb_ah(7M)

usb_as(7D)

usbecm(7D)

usbftdi(7D)

usb_ia(7D)

usbkbm(7M)

usb_mid(7D)

usbms(7M)

usbprn(7D)

usbsacm(7D)

usbser_edge(7D)

usbsksp(7D)

usbsprl(7D)

usbvc(7D)

usbwcm(7M)

uscsi(7I)

usmp(7I)

uvfs(7FS)

uwb(7D)

uwba(7D)

virtualkm(7D)

visual_io(7I)

vni(7d)

vr(7D)

vt(7I)

vuid2ps2(7M)

vuid3ps2(7M)

vuidm3p(7M)

vuidm4p(7M)

vuidm5p(7M)

vuidmice(7M)

vxge(7D)

wpi(7D)

wscons(7D)

wusb_ca(7D)

wusb_df(7D)

xge(7D)

yge(7D)

zcons(7D)

zero(7D)

zfs(7FS)

zs(7D)

zsh(7D)

zyd(7D)

pf_key

- Security association database interface

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 can spontaneously send pf_key messages to listening processes, 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 zero or more 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   /* Regis. to receive ACQUIRE msgs. */
#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. */
#define    SADB_X_UPDATEPAIR     /* Update an SA and its pair SA */
#define    SADB_X_DELPAIR        /* Delete an SA pair. */

The base message header consists of:

struct sadb_msg {
    uint8_t  sadb_msg_version;  /* Set to PF_KEY_V2, for compat. */
    uint8_t  sadb_msg_type;     /* Msg. 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 msg. originator */
    uint32_t sadb_msg_pid;      /* ID originator */
};

Extension types include:

#define  SADB_EXT_SA                /* SA info */
#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 - DEPRECATED */
#define  SADB_EXT_KEY_AUTH          /* Authen. key */
#define  SADB_EXT_KEY_ENCRYPT       /* Encryption key */
#define  SADB_EXT_IDENTITY_SRC      /* Source certif. ID */
#define  SADB_EXT_IDENTITY_DST      /* Destination certif. ID */
#define  SADB_EXT_SENSITIVITY       /* Sensitivity info */
#define  SADB_EXT_PROPOSAL          /* Security proposal */
#define  SADB_EXT_SUPPORTED_AUTH   /* Supported authen. algo's */
#define  SADB_EXT_SUPPORTED_ENCRYPT /* Supported encryption algo's */
#define  SADB_EXT_SPIRANGE          /* Range of possible SPIs *
#define  SADB_X_EXT_EREG           /* Reg. for extended ACQUIRE */
#define  SADB_X_EXT_EPROP          /* Extended ACQUIRE proposals */
#define  SADB_X_EXT_KM_COOKIE      /* Indicates which KM derived SA. */
#define  SADB_X_EXT_ADDRESS_NATT_LOC  /* NAT-Traversal local (my public) */
#define  SADB_X_EXT_ADDRESS_NATT_REM  /* NAT-T remote (peer's private) */
#define  SADB_X_EXT_ADDRESS_INNER_SRC /* Tunnel-mode inner source */
#define  SADB_X_EXT_ADDRESS_INNER_DST /* Tunnel-mode inner dest */
#define  SADB_X_EXT_REPLAY_VALUE      /* Replay Value */
#define  SADB_X_EXT_LIFETIME_IDLE     /* Idle lifetime */
#define  SADB_X_EXT_PAIR              /* SA pair extension*/
#define  SADB_X_EXT_OUTER_SENS   /*outer sensitivity */

Security Association Information Extension flags:

#define SADB_SAFLAGS_PFS        0x1          /* Perfect forward secrecy? */
#define SADB_SAFLAGS_NOREPLAY   0x2          /* Replay field NOT PRESENT. */
#define SADB_X_SAFLAGS_USED     0x80000000   /* SA used/not used */
#define SADB_X_SAFLAGS_UNIQUE   0x40000000   /* SA unique/reusable */
#define SADB_X_SAFLAGS_AALG1    0x20000000   /* Auth-alg specif. flag 1 */
#define SADB_X_SAFLAGS_AALG2    0x10000000   /* Auth-alg specif. flag 2 */
#define SADB_X_SAFLAGS_EALG1     0x8000000   /* Encr-alg specif. flag 1 */
#define SADB_X_SAFLAGS_EALG2     0x4000000   /* Encr-alg specif. flag 2 */
#define SADB_X_SAFLAGS_KM1       0x2000000   /* Key mgmt. specif. flag 1 */
#define SADB_X_SAFLAGS_KM2       0x1000000   /* Key mgmt. specif. flag 2 */
#define SADB_X_SAFLAGS_KM3        0x800000   /* Key mgmt. specif. flag 3 */
#define SADB_X_SAFLAGS_KM4        0x400000   /* Key mgmt. specif. flag 4 */
#define SADB_X_SAFLAGS_KRES1      0x200000   /* Reserved by the kernel */
#define SADB_X_SAFLAGS_NATT_LOC   0x100000   /* this has a natted srcSA */
#define SADB_X_SAFLAGS_NATT_REM    0x80000   /* this has a natted dstSA */
#define SADB_X_SAFLAGS_KRES2       0x40000   /* Reserved by the kernel */
#define SADB_X_SAFLAGS_TUNNEL      0x20000   /* tunnel mode */
#define SADB_X_SAFLAGS_PAIRED      0x10000   /* inbound/outbound pair*/
#define SADB_X_SAFLAGS_OUTBOUND     0x8000   /* SA direction bit */
#define SADB_X_SAFLAGS_INBOUND      0x4000   /* SA direction bit */

Sensitivity Extension flags:

#define SADB_X_SENS_IMPLICIT 0x1    /* implicit labelling */
#define SADB_X_SENS_UNLABELED 0x2   /* peer is unlabeled */

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, NATT_*, INNER_* */
    uint8_t sadb_address_proto;       /* Proto for ports... */ 
    uint8_t sadb_address_prefixlen;   /* Prefix length for INNER_*. */
    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, OUTER_SENS */
  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_x_sens_flags;
                  /*
                   * 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, X_EPROP */
    uint8_t sadb_prop_replay;
    uint8_t sadb_X_prop_ereserved;
    uint16_t sadb_x_prop_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;
   };
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;
};
Security Association Pair Extension
struct sadb_x_pair {
    uint16_t sadb_x_pair_len;
    uint16_t sadb_x_pair_exttype;   /* SADB_X_EXT_PAIR */
    uint32_t sadb_x_pair_spi;       /* SPI of paired SA */
};
Replay Value
struct sadb_x_replay_ctr {
    uint16_t sadb_x_rc_len;
    uint16_t sadb_x_rc_exttype;
    uint32_t sadb_x_rc_replay32;    /* For 240x SAs. */
    uint64_t sadb_x_rc_replay64;    /* For 430x SAs. */
};

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, (Nl)NAT-T local, (Nr)NAT-T remote, (Is)Inner source, and (Id)Inner destination.

Source and destination address extensions reflect outer-header selectors for an IPsec SA. An SA is inbound or outbound depending on which of the source or destination address is local to the node. Inner-source and inner-destination selectors represent inner-header selectors for Tunnel Mode SAs. A Tunnel Mode SA must have either IPPROTO_ENCAP or IPPROTO_IPV6 in its outer-headers as protocol selector, in addition to filled-in Inner-address extensions.

NAT-T local and NAT-T remote addresses store local and remote ports used for ESP-in-UDP encapsulation. A non-zero local NAT-T address extension represents the local node's external IP address if it is not equivalent to the SA's local address. A non-zero remote NAT-T address represents a peer's behind-a-NAT address if it is not equivalent to the SA's remote address. An SA with NAT-T extensions protects-and-transmits outbound traffic. Processing of inbound NAT-T traffic requires a UDP socket bound to the appropriate local port and it must have the UDP_NAT_T_ENDPOINT (see udp(7P)) socket option enabled.

Note that when an error occurs, only the base header is sent. In the event of an error, an extended diagnostic can be set (see DIAGNOSTICS). 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(Is,Id),
 address(Nl,Nr),key (AE), (identity(SD),) (sensitivity, outer sensitivity)>

The kernel returns the SADB_UPDATE message to all listening processes.

<base, SA(*), address (SD), (pair)>

Adding a sadb_x_pair extension to an SADB_UPDATE or SADB_ADD message updates the security association pair linkage with the SPI of the security association contained in that extension. The resulting security association pair can be updated or as a single entity using the SADB_X_UPDATEPAIR or SADB_X_DELPAIR message types.

SADB_ADD

Send a SADB_ADD message from a user process to the kernel.

<base, SA, (lifetime(HS),) address(SD), (address(Is,Id),)
  (address(Nl,Nr),) key(AE), (identity(SD),) (sensitivity, outer sensitivity) (pair)>
 

The kernel returns the SADB_ADD message to all listening processes.

<base, SA, (lifetime(HS),) address (SD), (address(Is,Id),)
   (address(Nl,Nr),) (identity (SD),) (sensitivity, outer sensitivity)>
SADB_X_UPDATEPAIR

Send a SADB_X_UPDATEPAIR message from a user process to the kernel. This message type is used to update the lifetime values of a security association and the lifetime values of the security association it is paired with.

<base, SA, lifetime(HS), address(SD)>
SADB_DELETE | SADB_X_DELPAIR

Send a SADB_DELETE message from a user process to the kernel. The SADB_X_DELPAIR message type requests deletion of the security association and the security association it is paired with.

<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, outer 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(Is,Id)), (identity(SD),) 
     (sensitivity) proposal>

Extended ACQUIRE has 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(Is,Id)), (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 can wish to consult the kernel for its policy. The application should send to the kernel:

<base, address (SD), (address(Is,Id))>

The kernel returns a message similar to a kernel-generated extended ACQUIRE:

<base, address (SD), (address(Is,Id)), (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 can arrive asynchronously due to an algorithm being loaded or unloaded into a dynamically linked kernel.

<base, supported>

There is also the extended REGISTER, which allows 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 limit 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 returns from the kernel to the sending socket.

<base, SA, (lifetime (HSC),) address (SD), (address (Is,Id),)
   (address (Nl,Nr),) key (AE), (identity (SD),) sensitivity, outer 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>

Diagnostics

The message returning from the kernel contains a diagnostic value in the base message header, the diagnostic value indicates if action requested by the original message was a success.

Diagnostic Values:

#define SADB_X_DIAGNOSTIC_NONE                  0
#define SADB_X_DIAGNOSTIC_UNKNOWN_MSG           1
#define SADB_X_DIAGNOSTIC_UNKNOWN_EXT           2
#define SADB_X_DIAGNOSTIC_BAD_EXTLEN            3
#define SADB_X_DIAGNOSTIC_UNKNOWN_SATYPE        4
#define SADB_X_DIAGNOSTIC_SATYPE_NEEDED         5
#define SADB_X_DIAGNOSTIC_NO_SADBS              6
#define SADB_X_DIAGNOSTIC_NO_EXT                7
        /* Bad address family value */
#define SADB_X_DIAGNOSTIC_BAD_SRC_AF            8
        /* in sockaddr->sa_family. */
#define SADB_X_DIAGNOSTIC_BAD_DST_AF            9
        /* These two are synonyms. */
#define SADB_X_DIAGNOSTIC_BAD_PROXY_AF          10
#define SADB_X_DIAGNOSTIC_BAD_INNER_SRC_AF      10

#define SADB_X_DIAGNOSTIC_AF_MISMATCH           11

#define SADB_X_DIAGNOSTIC_BAD_SRC               12
#define SADB_X_DIAGNOSTIC_BAD_DST               13

#define SADB_X_DIAGNOSTIC_ALLOC_HSERR           14
#define SADB_X_DIAGNOSTIC_BYTES_HSERR           15
#define SADB_X_DIAGNOSTIC_ADDTIME_HSERR         16
#define SADB_X_DIAGNOSTIC_USETIME_HSERR         17

#define SADB_X_DIAGNOSTIC_MISSING_SRC           18
#define SADB_X_DIAGNOSTIC_MISSING_DST           19
#define SADB_X_DIAGNOSTIC_MISSING_SA            20
#define SADB_X_DIAGNOSTIC_MISSING_EKEY          21
#define SADB_X_DIAGNOSTIC_MISSING_AKEY          22
#define SADB_X_DIAGNOSTIC_MISSING_RANGE         23

#define SADB_X_DIAGNOSTIC_DUPLICATE_SRC         24
#define SADB_X_DIAGNOSTIC_DUPLICATE_DST         25
#define SADB_X_DIAGNOSTIC_DUPLICATE_SA          26
#define SADB_X_DIAGNOSTIC_DUPLICATE_EKEY        27
#define SADB_X_DIAGNOSTIC_DUPLICATE_AKEY        28
#define SADB_X_DIAGNOSTIC_DUPLICATE_RANGE       29

#define SADB_X_DIAGNOSTIC_MALFORMED_SRC         30
#define SADB_X_DIAGNOSTIC_MALFORMED_DST         31
#define SADB_X_DIAGNOSTIC_MALFORMED_SA          32
#define SADB_X_DIAGNOSTIC_MALFORMED_EKEY        33
#define SADB_X_DIAGNOSTIC_MALFORMED_AKEY        34
#define SADB_X_DIAGNOSTIC_MALFORMED_RANGE       35

#define SADB_X_DIAGNOSTIC_AKEY_PRESENT          36
#define SADB_X_DIAGNOSTIC_EKEY_PRESENT          37
#define SADB_X_DIAGNOSTIC_PROP_PRESENT          38
#define SADB_X_DIAGNOSTIC_SUPP_PRESENT          39
#define SADB_X_DIAGNOSTIC_BAD_AALG              40
#define SADB_X_DIAGNOSTIC_BAD_EALG              41
#define SADB_X_DIAGNOSTIC_BAD_SAFLAGS           42
#define SADB_X_DIAGNOSTIC_BAD_SASTATE           43

#define SADB_X_DIAGNOSTIC_BAD_AKEYBITS          44
#define SADB_X_DIAGNOSTIC_BAD_EKEYBITS          45

#define SADB_X_DIAGNOSTIC_ENCR_NOTSUPP          46

#define SADB_X_DIAGNOSTIC_WEAK_EKEY             47
#define SADB_X_DIAGNOSTIC_WEAK_AKEY             48

#define SADB_X_DIAGNOSTIC_DUPLICATE_KMP         49
#define SADB_X_DIAGNOSTIC_DUPLICATE_KMC         50

#define SADB_X_DIAGNOSTIC_MISSING_NATT_LOC      51
#define SADB_X_DIAGNOSTIC_MISSING_NATT_REM      52
#define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_LOC    53
#define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_REM    54
#define SADB_X_DIAGNOSTIC_MALFORMED_NATT_LOC    55
#define SADB_X_DIAGNOSTIC_MALFORMED_NATT_REM    56
#define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_PORTS  57

#define SADB_X_DIAGNOSTIC_MISSING_INNER_SRC     58
#define SADB_X_DIAGNOSTIC_MISSING_INNER_DST     59
#define SADB_X_DIAGNOSTIC_DUPLICATE_INNER_SRC   60
#define SADB_X_DIAGNOSTIC_DUPLICATE_INNER_DST   61
#define SADB_X_DIAGNOSTIC_MALFORMED_INNER_SRC   62
#define SADB_X_DIAGNOSTIC_MALFORMED_INNER_DST   63

#define SADB_X_DIAGNOSTIC_PREFIX_INNER_SRC      64
#define SADB_X_DIAGNOSTIC_PREFIX_INNER_DST      65
#define SADB_X_DIAGNOSTIC_BAD_INNER_DST_AF      66
#define SADB_X_DIAGNOSTIC_INNER_AF_MISMATCH     67

#define SADB_X_DIAGNOSTIC_BAD_NATT_REM_AF       68
#define SADB_X_DIAGNOSTIC_BAD_NATT_LOC_AF       69

#define SADB_X_DIAGNOSTIC_PROTO_MISMATCH        70
#define SADB_X_DIAGNOSTIC_INNER_PROTO_MISMATCH  71

#define SADB_X_DIAGNOSTIC_DUAL_PORT_SETS        72

#define SADB_X_DIAGNOSTIC_PAIR_INAPPROPRIATE    73
#define SADB_X_DIAGNOSTIC_PAIR_ADD_MISMATCH     74
#define SADB_X_DIAGNOSTIC_PAIR_ALREADY          75
#define SADB_X_DIAGNOSTIC_PAIR_SA_NOTFOUND      76
#define SADB_X_DIAGNOSTIC_BAD_SA_DIRECTION      77

#define SADB_X_DIAGNOSTIC_SA_NOTFOUND           78
#define SADB_X_DIAGNOSTIC_SA_EXPIRED            79
#define SADB_X_DIAGNOSTIC_BAD_CTX               80
#define SADB_X_DIAGNOSTIC_INVALID_REPLAY        81
#define SADB_X_DIAGNOSTIC_MISSING_LIFETIME      82
#define SADB_X_DIAGNOSTIC_BAD_LABEL             83

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os
Interface Stability
Committed

See Also

in.iked(1M), ipseckey(1M), ipsec(7P), ipsecah(7P), ipsecesp(7P), route(7P), udp(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 might not expire with exact precision in seconds because kernel load can affect the aging of SA's.