freeswan/klips/utils/spi.8

   1 .TH IPSEC_SPI 8 "23 Oct 2001"
   2 .\"
   3 .\" RCSID $Id: spi.8,v 1.31 2001/11/06 20:18:47 rgb Exp $
   4 .\"
   5 .SH NAME
   6 ipsec spi \- manage IPSEC Security Associations
   7 .SH SYNOPSIS
   8 .br
   9 Note: In the following,
  10 .br
  11 .B <SA>
  12 means:
  13 .B \-\-af
  14 (inet | inet6)
  15 .B \-\-edst
  16 daddr
  17 .B \-\-spi
  18 spi
  19 .B \-\-proto
  20 proto OR
  21 .B \-\-said
  22 said,
  23 .br
  24 .B <life>
  25 means:
  26 .B \-\-life
  27 (soft | hard)\-(allocations | bytes | addtime | usetime | packets)=value[,...]
  28 .PP
  29 .B ipsec
  30 .B spi
  31 .PP
  32 .B ipsec
  33 .B spi
  34 .B <SA>
  35 .B \-\-src
  36 src
  37 .B \-\-ah
  38 .BR hmac-md5-96 | hmac-sha1-96
  39 [
  40 .B \-\-replay_window
  41 replayw ]
  42 [
  43 .B <life>
  44 ]
  45 .B \-\-authkey
  46 akey
  47 .PP
  48 .B ipsec
  49 .B spi
  50 .B <SA>
  51 .B \-\-src
  52 src
  53 .B \-\-esp
  54 .BR 3des
  55 [
  56 .B \-\-replay_window
  57 replayw ]
  58 [
  59 .B <life>
  60 ]
  61 .B \-\-enckey
  62 ekey
  63 .PP
  64 .B ipsec
  65 .B spi
  66 .B <SA>
  67 .B \-\-src
  68 src
  69 .B \-\-esp
  70 .BR 3des-md5-96 | 3des-sha1-96
  71 [
  72 .B \-\-replay_window
  73 replayw ]
  74 [
  75 .B <life>
  76 ]
  77 .B \-\-enckey
  78 ekey
  79 .B \-\-authkey
  80 akey
  81 .PP
  82 .B ipsec
  83 .B spi
  84 .B <SA>
  85 .B \-\-src
  86 src
  87 .B \-\-comp
  88 .BR deflate
  89 .PP
  90 .B ipsec
  91 .B spi
  92 .B <SA>
  93 .B \-\-ip4
  94 .B \-\-src
  95 encap-src
  96 .B \-\-dst
  97 encap-dst
  98 .PP
  99 .B ipsec
 100 .B spi
 101 .B <SA>
 102 .B \-\-ip6
 103 .B \-\-src
 104 encap-src
 105 .B \-\-dst
 106 encap-dst
 107 .PP
 108 .B ipsec
 109 .B spi
 110 .B <SA>
 111 .B \-\-del
 112 .PP
 113 .B ipsec
 114 .B spi
 115 .B \-\-help
 116 .PP
 117 .B ipsec
 118 .B spi
 119 .B \-\-version
 120 .PP
 121 .B ipsec
 122 .B spi
 123 .B \-\-clear
 124 .PP
 125 .SH DESCRIPTION
 126 .I Spi
 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).
 134 .PP
 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.
 145 (See
 146 .IR ipsec_spigrp (8)
 147 for discussion of how multiple transforms are combined.)
 148 .PP
 149 The
 150 .IR af ,
 151 .IR daddr ,
 152 .I spi
 153 and
 154 .I proto
 155 arguments specify the SA to be created or deleted.
 156 .I af
 157 is the address family (inet for IPv4, inet6 for IPv6).
 158 .I Daddr
 159 is a destination address
 160 in dotted-decimal notation for IPv4
 161 or in a coloned hex notation for IPv6.
 162 .I Spi
 163 is a number, preceded by '0x' for hexadecimal,
 164 between
 165 .B 0x100
 166 and
 167 .BR 0xffffffff ;
 168 values from
 169 .B 0x0
 170 to
 171 .B 0xff
 172 are reserved.
 173 .I Proto
 174 is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol.
 175 The protocol must agree with the algorithm selected.
 176 .PP
 177 Alternatively, the
 178 .I said
 179 argument can also specify an SA to be created or deleted.
 180 .I Said
 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.
 184 .PP
 185 The source address,
 186 .IR src ,
 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.
 190 .PP
 191 Keys vectors must be entered as hexadecimal or base64 numbers.
 192 They should be cryptographically strong random numbers.
 193 .PP
 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.
 200 .PP
 201 The deletion of an SA which has been grouped will result in the entire chain
 202 being deleted.
 203 .PP
 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
 206 ipsec_spi(5).
 207 .PP
 208 The lifetime severity of
 209 .B soft
 210 sets a limit when the key management daemons are asked to rekey the SA.
 211 The lifetime severity of
 212 .B hard
 213 sets a limit when the SA must expire.
 214 The lifetime type
 215 .B allocations
 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
 218 .B bytes
 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
 221 .B addtime
 222 tells the system to expire the SA a certain number of seconds after the SA was
 223 installed.  The lifetime type of
 224 .B usetime
 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
 227 .B packets
 228 tells the system to expire the SA after a certain number of packets have been
 229 processed with that SA.
 230 .SH OPTIONS
 231 .TP 10
 232 .B \-\-af
 233 specifies the address family (inet for IPv4, inet6 for IPv6)
 234 .TP
 235 .B \-\-edst
 236 specifies the effective destination
 237 .I daddr
 238 of the Security Association
 239 .TP
 240 .B \-\-spi
 241 specifies the Security Parameters Index
 242 .I spi
 243 of the Security Association
 244 .TP
 245 .B \-\-proto
 246 specifies the IP protocol
 247 .I proto
 248 of the Security Association
 249 .TP
 250 .B \-\-said
 251 specifies the Security Association in monolithic format
 252 .TP
 253 .B \-\-ah
 254 add an SA for an IPSEC Authentication Header,
 255 specified by the following transform identifier
 256 (\c
 257 .BR hmac-md5-96
 258 or
 259 .BR hmac-sha1-96 )
 260 (RFC2402, obsoletes RFC1826)
 261 .TP
 262 .B hmac-md5-96
 263 transform following the HMAC and MD5 standards,
 264 using a 128-bit
 265 .I key
 266 to produce a 96-bit authenticator (RFC2403)
 267 .TP
 268 .B hmac-sha1-96
 269 transform following the HMAC and SHA1 standards,
 270 using a 160-bit
 271 .I key
 272 to produce a 96-bit authenticator (RFC2404)
 273 .TP
 274 .B \-\-esp
 275 add an SA for an IPSEC Encapsulation Security Payload,
 276 specified by the following
 277 transform identifier (\c
 278 .BR 3des ,
 279 or
 280 .BR 3des-md5-96 )
 281 (RFC2406, obsoletes RFC1827)
 282 .TP
 283 .B 3des
 284 encryption transform following the Triple-DES standard in
 285 Cipher-Block-Chaining mode using a 64-bit
 286 .I iv
 287 (internally generated) and a 192-bit 3DES
 288 .I ekey
 289 (RFC2451)
 290 .TP
 291 .B 3des-md5-96
 292 encryption transform following the Triple-DES standard in
 293 Cipher-Block-Chaining mode with authentication provided by
 294 HMAC and MD5
 295 (96-bit authenticator),
 296 using a 64-bit
 297 .IR iv
 298 (internally generated), a 192-bit 3DES
 299 .I ekey
 300 and a 128-bit HMAC-MD5
 301 .I akey
 302 (RFC2451, RFC2403)
 303 .TP
 304 .B 3des-sha1-96
 305 encryption transform following the Triple-DES standard in
 306 Cipher-Block-Chaining mode with authentication provided by
 307 HMAC and SHA1
 308 (96-bit authenticator),
 309 using a 64-bit
 310 .IR iv
 311 (internally generated), a 192-bit 3DES
 312 .I ekey
 313 and a 160-bit HMAC-SHA1
 314 .I akey
 315 (RFC2451, RFC2404)
 316 .TP
 317 .BR \-\-replay_window " replayw"
 318 sets the replay window size; valid values are decimal, 1 to 64
 319 .TP
 320 .BR \-\-life " life_param[,life_param]"
 321 sets the lifetime expiry; the format of
 322 .B life_param
 323 consists of a comma-separated list of lifetime specifications without spaces;
 324 a lifetime specification is comprised of a severity of
 325 .BR soft " or " hard
 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
 329 .TP
 330 .B \-\-comp
 331 add an SA for IPSEC IP Compression,
 332 specified by the following
 333 transform identifier (\c
 334 .BR deflate )
 335 (RFC2393)
 336 .TP
 337 .B deflate
 338 compression transform following the patent-free Deflate compression algorithm
 339 (RFC2394)
 340 .TP
 341 .B \-\-ip4
 342 add an SA for an IPv4-in-IPv4
 343 tunnel from
 344 .I encap-src
 345 to
 346 .I encap-dst
 347 .TP
 348 .B \-\-ip6
 349 add an SA for an IPv6-in-IPv6
 350 tunnel from
 351 .I encap-src
 352 to
 353 .I encap-dst
 354 .TP
 355 .B \-\-src
 356 specify the source end of an IP-in-IP tunnel from
 357 .I encap-src
 358 to
 359 .I encap-dst
 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
 362 family as
 363 .I af
 364 and
 365 .I edst
 366 .TP
 367 .B \-\-dst
 368 specify the destination end of an IP-in-IP tunnel from
 369 .I encap-src
 370 to
 371 .I encap-dst
 372 .TP
 373 .B \-\-del
 374 delete the specified SA
 375 .TP
 376 .BR \-\-clear
 377 clears the table of
 378 .BR SA s
 379 .TP
 380 .BR \-\-help
 381 display synopsis
 382 .TP
 383 .BR \-\-version
 384 display version information
 385 .SH EXAMPLES
 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
 389 .RI `` ... ''.
 390 Keys used when the programs are actually run must,
 391 of course, be the full length required for the particular algorithm.
 392 .LP
 393 .B "ipsec spi \-\-af inet \-\-edst gw2 \-\-spi 0x125 \-\-proto esp \e"
 394 .br
 395 .B "   \-\-src gw1 \e"
 396 .br
 397 .B "   \-\-esp 3des\-md5\-96 \e"
 398 .br
 399 .BI "\ \ \ \-\-enckey\ 0x6630" "..." "97ce\ \e"
 400 .br
 401 .BI "   \-\-authkey 0x9941" "..." "71df"
 402 .LP
 403 sets up an SA from
 404 .BR gw1
 405 to
 406 .BR gw2
 407 with an SPI of
 408 .BR 0x125
 409 and protocol
 410 .BR ESP
 411 (50) using
 412 .BR 3DES
 413 encryption with integral
 414 .BR MD5-96
 415 authentication transform, using an encryption key of
 416 .BI 0x6630 ... 97ce
 417 and an authentication key of
 418 .BI 0x9941 ... 71df
 419 (see note above about abbreviated keys).
 420 .LP
 421 .B "ipsec spi \-\-af inet6 \-\-edst 3049:9::9000:3100 \-\-spi 0x150 \-\-proto ah \e"
 422 .br
 423 .B "   \-\-src 3049:9::9000:3101 \e"
 424 .br
 425 .B "   \-\-ah hmac\-md5\-96 \e"
 426 .br
 427 .BI "\ \ \ \-\-authkey\ 0x1234" "..." "2eda\ \e"
 428 .LP
 429 sets up an SA from
 430 .BR 3049:9::9000:3101
 431 to
 432 .BR 3049:9::9000:3100
 433 with an SPI of
 434 .BR 0x150
 435 and protocol
 436 .BR AH
 437 (50) using
 438 .BR MD5-96
 439 authentication transform, using an authentication key of
 440 .BI 0x1234 ... 2eda
 441 (see note above about abbreviated keys).
 442 .LP
 443 .B "ipsec spi \-\-said tun.987@192.168.100.100 \-\-del "
 444 .LP
 445 deletes an SA to
 446 .BR 192.168.100.100
 447 with an SPI of
 448 .BR 0x987
 449 and protocol
 450 .BR IPv4-in-IPv4
 451 (4).
 452 .LP
 453 .B "ipsec spi \-\-said tun:500@3049:9::1000:1 \-\-del "
 454 .LP
 455 deletes an SA to
 456 .BR 3049:9::1000:1
 457 with an SPI of
 458 .BR 0x500
 459 and protocol
 460 .BR IPv6-in-IPv6
 461 (4).
 462 .LP
 463 .SH FILES
 464 /proc/net/ipsec_spi, /usr/local/bin/ipsec
 465 .SH "SEE ALSO"
 466 ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8),
 467 ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)
 468 .SH HISTORY
 469 Written for the Linux FreeS/WAN project
 470 <http://www.freeswan.org/>
 471 by Richard Guy Briggs.
 472 .SH BUGS
 473 The syntax is messy and the transform naming needs work.
 474 .\"
 475 .\" $Log: spi.8,v $
 476 .\" Revision 1.31  2001/11/06 20:18:47  rgb
 477 .\" Added lifetime parameters.
 478 .\"
 479 .\" Revision 1.30  2001/10/24 03:23:32  rgb
 480 .\" Added lifetime option and parameters.
 481 .\"
 482 .\" Revision 1.29  2001/05/30 08:14:04  rgb
 483 .\" Removed vestiges of esp-null transforms.
 484 .\"
 485 .\" Revision 1.28  2000/11/29 19:15:20  rgb
 486 .\" Add --src requirement for inbound policy routing.
 487 .\"
 488 .\" Revision 1.27  2000/09/17 18:56:48  rgb
 489 .\" Added IPCOMP support.
 490 .\"
 491 .\" Revision 1.26  2000/09/13 15:54:32  rgb
 492 .\" Added Gerhard's ipv6 updates.
 493 .\"
 494 .\" Revision 1.25  2000/09/12 22:36:45  rgb
 495 .\" Gerhard's IPv6 support.
 496 .\"
 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.
 501 .\"
 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.
 505 .\"
 506 .\" Revision 1.22  1999/08/11 08:35:16  rgb
 507 .\" Update, deleting references to obsolete and insecure algorithms.
 508 .\"
 509 .\" Revision 1.21  1999/07/19 18:53:55  henry
 510 .\" improve font usage in key abbreviations
 511 .\"
 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
 515 .\"
 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.
 519 .\"