1IPSEC_SPI(8)                  Executable programs                 IPSEC_SPI(8)
2
3
4

NAME

6       ipsec_spi - manage IPSEC Security Associations
7

SYNOPSIS

9       Note: In the following,
10
11       <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
30

DESCRIPTION

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
39       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
49       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
58       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
64       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
68       Keys vectors must be entered as hexadecimal or base64 numbers. They
69       should be cryptographically strong random numbers.
70
71       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
78       The deletion of an SA which has been grouped will result in the entire
79       chain being deleted.
80
81       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
85       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

OPTIONS

99       --af
100           specifies the address family (inet for IPv4, inet6 for IPv6)
101
102       --edst
103           specifies the effective destination daddr of the Security
104           Association
105
106       --spi
107           specifies the Security Parameters Index spi of the Security
108           Association
109
110       --proto
111           specifies the IP protocol proto of the Security Association
112
113       --said
114           specifies the Security Association in monolithic format
115
116       --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
121       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
125       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
129       --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
134       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
139       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
146       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
153       --replay_window replayw
154           sets the replay window size; valid values are decimal, 1 to 64
155
156       --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
164       --comp
165           add an SA for IPSEC IP Compression, specified by the following
166           transform identifier (deflate) (RFC2393)
167
168       deflate
169           compression transform following the patent-free Deflate compression
170           algorithm (RFC2394)
171
172       --ip4
173           add an SA for an IPv4-in-IPv4 tunnel from encap-src to encap-dst
174
175       --ip6
176           add an SA for an IPv6-in-IPv6 tunnel from encap-src to encap-dst
177
178       --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
184       --dst
185           specify the destination end of an IP-in-IP tunnel from encap-src to
186           encap-dst
187
188       --del
189           delete the specified SA
190
191       --clear
192           clears the table of SAs
193
194       --help
195           display synopsis
196
197       --version
198           display version information
199

EXAMPLES

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
206       ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \
207
208        --src gw1 \
209
210        --esp 3des-md5-96 \
211
212          --enckey 0x6630...97ce \
213
214        --authkey 0x9941...71df
215
216       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
222       ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \
223
224        --src 3049:9::9000:3101 \
225
226        --ah hmac-md5-96 \
227
228          --authkey 0x1234...2eda \
229
230       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
235       ipsec spi --said tun.987@192.168.100.100 --del
236
237       deletes an SA to 192.168.100.100 with an SPI of 0x987 and protocol
238       IPv4-in-IPv4 (4).
239
240       ipsec spi --said tun:500@3049:9::1000:1 --del
241
242       deletes an SA to 3049:9::1000:1 with an SPI of 0x500 and protocol
243       IPv6-in-IPv6 (4).
244

FILES

246       /proc/net/ipsec_spi, /usr/local/bin/ipsec
247

SEE ALSO

249       ipsec(8), ipsec_tncfg(8), ipsec_eroute(8), ipsec_spigrp(8),
250       ipsec_klipsdebug(8), ipsec_spi(5)
251

HISTORY

253       Written for the Linux FreeS/WAN project <http://www.freeswan.org/> by
254       Richard Guy Briggs.
255

BUGS

257       The syntax is messy and the transform naming needs work.
258

AUTHOR

260       Paul Wouters
261           placeholder to suppress warning
262
263
264
265libreswan                         10/04/2017                      IPSEC_SPI(8)
Impressum