pf_key - security association database


     #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 out-
     bound 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

     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 mes-
     sage is the GET message, which  requires  the  base  header,
     the SA extension, and the ADDRESS_DST extension.

     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
     #define sadb_x_prop_ereserved
     #define 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;
         /* 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. Con-
     tents of messages are illustrated as:


     The SA extension is sometimes used only for its  SPI  field.
     If  all other fields must be ignored, this is represented by

     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,

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

           Needed memory was not available.

           Message exceeds the maximum length allowed.

           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:

     Send a SADB_GETSPI message from a user process to  the  ker-

     <base, address, SPI range>

     The kernel returns the SADB_GETSPI message to all  listening

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

     Send a SADB_UPDATE message from a user process to  the  ker-

     <base, SA, (lifetime(HS),) address(SD), (address(P), key (AE),
          (identity(SD),) (sensitivity)>c

     The kernel returns the SADB_UPDATE message to all  listening

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


     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

     <base, SA, (lifetime(HS),) address (SD),
          (identity (SD),) (sensitivity)>

     Send a SADB_DELETE message from a user process to  the  ker-

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

     The kernel returns the SADB_DELETE message to all  listening

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

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

     The kernel sends a SADB_ACQUIRE message to registered  sock-
     ets.  Note that any GETSPI, ADD, or UPDATE calls in reaction
     to an ACQUIRE must fill in the sadb_msg_seq  of  those  mes-
     sages  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


     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>

     Send a SADB_REGISTER message from a user process to the ker-


     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.

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

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


     The kernel returns the SADB_FLUSH message to  all  listening


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


     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.


     Send a SADB_X_PROMISC message from a  user  process  to  the


     The kernel returns the SADB_X_PROMISC message to all listen-
     ing processes.



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

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


     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


     Time-based lifetimes may not expire with exact precision  in
     seconds because kernel load may affect the aging of SA's.

Man(1) output converted with man2html