1 .TH IPSEC_SPI 8 "23 Oct 2001"
3 .\" RCSID $Id: spi.8,v 1.31 2001/11/06 20:18:47 rgb Exp $
6 ipsec spi \- manage IPSEC Security Associations
9 Note: In the following,
27 (soft | hard)\-(allocations | bytes | addtime | usetime | packets)=value[,...]
38 .BR hmac-md5-96 | hmac-sha1-96
70 .BR 3des-md5-96 | 3des-sha1-96
127 creates and deletes IPSEC Security Associations.
128 A Security Association (SA) is a transform through which packet
129 contents are to be processed before being forwarded.
130 A transform can be an IPv4-in-IPv4 or an IPv6-in-IPv6 encapsulation,
131 an IPSEC Authentication Header (authentication with no encryption),
132 or an IPSEC Encapsulation Security Payload (encryption, possibly
133 including authentication).
135 When a packet is passed from a higher networking layer
136 through an IPSEC virtual interface,
137 a search in the extended routing table (see
138 .IR ipsec_eroute (8))
139 yields an effective destination address, a
140 Security Parameters Index (SPI) and a IP protocol number.
141 When an IPSEC packet arrives from the network,
142 its ostensible destination, an SPI and an IP protocol
143 specified by its outermost IPSEC header are used.
144 The destination/SPI/protocol combination is used to select a relevant SA.
147 for discussion of how multiple transforms are combined.)
155 arguments specify the SA to be created or deleted.
157 is the address family (inet for IPv4, inet6 for IPv6).
159 is a destination address
160 in dotted-decimal notation for IPv4
161 or in a coloned hex notation for IPv6.
163 is a number, preceded by '0x' for hexadecimal,
174 is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol.
175 The protocol must agree with the algorithm selected.
179 argument can also specify an SA to be created or deleted.
181 combines the three parameters above, such as: "tun.101@1.2.3.4" or "tun:101@1:2::3:4",
182 where the address family is specified by "." for IPv4 and ":" for IPv6. The address
183 family indicators substitute the "0x" for hexadecimal.
187 must also be provided for the inbound policy check to
188 function. The source address does not need to be included if inbound
189 policy checking has been disabled.
191 Keys vectors must be entered as hexadecimal or base64 numbers.
192 They should be cryptographically strong random numbers.
194 All hexadecimal numbers are entered as strings of hexadecimal digits
195 (0-9 and a-f), without spaces, preceded by '0x', where each hexadecimal
196 digit represents 4 bits.
197 All base64 numbers are entered as strings of base64 digits
198 (0-9, A-Z, a-z, '+' and '/'), without spaces, preceded by '0s',
199 where each hexadecimal digit represents 6 bits and '=' is used for padding.
201 The deletion of an SA which has been grouped will result in the entire chain
204 The form with no additional arguments lists the contents of
205 /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in
208 The lifetime severity of
210 sets a limit when the key management daemons are asked to rekey the SA.
211 The lifetime severity of
213 sets a limit when the SA must expire.
216 tells the system when to expire the SA because it is being shared by too many
217 eroutes (not currently used). The lifetime type of
219 tells the system to expire the SA after a certain number of bytes have been
220 processed with that SA. The lifetime type of
222 tells the system to expire the SA a certain number of seconds after the SA was
223 installed. The lifetime type of
225 tells the system to expire the SA a certain number of seconds after that SA has
226 processed its first packet. The lifetime type of
228 tells the system to expire the SA after a certain number of packets have been
229 processed with that SA.
233 specifies the address family (inet for IPv4, inet6 for IPv6)
236 specifies the effective destination
238 of the Security Association
241 specifies the Security Parameters Index
243 of the Security Association
246 specifies the IP protocol
248 of the Security Association
251 specifies the Security Association in monolithic format
254 add an SA for an IPSEC Authentication Header,
255 specified by the following transform identifier
260 (RFC2402, obsoletes RFC1826)
263 transform following the HMAC and MD5 standards,
266 to produce a 96-bit authenticator (RFC2403)
269 transform following the HMAC and SHA1 standards,
272 to produce a 96-bit authenticator (RFC2404)
275 add an SA for an IPSEC Encapsulation Security Payload,
276 specified by the following
277 transform identifier (\c
281 (RFC2406, obsoletes RFC1827)
284 encryption transform following the Triple-DES standard in
285 Cipher-Block-Chaining mode using a 64-bit
287 (internally generated) and a 192-bit 3DES
292 encryption transform following the Triple-DES standard in
293 Cipher-Block-Chaining mode with authentication provided by
295 (96-bit authenticator),
298 (internally generated), a 192-bit 3DES
300 and a 128-bit HMAC-MD5
305 encryption transform following the Triple-DES standard in
306 Cipher-Block-Chaining mode with authentication provided by
308 (96-bit authenticator),
311 (internally generated), a 192-bit 3DES
313 and a 160-bit HMAC-SHA1
317 .BR \-\-replay_window " replayw"
318 sets the replay window size; valid values are decimal, 1 to 64
320 .BR \-\-life " life_param[,life_param]"
321 sets the lifetime expiry; the format of
323 consists of a comma-separated list of lifetime specifications without spaces;
324 a lifetime specification is comprised of a severity of
326 followed by a '-', followed by a lifetime type of
327 .BR allocations ", " bytes ", " addtime ", " usetime " or " packets
328 followed by an '=' and finally by a value
331 add an SA for IPSEC IP Compression,
332 specified by the following
333 transform identifier (\c
338 compression transform following the patent-free Deflate compression algorithm
342 add an SA for an IPv4-in-IPv4
349 add an SA for an IPv6-in-IPv6
356 specify the source end of an IP-in-IP tunnel from
360 and also specifies the source address of the Security Association to be
361 used in inbound policy checking and must be the same address
368 specify the destination end of an IP-in-IP tunnel from
374 delete the specified SA
384 display version information
386 To keep line lengths down and reduce clutter,
387 some of the long keys in these examples have been abbreviated
388 by replacing part of their text with
390 Keys used when the programs are actually run must,
391 of course, be the full length required for the particular algorithm.
393 .B "ipsec spi \-\-af inet \-\-edst gw2 \-\-spi 0x125 \-\-proto esp \e"
397 .B " \-\-esp 3des\-md5\-96 \e"
399 .BI "\ \ \ \-\-enckey\ 0x6630" "..." "97ce\ \e"
401 .BI " \-\-authkey 0x9941" "..." "71df"
413 encryption with integral
415 authentication transform, using an encryption key of
417 and an authentication key of
419 (see note above about abbreviated keys).
421 .B "ipsec spi \-\-af inet6 \-\-edst 3049:9::9000:3100 \-\-spi 0x150 \-\-proto ah \e"
423 .B " \-\-src 3049:9::9000:3101 \e"
425 .B " \-\-ah hmac\-md5\-96 \e"
427 .BI "\ \ \ \-\-authkey\ 0x1234" "..." "2eda\ \e"
430 .BR 3049:9::9000:3101
432 .BR 3049:9::9000:3100
439 authentication transform, using an authentication key of
441 (see note above about abbreviated keys).
443 .B "ipsec spi \-\-said tun.987@192.168.100.100 \-\-del "
453 .B "ipsec spi \-\-said tun:500@3049:9::1000:1 \-\-del "
464 /proc/net/ipsec_spi, /usr/local/bin/ipsec
466 ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8),
467 ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)
469 Written for the Linux FreeS/WAN project
470 <http://www.freeswan.org/>
471 by Richard Guy Briggs.
473 The syntax is messy and the transform naming needs work.
476 .\" Revision 1.31 2001/11/06 20:18:47 rgb
477 .\" Added lifetime parameters.
479 .\" Revision 1.30 2001/10/24 03:23:32 rgb
480 .\" Added lifetime option and parameters.
482 .\" Revision 1.29 2001/05/30 08:14:04 rgb
483 .\" Removed vestiges of esp-null transforms.
485 .\" Revision 1.28 2000/11/29 19:15:20 rgb
486 .\" Add --src requirement for inbound policy routing.
488 .\" Revision 1.27 2000/09/17 18:56:48 rgb
489 .\" Added IPCOMP support.
491 .\" Revision 1.26 2000/09/13 15:54:32 rgb
492 .\" Added Gerhard's ipv6 updates.
494 .\" Revision 1.25 2000/09/12 22:36:45 rgb
495 .\" Gerhard's IPv6 support.
497 .\" Revision 1.24 2000/06/30 18:21:55 rgb
498 .\" Update SEE ALSO sections to include ipsec_version(5) and ipsec_pf_key(5)
499 .\" and correct FILES sections to no longer refer to /dev/ipsec which has
500 .\" been removed since PF_KEY does not use it.
502 .\" Revision 1.23 2000/06/21 16:54:57 rgb
503 .\" Added 'no additional args' text for listing contents of
504 .\" /proc/net/ipsec_* files.
506 .\" Revision 1.22 1999/08/11 08:35:16 rgb
507 .\" Update, deleting references to obsolete and insecure algorithms.
509 .\" Revision 1.21 1999/07/19 18:53:55 henry
510 .\" improve font usage in key abbreviations
512 .\" Revision 1.20 1999/07/19 18:50:09 henry
513 .\" fix slightly-misformed comments
514 .\" abbreviate long keys to avoid long-line complaints
516 .\" Revision 1.19 1999/04/06 04:54:38 rgb
517 .\" Fix/Add RCSID Id: and Log: bits to make PHMDs happy. This includes
518 .\" patch shell fixes.