1IPSEC_SPI(8) IPSEC_SPI(8)
2
6 ipsec spi - manage IPSEC Security Associations
7
9 Note: In the following,
10 <SA> means: --af (inet | inet6) --edst daddr --spi spi --proto proto OR
12 --said said,
13 <life> means: --life (soft | hard) allocations | bytes | addtime |
14 usetime | packets | value <SA> --src src --ah
15 (hmac-md5-96 | hmac-sha1-96) [--replay_window replayw] [<life>]
16 --authkey akey
17 ipsec spi <SA> --src src --esp
18 (3des | 3des-md5-96 | 3des-sha1-96) [--replay_window replayw]
19 [<life>] --enckey ekey
20 ipsec spi <SA> --src src --esp [--replay_window replayw] [<life>]
21 --enckey ekey --authkey akey
22 ipsec spi <SA> --src src --comp deflate
23 ipsec spi <SA> --ip4 --src encap-src --dst encap-dst
24 ipsec spi <SA> --ip6 --src encap-src --dst encap-dst
25 ipsec spi <SA> --del
26 ipsec spi --help
27 ipsec spi --version
28 ipsec spi --clear
29
33 Spi creates and deletes IPSEC Security Associations. A Security Associ‐
34 ation (SA) is a transform through which packet contents are to be pro‐
35 cessed before being forwarded. A transform can be an IPv4-in-IPv4 or an
36 IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentica‐
37 tion with no encryption), or an IPSEC Encapsulation Security Payload
38 (encryption, possibly including authentication).
39 When a packet is passed from a higher networking layer through an IPSEC
42 virtual interface, a search in the extended routing table (see
43 ipsec_eroute(8)) yields an effective destination address, a Security
44 Parameters Index (SPI) and a IP protocol number. When an IPSEC packet
45 arrives from the network, its ostensible destination, an SPI and an IP
46 protocol specified by its outermost IPSEC header are used. The destina‐
47 tion/SPI/protocol combination is used to select a relevant SA. (See
48 ipsec_spigrp(8) for discussion of how multiple transforms are com‐
49 bined.)
50 The af, daddr, spi and proto arguments specify the SA to be created or
53 deleted. af is the address family (inet for IPv4, inet6 for IPv6). Dad‐
54 dr is a destination address in dotted-decimal notation for IPv4 or in a
55 coloned hex notation for IPv6. Spi is a number, preceded by '0x' for
56 hexadecimal, between 0x100 and 0xffffffff; values from 0x0 to 0xff are
57 reserved. Proto is an ASCII string, "ah", "esp", "comp" or "tun", spec‐
58 ifying the IP protocol. The protocol must agree with the algorithm se‐
59 lected.
60 Alternatively, the said argument can also specify an SA to be created
63 or deleted. Said combines the three parameters above, such as:
64 "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the address family is
65 specified by "." for IPv4 and ":" for IPv6. The address family indica‐
66 tors substitute the "0x" for hexadecimal.
67 The source address, src, must also be provided for the inbound policy
70 check to function. The source address does not need to be included if
71 inbound policy checking has been disabled.
72 Keys vectors must be entered as hexadecimal or base64 numbers. They
75 should be cryptographically strong random numbers.
76 All hexadecimal numbers are entered as strings of hexadecimal digits
79 (0-9 and a-f), without spaces, preceded by '0x', where each hexadecimal
80 digit represents 4 bits. All base64 numbers are entered as strings of
81 base64 digits (0-9, A-Z, a-z, '+' and '/'), without spaces, preceded by
82 '0s', where each hexadecimal digit represents 6 bits and '=' is used
83 for padding.
84 The deletion of an SA which has been grouped will result in the entire
87 chain being deleted.
88 The form with no additional arguments lists the contents of
91 /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in
92 ipsec_spi(5).
93 The lifetime severity of soft sets a limit when the key management dae‐
96 mons are asked to rekey the SA. The lifetime severity of hard sets a
97 limit when the SA must expire. The lifetime type allocations tells the
98 system when to expire the SA because it is being shared by too many er‐
99 outes (not currently used). The lifetime type of bytes tells the system
100 to expire the SA after a certain number of bytes have been processed
101 with that SA. The lifetime type of addtime tells the system to expire
102 the SA a certain number of seconds after the SA was installed. The
103 lifetime type of usetime tells the system to expire the SA a certain
104 number of seconds after that SA has processed its first packet. The
105 lifetime type of packets tells the system to expire the SA after a cer‐
106 tain number of packets have been processed with that SA.
107
110 --af specifies the address family (inet for IPv4, inet6 for IPv6)
111 --edst specifies the effective destination daddr of the Security Asso‐
114 ciation
115 --spi specifies the Security Parameters Index spi of the Security As‐
118 sociation
119 --proto
122 specifies the IP protocol proto of the Security Association
123 --said specifies the Security Association in monolithic format
126 --ah add an SA for an IPSEC Authentication Header, specified by the
129 following transform identifier (hmac-md5-96 or hmac-sha1-96)
130 (RFC2402, obsoletes RFC1826)
131 hmac-md5-96
134 transform following the HMAC and MD5 standards, using a 128-bit
135 key to produce a 96-bit authenticator (RFC2403)
136 hmac-sha1-96
139 transform following the HMAC and SHA1 standards, using a 160-bit
140 key to produce a 96-bit authenticator (RFC2404)
141 --esp add an SA for an IPSEC Encapsulation Security Payload, specified
144 by the following transform identifier (3des, or 3des-md5-96
145 (RFC2406, obsoletes RFC1827)
146 3des encryption transform following the Triple-DES standard in Ci‐
149 pher-Block-Chaining mode using a 64-bit iv (internally generat‐
150 ed) and a 192-bit 3DES ekey (RFC2451)
151 3des-md5-96
154 encryption transform following the Triple-DES standard in Ci‐
155 pher-Block-Chaining mode with authentication provided by HMAC
156 and MD5 (96-bit authenticator), using a 64-bit iv (internally
157 generated), a 192-bit 3DES ekey and a 128-bit HMAC-MD5 akey
158 (RFC2451, RFC2403)
159 3des-sha1-96
162 encryption transform following the Triple-DES standard in Ci‐
163 pher-Block-Chaining mode with authentication provided by HMAC
164 and SHA1 (96-bit authenticator), using a 64-bit iv (internally
165 generated), a 192-bit 3DES ekey and a 160-bit HMAC-SHA1 akey
166 (RFC2451, RFC2404)
167 --replay_window replayw
170 sets the replay window size; valid values are decimal, 1 to 64
171 --life life_param[,life_param]
174 sets the lifetime expiry; the format of life_param consists of a
175 comma-separated list of lifetime specifications without spaces;
176 a lifetime specification is comprised of a severity of soft or
177 hard followed by a '-', followed by a lifetime type of alloca‐
178 tions, bytes, addtime, usetime or packets followed by an '=' and
179 finally by a value
180 --comp add an SA for IPSEC IP Compression, specified by the following
183 transform identifier (deflate) (RFC2393)
184 deflate
187 compression transform following the patent-free Deflate compres‐
188 sion algorithm (RFC2394)
189 --ip4 add an SA for an IPv4-in-IPv4 tunnel from encap-src to encap-dst
192 --ip6 add an SA for an IPv6-in-IPv6 tunnel from encap-src to encap-dst
195 --src specify the source end of an IP-in-IP tunnel from encap-src to
198 encap-dst and also specifies the source address of the Security
199 Association to be used in inbound policy checking and must be
200 the same address family as af and edst
201 --dst specify the destination end of an IP-in-IP tunnel from encap-src
204 to encap-dst
205 --del delete the specified SA
208 --clear
211 clears the table of SAs
212 --help display synopsis
215 --version
218 display version information
219
222 To keep line lengths down and reduce clutter, some of the long keys in
223 these examples have been abbreviated by replacing part of their text
224 with ``...''. Keys used when the programs are actually run must, of
225 course, be the full length required for the particular algorithm.
226 ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \ --src gw1
229 \ --esp 3des-md5-96 \ --enckey 0x6630...97ce \ --authkey
230 0x9941...71df
231 sets up an SA from gw1 to gw2 with an SPI of 0x125 and protocol ESP
234 (50) using 3DES encryption with integral MD5-96 authentication trans‐
235 form, using an encryption key of 0x6630...97ce and an authentication
236 key of 0x9941...71df (see note above about abbreviated keys).
237 ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \
240 --src 3049:9::9000:3101 \ --ah hmac-md5-96 \ --au‐
241 thkey 0x1234...2eda \
242 sets up an SA from 3049:9::9000:3101 to 3049:9::9000:3100 with an SPI
245 of 0x150 and protocol AH (50) using MD5-96 authentication transform,
246 using an authentication key of 0x1234...2eda (see note above about ab‐
247 breviated keys).
248 ipsec spi --said tun.987@192.168.100.100 --del
251 deletes an SA to 192.168.100.100 with an SPI of 0x987 and protocol
254 IPv4-in-IPv4 (4).
255 ipsec spi --said tun:500@3049:9::1000:1 --del
258 deletes an SA to 3049:9::1000:1 with an SPI of 0x500 and protocol
261 IPv6-in-IPv6 (4).
262
265 /proc/net/ipsec_spi, /usr/local/bin/ipsec
266
269 ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), ipsec_spi‐
270 grp(8), ipsec_klipsdebug(8), ipsec_spi(5)
271
274 Written for the Linux FreeS/WAN project <http://www.freeswan.org/:
275 http://www.freeswan.org/> by Richard Guy Briggs.
276
279 The syntax is messy and the transform naming needs work.
280 23 Oct 2001 IPSEC_SPI(8)