| SETKEY(8) | System Manager's Manual | SETKEY(8) | 
setkey —
| setkey | [ -knrv] file ... | 
| setkey | [ -knrv]-c | 
| setkey | [ -krv]-ffilename | 
| setkey | [ -aklPrv]-D | 
| setkey | [ -Pvp]-F | 
| setkey | [ -H]-x | 
| setkey | [ -?V] | 
setkey adds, updates, dumps, or flushes Security
  Association Database (SAD) entries as well as Security Policy Database (SPD)
  entries in the kernel.
setkey takes a series of operations from
    standard input (if invoked with -c) or the file
    named filename (if invoked with
    -f filename).
-?-asetkey usually does not display dead SAD entries
      with -D. If -a is also
      specified, the dead SAD entries will be displayed as well. A dead SAD
      entry is one that has expired but remains in the system because it is
      referenced by some SPD entries.-D-P is also specified, the
      SPD entries are dumped. If -p is specified, the
      ports are displayed.-F-P is also specified,
      the SPD entries are flushed.-H-x mode.-h-H.
      On other systems, synonym for -?.-k-r.-l-D.-n-r-k.-xPF_KEY socket. -xx prints
      the unformatted timestamps.-V-vPF_KEY socket, including messages sent from other
      processes to the kernel.-c or -f on the command
  line, setkey accepts the following configuration
  syntax. Lines starting with hash signs (‘#’) are treated as
  comment lines.
add
    [-46n] src
    dst protocol
    spi [extensions]
    algorithm ...;add can fail for multiple
      reasons, including when the key length does not match the specified
      algorithm.getspi
    [-46n] src
    dst protocol
    spi [extensions];update
    [-46n] src
    dst protocol
    spi [extensions]
    algorithm ...;add or getspi in a series
      of operations because the API requires that a process updating an SAD
      entry is the same as one created the SAD entry.get
    [-46n] src
    dst protocol
    spi;delete
    [-46n] src
    dst protocol
    spi;deleteall
    [-46n] src
    dst protocol;flush
    [protocol];-F
      on the command line achieves the same functionality.dump
    [protocol];-D
      on the command line achieves the same functionality.spdadd
    [-46n] src_range
    dst_range upperspec
    label policy;spdadd
    tagged tag
    policy;spdupdate
    [-46n] src_range
    dst_range upperspec
    label policy;spdupdate
    tagged tag
    policy;spddelete
    [-46n] src_range
    dst_range upperspec
    -P direction;spdflush;-FP on the command line
      achieves the same functionality.spddump;-DP on the command line
      achieves the same functionality.Meta-arguments are as follows:
setkey can resolve a FQDN into numeric addresses.
      If the FQDN resolves into multiple addresses,
      setkey will install multiple SAD/SPD entries into
      the kernel by trying all possible combinations.
      -4, -6, and
      -n restrict the address resolution of FQDN in
      certain ways. -4 and -6
      restrict results into IPv4/v6 addresses only, respectively.
      -n avoids FQDN resolution and requires addresses
      to be numeric addresses.
    
  0x” prefix. SPI
      values between 0 and 255 are reserved for future use by IANA and cannot be
      used. TCP-MD5 associations must use 0x1000 and therefore only have
      per-host granularity at this time.
    
  -m
        modetransport,
          tunnel, or any. The
          default value is any.-r
        size-u
        id-f
        pad_optionzero-padrandom-padseq-pad-f
        nocyclic-seq-lh
        time-ls
        time-bh
        bytes-bs
        bytes-esp_frag
        bytes-ctx
        doi algorithm
        context-name-E
        ealgo key-E
        ealgo key
        -A aalgo
        key-A
        aalgo key-C
        calgo [-R]-R is specified, the spi
          field value will be used as the IPComp CPI (compression parameter
          index) on wire as-is. If -R is not specified,
          the kernel will use well-known CPI on wire, and
          spi field will be used only as an index for
          kernel internal usage.key must be a double-quoted character
        string, or a series of hexadecimal digits preceded by
        “0x”.
Possible values for ealgo, aalgo, and calgo are specified in the Algorithms sections.
address
address/prefixlen
address[port]
address/prefixlen[port]
    
    prefixlen and port must be decimal numbers. The square brackets around port are really necessary, they are not man page meta-characters. For FQDN resolution, the rules applicable to src and dst apply here as well.
icmp6, ip4,
      gre, or any.
      any stands for “any protocol”. You
      can also use the protocol number. Additional specification can be placed
      after the protocol name for some protocols. You can specify a type and/or
      a code of ICMP or ICMPv6. The type is separated from a code by single
      comma and the code must always be specified. GRE key can be specified in
      dotted-quad format or as plain number. When a zero is specified, the
      kernel deals with it as a wildcard. Note that the kernel can not
      distinguish a wildcard from an ICPMv6 type of zero.
    For example, the following means that the policy doesn't require IPsec for any inbound Neighbor Solicitation.
spdadd ::/0 ::/0 icmp6 135,0 -P
      in none;A second example of requiring transport mode encryption of specific GRE tunnel:
spdadd 0.0.0.0 0.0.0.0 gre 1234
      ipsec esp/transport//require;Note: upperspec does not work against forwarding case at this moment, as it requires extra reassembly at the forwarding node (not implemented at this moment). There are many protocols in /etc/protocols, but all protocols except of TCP, UDP, GRE, and ICMP may not be suitable to use with IPsec. You have to consider carefully what to use.
-ctx
        doi algorithm
        context-name-P
          direction [priority specification]
          discard-P
          direction [priority specification]
          none-P
          direction [priority specification]
          ipsec
          protocol/mode/src-dst/level [...]You must specify the direction of its policy as
        direction. Either out,
        in, or fwd can be
      used.
priority specification is used to control the placement of the policy within the SPD. Policy position is determined by a signed integer where higher priorities indicate the policy is placed closer to the beginning of the list and lower priorities indicate the policy is placed closer to the end of the list. Policies with equal priorities are added at the end of groups of such policies.
Priority can only be specified when setkey has been compiled against kernel headers that support policy priorities (Linux >= 2.6.6). If the kernel does not support priorities, a warning message will be printed the first time a priority specification is used. Policy priority takes one of the following formats:
low
          (-1073741824), def (0), or
          high (1073741824)
        offset is an unsigned integer. It can be up to 1073741824 for positive offsets, and up to 1073741823 for negative offsets.
discard means the packet matching
        indexes will be discarded. none means that IPsec
        operation will not take place onto the packet.
        ipsec means that IPsec operation will take place
        onto the packet.
The protocol/mode/src-dst/level part
        specifies the rule how to process the packet. Either
        ah, esp, or
        ipcomp must be used as
        protocol. mode is either
        transport or tunnel. If
        mode is tunnel, you must
        specify the end-point addresses of the SA as src
        and dst with ‘-’ between these
        addresses, which is used to specify the SA to use. If
        mode is transport, both
        src and dst can be omitted.
        level is to be one of the following:
        default, use,
        require, or unique. If
        the SA is not available in every level, the kernel will ask the key
        exchange daemon to establish a suitable SA.
        default means the kernel consults the system
        wide default for the protocol you specified, e.g. the
        esp_trans_deflev sysctl variable, when the
        kernel processes the packet. use means that the
        kernel uses an SA if it's available, otherwise the kernel keeps normal
        operation. require means SA is required whenever
        the kernel sends a packet matched with the policy.
        unique is the same as
        require; in addition, it allows the policy to
        match the unique out-bound SA. You just specify the policy level
        unique,
        racoon(8) will configure
        the SA for the policy. If you configure the SA by manual keying for that
        policy, you can put a decimal number as the policy identifier after
        unique separated by a colon ‘:’
        like: unique:number in
        order to bind this policy to the SA. number must
        be between 1 and 32767. It corresponds to
        extensions -u of the
        manual SA configuration. When you want to use SA bundle, you can define
        multiple rules. For example, if an IP header was followed by an AH
        header followed by an ESP header followed by an upper layer protocol
        header, the rule would be:
esp/transport//require
      ah/transport//require;When NAT-T is enabled in the kernel, policy matching for ESP over UDP packets may be done on endpoint addresses and port (this depends on the system. System that do not perform the port check cannot support multiple endpoints behind the same NAT). When using ESP over UDP, you can specify port numbers in the endpoint addresses to get the correct matching. Here is an example:
spdadd 10.0.11.0/24[any] 10.0.11.33/32[any] any -P out ipsec
    esp/tunnel/192.168.0.1[4500]-192.168.1.2[30000]/require ;
    
    setkey -DPp.
    Note that discard and
        none are not in the syntax described in
        ipsec_set_policy(3).
        There are a few differences in the syntax. See
        ipsec_set_policy(3)
        for detail.
-A aalgo of the
  protocol parameter:
algorithm keylen (bits) hmac-md5 128 ah: rfc2403 128 ah-old: rfc2085 hmac-sha1 160 ah: rfc2404 160 ah-old: 128bit ICV (no document) keyed-md5 128 ah: 96bit ICV (no document) 128 ah-old: rfc1828 keyed-sha1 160 ah: 96bit ICV (no document) 160 ah-old: 128bit ICV (no document) null 0 to 2048 for debugging hmac-sha256 256 ah: 128bit ICV (RFC4868) 256 ah-old: 128bit ICV (no document) hmac-sha384 384 ah: 192bit ICV (RFC4868) 384 ah-old: 128bit ICV (no document) hmac-sha512 512 ah: 256bit ICV (RFC4868) 512 ah-old: 128bit ICV (no document) hmac-ripemd160 160 ah: 96bit ICV (RFC2857) ah-old: 128bit ICV (no document) aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 128 ah-old: 128bit ICV (no document) tcp-md5 8 to 640 tcp: rfc2385
These encryption algorithms can be used as
    ealgo in -E
    ealgo of the protocol
  parameter:
algorithm keylen (bits) des-cbc 64 esp-old: rfc1829, esp: rfc2405 3des-cbc 192 rfc2451 null 0 to 2048 rfc2410 blowfish-cbc 40 to 448 rfc2451 cast128-cbc 40 to 128 rfc2451 des-deriv 64 ipsec-ciph-des-derived-01 3des-deriv 192 no document rijndael-cbc 128/192/256 rfc3602 twofish-cbc 0 to 256 draft-ietf-ipsec-ciph-aes-cbc-01 aes-ctr 160/224/288 rfc3686 camellia-cbc 128/192/256 rfc4312 aes-gcm-16 160/224/288 rfc4106 aes-gmac 160/224/288 rfc4543
Note that the first 128/192/256 bits of a key for
    aes-ctr, aes-gcm-16 or
    aes-gmac will be used as AES key, and the remaining
    32 bits will be used as nonce. Also note that
    aes-gmac does not encrypt the payload, it only
    provides authentication.
These compression algorithms can be used as
    calgo in -C
    calgo of the protocol
  parameter:
algorithm deflate rfc2394
fwd policy instead of the
  in policy for packets what are forwarded through that
  particular box.
In kernel mode,
    setkey manages and shows policies and SAs exactly as
    they are stored in the kernel.
In RFC mode,
  setkey
fwd policies for every
      in policy insertedfwd
    policiessetkey utility exits 0 on success,
  and >0 if an error occurs.
add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 -E des-cbc 0x3ffe05014819ffff ; add -6 myhost.example.com yourhost.example.com ah 123456 -A hmac-sha1 "AH SA configuration!" ; add 10.0.11.41 10.0.11.33 esp 0x10001 -E des-cbc 0x3ffe05014819ffff -A hmac-md5 "authentication!!" ; get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; flush ; dump esp ; spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; add 10.0.11.41 10.0.11.33 esp 0x10001 -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh" -E des-cbc 0x3ffe05014819ffff; spdadd 10.0.11.41 10.0.11.33 any -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh" -P out ipsec esp/transport//require ;
Changed manual key configuration for IPsec, http://www.kame.net/newsletter/19991007/, October 1999.
setkey command first appeared in the WIDE Hydrangea
  IPv6 protocol stack kit. The command was completely re-designed in June 1998.
setkey should report and handle syntax errors better.
For IPsec gateway configuration, src_range and dst_range with TCP/UDP port numbers does not work, as the gateway does not reassemble packets (it cannot inspect upper-layer headers).
| July 23, 2019 | NetBSD 10.0 |