1IPSEC_SPI(8) [FIXME: manual] 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 |
14 addtime | usetime | packets | [value...] <SA> --src src
15 --ah (hmac-md5-96 | hmac-sha1-96)
16 [--replay_window replayw] [<life>] --authkey akey
17 ipsec spi <SA> --src src --esp
18 (3des | 3des-md5-96 | 3des-sha1-96)
19 [--replay_window replayw] [<life>] --enckey ekey
20 ipsec spi <SA> --src src --esp [--replay_window replayw]
21 [<life>] --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
32 Spi creates and deletes IPSEC Security Associations. A Security
33 Association (SA) is a transform through which packet contents are to be
34 processed before being forwarded. A transform can be an IPv4-in-IPv4 or
35 an IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header
36 (authentication with no encryption), or an IPSEC Encapsulation Security
37 Payload (encryption, possibly including authentication).
38 When a packet is passed from a higher networking layer through an IPSEC
40 virtual interface, a search in the extended routing table (see
41 ipsec_eroute(8)) yields an effective destination address, a Security
42 Parameters Index (SPI) and a IP protocol number. When an IPSEC packet
43 arrives from the network, its ostensible destination, an SPI and an IP
44 protocol specified by its outermost IPSEC header are used. The
45 destination/SPI/protocol combination is used to select a relevant SA.
46 (See ipsec_spigrp(8) for discussion of how multiple transforms are
47 combined.)
48 The af, daddr, spi and proto arguments specify the SA to be created or
50 deleted. af is the address family (inet for IPv4, inet6 for IPv6).
51 Daddr is a destination address in dotted-decimal notation for IPv4 or
52 in a coloned hex notation for IPv6. Spi is a number, preceded by ´0x´
53 for hexadecimal, between 0x100 and 0xffffffff; values from 0x0 to 0xff
54 are reserved. Proto is an ASCII string, "ah", "esp", "comp" or "tun",
55 specifying the IP protocol. The protocol must agree with the algorithm
56 selected.
57 Alternatively, the said argument can also specify an SA to be created
59 or deleted. Said combines the three parameters above, such as:
60 "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the address family is
61 specified by "." for IPv4 and ":" for IPv6. The address family
62 indicators substitute the "0x" for hexadecimal.
63 The source address, src, must also be provided for the inbound policy
65 check to function. The source address does not need to be included if
66 inbound policy checking has been disabled.
67 Keys vectors must be entered as hexadecimal or base64 numbers. They
69 should be cryptographically strong random numbers.
70 All hexadecimal numbers are entered as strings of hexadecimal digits
72 (0-9 and a-f), without spaces, preceded by ´0x´, where each hexadecimal
73 digit represents 4 bits. All base64 numbers are entered as strings of
74 base64 digits (0-9, A-Z, a-z, ´+´ and ´/´), without spaces, preceded by
75 ´0s´, where each hexadecimal digit represents 6 bits and ´=´ is used
76 for padding.
77 The deletion of an SA which has been grouped will result in the entire
79 chain being deleted.
80 The form with no additional arguments lists the contents of
82 /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in
83 ipsec_spi(5).
84 The lifetime severity of soft sets a limit when the key management
86 daemons are asked to rekey the SA. The lifetime severity of hard sets a
87 limit when the SA must expire. The lifetime type allocations tells the
88 system when to expire the SA because it is being shared by too many
89 eroutes (not currently used). The lifetime type of bytes tells the
90 system to expire the SA after a certain number of bytes have been
91 processed with that SA. The lifetime type of addtime tells the system
92 to expire the SA a certain number of seconds after the SA was
93 installed. The lifetime type of usetime tells the system to expire the
94 SA a certain number of seconds after that SA has processed its first
95 packet. The lifetime type of packets tells the system to expire the SA
96 after a certain number of packets have been processed with that SA.
97
99 --af
100 specifies the address family (inet for IPv4, inet6 for IPv6)
101 --edst
103 specifies the effective destination daddr of the Security
104 Association
105 --spi
107 specifies the Security Parameters Index spi of the Security
108 Association
109 --proto
111 specifies the IP protocol proto of the Security Association
112 --said
114 specifies the Security Association in monolithic format
115 --ah
117 add an SA for an IPSEC Authentication Header, specified by the
118 following transform identifier (hmac-md5-96 or hmac-sha1-96)
119 (RFC2402, obsoletes RFC1826)
120 hmac-md5-96
122 transform following the HMAC and MD5 standards, using a 128-bit key
123 to produce a 96-bit authenticator (RFC2403)
124 hmac-sha1-96
126 transform following the HMAC and SHA1 standards, using a 160-bit
127 key to produce a 96-bit authenticator (RFC2404)
128 --esp
130 add an SA for an IPSEC Encapsulation Security Payload, specified by
131 the following transform identifier (3des, or 3des-md5-96 (RFC2406,
132 obsoletes RFC1827)
133 3des
135 encryption transform following the Triple-DES standard in
136 Cipher-Block-Chaining mode using a 64-bit iv (internally generated)
137 and a 192-bit 3DES ekey (RFC2451)
138 3des-md5-96
140 encryption transform following the Triple-DES standard in
141 Cipher-Block-Chaining mode with authentication provided by HMAC and
142 MD5 (96-bit authenticator), using a 64-bit iv (internally
143 generated), a 192-bit 3DES ekey and a 128-bit HMAC-MD5 akey
144 (RFC2451, RFC2403)
145 3des-sha1-96
147 encryption transform following the Triple-DES standard in
148 Cipher-Block-Chaining mode with authentication provided by HMAC and
149 SHA1 (96-bit authenticator), using a 64-bit iv (internally
150 generated), a 192-bit 3DES ekey and a 160-bit HMAC-SHA1 akey
151 (RFC2451, RFC2404)
152 --replay_window replayw
154 sets the replay window size; valid values are decimal, 1 to 64
155 --life life_param[,life_param]
157 sets the lifetime expiry; the format of life_param consists of a
158 comma-separated list of lifetime specifications without spaces; a
159 lifetime specification is comprised of a severity of soft or hard
160 followed by a ´-´, followed by a lifetime type of allocations,
161 bytes, addtime, usetime or packets followed by an ´=´ and finally
162 by a value
163 --comp
165 add an SA for IPSEC IP Compression, specified by the following
166 transform identifier (deflate) (RFC2393)
167 deflate
169 compression transform following the patent-free Deflate compression
170 algorithm (RFC2394)
171 --ip4
173 add an SA for an IPv4-in-IPv4 tunnel from encap-src to encap-dst
174 --ip6
176 add an SA for an IPv6-in-IPv6 tunnel from encap-src to encap-dst
177 --src
179 specify the source end of an IP-in-IP tunnel from encap-src to
180 encap-dst and also specifies the source address of the Security
181 Association to be used in inbound policy checking and must be the
182 same address family as af and edst
183 --dst
185 specify the destination end of an IP-in-IP tunnel from encap-src to
186 encap-dst
187 --del
189 delete the specified SA
190 --clear
192 clears the table of SAs
193 --help
195 display synopsis
196 --version
198 display version information
199
201 To keep line lengths down and reduce clutter, some of the long keys in
202 these examples have been abbreviated by replacing part of their text
203 with ``...´´. Keys used when the programs are actually run must, of
204 course, be the full length required for the particular algorithm.
205 ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \
207 --src gw1 \
209 --esp 3des-md5-96 \
211 --enckey 0x6630...97ce \
213 --authkey 0x9941...71df
215 sets up an SA from gw1 to gw2 with an SPI of 0x125 and protocol ESP
217 (50) using 3DES encryption with integral MD5-96 authentication
218 transform, using an encryption key of 0x6630...97ce and an
219 authentication key of 0x9941...71df (see note above about abbreviated
220 keys).
221 ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \
223 --src 3049:9::9000:3101 \
225 --ah hmac-md5-96 \
227 --authkey 0x1234...2eda \
229 sets up an SA from 3049:9::9000:3101 to 3049:9::9000:3100 with an SPI
231 of 0x150 and protocol AH (50) using MD5-96 authentication transform,
232 using an authentication key of 0x1234...2eda (see note above about
233 abbreviated keys).
234 ipsec spi --said tun.987@192.168.100.100 --del
236 deletes an SA to 192.168.100.100 with an SPI of 0x987 and protocol
238 IPv4-in-IPv4 (4).
239 ipsec spi --said tun:500@3049:9::1000:1 --del
241 deletes an SA to 3049:9::1000:1 with an SPI of 0x500 and protocol
243 IPv6-in-IPv6 (4).
244
246 /proc/net/ipsec_spi, /usr/local/bin/ipsec
247
249 ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8),
250 ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)
251
253 Written for the Linux FreeS/WAN project <http://www.freeswan.org/> by
254 Richard Guy Briggs.
255
257 The syntax is messy and the transform naming needs work.
258[FIXME: source] 23 Oct 2001 IPSEC_SPI(8)