--- name: "ipsec_spi" section: "8" platform: "linux" package: "openswan" version: "1:2.6.37-3+deb7u1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/ipsec_spi" --- # ipsec\_spi(8) manage IPSEC Security Associations ## NAME ipsec\_spi - manage IPSEC Security Associations ## SYNOPSIS Note: In the following, **\** *means:* --af *(inet \| inet6)* --edst *daddr* --spi *spi* --proto *proto* *OR* --said *said,*\ **\** *means:* --life *(soft \| hard)* allocations \| *bytes* \| *addtime* \| *usetime* \| *packets* \| \[value...\] **\** --src *src* --ah *(hmac-md5-96 \| hmac-sha1-96)* \[--replay\_window *replayw*\] \[*\*\] --authkey *akey*\ *ipsec* *spi* *\* --src *src* --esp *(3des \| 3des-md5-96 \| 3des-sha1-96)* \[--replay\_window *replayw*\] \[*\*\] --enckey *ekey*\ *ipsec* *spi* *\* --src *src* --esp \[--replay\_window *replayw*\] \[*\*\] --enckey *ekey* --authkey *akey*\ *ipsec* *spi* *\* --src *src* --comp *deflate*\ *ipsec* *spi* *\* --ip4 --src *encap-src* --dst *encap-dst*\ *ipsec* *spi* *\* --ip6 --src *encap-src* --dst *encap-dst*\ *ipsec* *spi* *\* --del\ *ipsec* *spi* --help\ *ipsec* *spi* --version\ *ipsec* *spi* --clear\ ## DESCRIPTION *Spi* creates and deletes IPSEC Security Associations. A Security Association (SA) is a transform through which packet contents are to be processed before being forwarded. A transform can be an IPv4-in-IPv4 or an IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication with no encryption), or an IPSEC Encapsulation Security Payload (encryption, possibly including authentication). When a packet is passed from a higher networking layer through an IPSEC virtual interface, a search in the extended routing table (see [**ipsec\_eroute**(8)](/ipsec_eroute/8.md)) yields an effective destination address, a Security Parameters Index (SPI) and a IP protocol number. When an IPSEC packet arrives from the network, its ostensible destination, an SPI and an IP protocol specified by its outermost IPSEC header are used. The destination/SPI/protocol combination is used to select a relevant SA. (See [**ipsec\_spigrp**(8)](/ipsec_spigrp/8.md) for discussion of how multiple transforms are combined.) The *af*, *daddr*, *spi* and *proto* arguments specify the SA to be created or deleted. *af* is the address family (inet for IPv4, inet6 for IPv6). *Daddr* is a destination address in dotted-decimal notation for IPv4 or in a coloned hex notation for IPv6. *Spi* is a number, preceded by ´0x´ for hexadecimal, between **0x100** and **0xffffffff**; values from **0x0** to **0xff** are reserved. *Proto* is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. The protocol must agree with the algorithm selected. Alternatively, the *said* argument can also specify an SA to be created or deleted. *Said* combines the three parameters above, such as: "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the address family is specified by "." for IPv4 and ":" for IPv6. The address family indicators substitute the "0x" for hexadecimal. The source address, *src*, must also be provided for the inbound policy check to function. The source address does not need to be included if inbound policy checking has been disabled. Keys vectors must be entered as hexadecimal or base64 numbers. They should be cryptographically strong random numbers. All hexadecimal numbers are entered as strings of hexadecimal digits (0-9 and a-f), without spaces, preceded by ´0x´, where each hexadecimal digit represents 4 bits. All base64 numbers are entered as strings of base64 digits (0-9, A-Z, a-z, ´+´ and ´/´), without spaces, preceded by ´0s´, where each hexadecimal digit represents 6 bits and ´=´ is used for padding. The deletion of an SA which has been grouped will result in the entire chain being deleted. The form with no additional arguments lists the contents of /proc/net/ipsec\_spi. The format of /proc/net/ipsec\_spi is discussed in [ipsec\_spi(5)](/ipsec_spi/5.md). The lifetime severity of **soft** sets a limit when the key management daemons are asked to rekey the SA. The lifetime severity of **hard** sets a limit when the SA must expire. The lifetime type **allocations** tells the system when to expire the SA because it is being shared by too many eroutes (not currently used). The lifetime type of **bytes** tells the system to expire the SA after a certain number of bytes have been processed with that SA. The lifetime type of **addtime** tells the system to expire the SA a certain number of seconds after the SA was installed. The lifetime type of **usetime** tells the system to expire the SA a certain number of seconds after that SA has processed its first packet. The lifetime type of **packets** tells the system to expire the SA after a certain number of packets have been processed with that SA. ## OPTIONS - **--af** specifies the address family (inet for IPv4, inet6 for IPv6) - **--edst** specifies the effective destination *daddr* of the Security Association - **--spi** specifies the Security Parameters Index *spi* of the Security Association - **--proto** specifies the IP protocol *proto* of the Security Association - **--said** specifies the Security Association in monolithic format - **--ah** add an SA for an IPSEC Authentication Header, specified by the following transform identifier (**hmac-md5-96** or **hmac-sha1-96**) (RFC2402, obsoletes RFC1826) **hmac-md5-96** transform following the HMAC and MD5 standards, using a 128-bit *key* to produce a 96-bit authenticator (RFC2403) **hmac-sha1-96** transform following the HMAC and SHA1 standards, using a 160-bit *key* to produce a 96-bit authenticator (RFC2404) - **--esp** add an SA for an IPSEC Encapsulation Security Payload, specified by the following transform identifier (**3des**, or **3des-md5-96** (RFC2406, obsoletes RFC1827) **3des** encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode using a 64-bit *iv* (internally generated) and a 192-bit 3DES *ekey* (RFC2451) **3des-md5-96** encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode with authentication provided by HMAC and MD5 (96-bit authenticator), using a 64-bit *iv* (internally generated), a 192-bit 3DES *ekey* and a 128-bit HMAC-MD5 *akey* (RFC2451, RFC2403) **3des-sha1-96** encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode with authentication provided by HMAC and SHA1 (96-bit authenticator), using a 64-bit *iv* (internally generated), a 192-bit 3DES *ekey* and a 160-bit HMAC-SHA1 *akey* (RFC2451, RFC2404) - **--replay\_window** replayw sets the replay window size; valid values are decimal, 1 to 64 - **--life** life\_param\[,life\_param\] sets the lifetime expiry; the format of **life\_param** consists of a comma-separated list of lifetime specifications without spaces; a lifetime specification is comprised of a severity of **soft** or **hard** followed by a ´-´, followed by a lifetime type of **allocations**, **bytes**, **addtime**, **usetime** or **packets** followed by an ´=´ and finally by a value - **--comp** add an SA for IPSEC IP Compression, specified by the following transform identifier (**deflate**) (RFC2393) **deflate** compression transform following the patent-free Deflate compression algorithm (RFC2394) - **--ip4** add an SA for an IPv4-in-IPv4 tunnel from *encap-src* to *encap-dst* - **--ip6** add an SA for an IPv6-in-IPv6 tunnel from *encap-src* to *encap-dst* - **--src** specify the source end of an IP-in-IP tunnel from *encap-src* to *encap-dst* and also specifies the source address of the Security Association to be used in inbound policy checking and must be the same address family as *af* and *edst* - **--dst** specify the destination end of an IP-in-IP tunnel from *encap-src* to *encap-dst* - **--del** delete the specified SA - **--clear** clears the table of **SA**s - **--help** display synopsis - **--version** display version information ## EXAMPLES To keep line lengths down and reduce clutter, some of the long keys in these examples have been abbreviated by replacing part of their text with \`\`...´´. Keys used when the programs are actually run must, of course, be the full length required for the particular algorithm. **ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \\** **--src gw1 \\** **--esp 3des-md5-96 \\** **--enckey 0x6630**...**97ce \\** **--authkey 0x9941**...**71df** sets up an SA from **gw1** to **gw2** with an SPI of **0x125** and protocol **ESP** (50) using **3DES** encryption with integral **MD5-96** authentication transform, using an encryption key of **0x6630**...**97ce** and an authentication key of **0x9941**...**71df** (see note above about abbreviated keys). **ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \\** **--src 3049:9::9000:3101 \\** **--ah hmac-md5-96 \\** **--authkey 0x1234**...**2eda \\** sets up an SA from **3049:9::9000:3101** to **3049:9::9000:3100** with an SPI of **0x150** and protocol **AH** (50) using **MD5-96** authentication transform, using an authentication key of **0x1234**...**2eda** (see note above about abbreviated keys). **ipsec spi --said tun.987@192.168.100.100 --del** deletes an SA to 192.168.100.100 with an SPI of **0x987** and protocol **IPv4-in-IPv4** (4). **ipsec spi --said tun:500@3049:9::1000:1 --del** deletes an SA to **3049:9::1000:1** with an SPI of **0x500** and protocol **IPv6-in-IPv6** (4). ## FILES /proc/net/ipsec\_spi, /usr/local/bin/ipsec ## SEE ALSO [ipsec(8)](/ipsec/8.md), [ipsec\_manual(8)](/ipsec_manual/8.md), [ipsec\_tncfg(8)](/ipsec_tncfg/8.md), [ipsec\_eroute(8)](/ipsec_eroute/8.md), [ipsec\_spigrp(8)](/ipsec_spigrp/8.md), [ipsec\_klipsdebug(8)](/ipsec_klipsdebug/8.md), [ipsec\_spi(5)](/ipsec_spi/5.md) ## HISTORY Written for the Linux FreeS/WAN project \<**http://www.freeswan.org/**\> by Richard Guy Briggs. ## BUGS The syntax is messy and the transform naming needs work.