usr.sbin/setkey/setkey.8

   1 .\"     $KAME: setkey.8,v 1.49 2001/05/18 05:49:51 sakane Exp $
   2 .\"     $FreeBSD: src/usr.sbin/setkey/setkey.8,v 1.4.2.15 2003/03/12 22:08:15 trhodes Exp $
   3 .\"     $DragonFly: src/usr.sbin/setkey/setkey.8,v 1.5 2006/03/26 22:56:58 swildner Exp $
   4 .\"
   5 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the project nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd November 20, 2000
  33 .Dt SETKEY 8
  34 .Os
  35 .\"
  36 .Sh NAME
  37 .Nm setkey
  38 .Nd "manually manipulate the IPsec SA/SP database"
  39 .\"
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl dv
  43 .Fl c
  44 .Nm
  45 .Op Fl dv
  46 .Fl f Ar filename
  47 .Nm
  48 .Op Fl adPlv
  49 .Fl D
  50 .Nm
  51 .Op Fl dPv
  52 .Fl F
  53 .Nm
  54 .Op Fl h
  55 .Fl x
  56 .\"
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 utility adds, updates, dumps, or flushes
  61 Security Association Database (SAD) entries
  62 as well as Security Policy Database (SPD) entries in the kernel.
  63 .Pp
  64 The
  65 .Nm
  66 utility takes a series of operations from the standard input
  67 (if invoked with
  68 .Fl c )
  69 or the file named
  70 .Ar filename
  71 (if invoked with
  72 .Fl f Ar filename ) .
  73 .Bl -tag -width Ds
  74 .It Fl D
  75 Dump the SAD entries.
  76 If with
  77 .Fl P ,
  78 the SPD entries are dumped.
  79 .It Fl F
  80 Flush the SAD entries.
  81 If with
  82 .Fl P ,
  83 the SPD entries are flushed.
  84 .It Fl a
  85 Dead SAD entries are usually not displayed with
  86 .Fl D .
  87 If with
  88 .Fl a ,
  89 the dead SAD entries will be displayed as well.
  90 A dead SAD entry means that
  91 it has been expired but remains
  92 because it is referenced by SPD entries.
  93 .It Fl d
  94 Enable to print debugging messages for command parser,
  95 without talking to kernel.
  96 It is not used usually.
  97 .It Fl x
  98 Loop forever and dump all the messages transmitted to
  99 .Dv PF_KEY
 100 socket.
 101 .Fl xx
 102 makes each timestamps unformatted.
 103 .It Fl h
 104 Add hexadecimal dump on
 105 .Fl x
 106 mode.
 107 .It Fl l
 108 Loop forever with short output on
 109 .Fl D .
 110 .It Fl v
 111 Be verbose.
 112 The program will dump messages exchanged on
 113 .Dv PF_KEY
 114 socket, including messages sent from other processes to the kernel.
 115 .El
 116 .Pp
 117 Operations have the following grammar.
 118 Note that lines starting with
 119 hashmarks ('#') are treated as comment lines.
 120 .Bl -tag -width Ds
 121 .It Xo
 122 .Li add
 123 .Ar src Ar dst Ar protocol Ar spi
 124 .Op Ar extensions
 125 .Ar algorithm...
 126 .Li ;
 127 .Xc
 128 Add an SAD entry.
 129 .\"
 130 .It Xo
 131 .Li get
 132 .Ar src Ar dst Ar protocol Ar spi
 133 .Li ;
 134 .Xc
 135 Show an SAD entry.
 136 .\"
 137 .It Xo
 138 .Li delete
 139 .Ar src Ar dst Ar protocol Ar spi
 140 .Li ;
 141 .Xc
 142 Remove an SAD entry.
 143 .\"
 144 .It Xo
 145 .Li deleteall
 146 .Ar src Ar dst Ar protocol
 147 .Li ;
 148 .Xc
 149 Remove all SAD entries that match the specification.
 150 .\"
 151 .It Xo
 152 .Li flush
 153 .Op Ar protocol
 154 .Li ;
 155 .Xc
 156 Clear all SAD entries matched by the options.
 157 .\"
 158 .It Xo
 159 .Li dump
 160 .Op Ar protocol
 161 .Li ;
 162 .Xc
 163 Dumps all SAD entries matched by the options.
 164 .\"
 165 .It Xo
 166 .Li spdadd
 167 .Ar src_range Ar dst_range Ar upperspec Ar policy
 168 .Li ;
 169 .Xc
 170 Add an SPD entry.
 171 .\"
 172 .It Xo
 173 .Li spddelete
 174 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
 175 .Li ;
 176 .Xc
 177 Delete an SPD entry.
 178 .\"
 179 .It Xo
 180 .Li spdflush
 181 .Li ;
 182 .Xc
 183 Clear all SPD entries.
 184 .\"
 185 .It Xo
 186 .Li spddump
 187 .Li ;
 188 .Xc
 189 Dumps all SPD entries.
 190 .El
 191 .\"
 192 .Pp
 193 Meta-arguments are as follows:
 194 .Pp
 195 .Bl -tag -compact -width Ds
 196 .It Ar src
 197 .It Ar dst
 198 Source/destination of the secure communication is specified as
 199 IPv4/v6 address.
 200 The
 201 .Nm
 202 utility does not consult hostname-to-address for arguments
 203 .Ar src
 204 and
 205 .Ar dst .
 206 They must be in numeric form.
 207 .\"
 208 .Pp
 209 .It Ar protocol
 210 .Ar protocol
 211 is one of following:
 212 .Bl -tag -width Fl -compact
 213 .It Li esp
 214 ESP based on rfc2405
 215 .It Li esp-old
 216 ESP based on rfc1827
 217 .It Li ah
 218 AH based on rfc2402
 219 .It Li ah-old
 220 AH based on rfc1826
 221 .It Li ipcomp
 222 IPCOMP
 223 .El
 224 .\"
 225 .Pp
 226 .It Ar spi
 227 Security Parameter Index (SPI) for the SAD and the SPD.
 228 It must be decimal number or hexadecimal number
 229 You cannot use the set of SPI values in the range 0 through 255.
 230 (with
 231 .Li 0x
 232 attached).
 233 .\"
 234 .Pp
 235 .It Ar extensions
 236 takes some of the following:
 237 .Bl -tag -width Fl -compact
 238 .\"
 239 .It Fl m Ar mode
 240 Specify a security protocol mode for use.
 241 .Ar mode
 242 is one of following:
 243 .Li transport , tunnel
 244 or
 245 .Li any .
 246 The default value is
 247 .Li any .
 248 .\"
 249 .It Fl r Ar size
 250 Specify window size of bytes for replay prevention.
 251 .Ar size
 252 must be decimal number in 32-bit word.
 253 If
 254 .Ar size
 255 is zero or not specified, replay check don't take place.
 256 .\"
 257 .It Fl u Ar id
 258 Specify the identifier of the policy entry in SPD.
 259 See
 260 .Ar policy .
 261 .\"
 262 .It Fl f Ar pad_option
 263 defines the content of the ESP padding.
 264 .Ar pad_option
 265 is one of following:
 266 .Bl -tag -width random-pad -compact
 267 .It Li zero-pad
 268 All of the padding are zero.
 269 .It Li random-pad
 270 A series of randomized values are set.
 271 .It Li seq-pad
 272 A series of sequential increasing numbers started from 1 are set.
 273 .El
 274 .\"
 275 .It Fl f Li nocyclic-seq
 276 Don't allow cyclic sequence number.
 277 .\"
 278 .It Fl lh Ar time
 279 .It Fl ls Ar time
 280 Specify hard/soft life time duration of the SA.
 281 .El
 282 .\"
 283 .Pp
 284 .It Ar algorithm
 285 .Bl -tag -width Fl -compact
 286 .It Fl E Ar ealgo Ar key
 287 Specify an encryption algorithm.
 288 .It Fl A Ar aalgo Ar key
 289 Specify an authentication algorithm.
 290 If
 291 .Fl A
 292 is used with
 293 .Ar protocol Li esp ,
 294 it will be treated as ESP payload authentication algorithm.
 295 .It Fl C Ar calgo Op Fl R
 296 Specify compression algorithm.
 297 If
 298 .Fl R
 299 is not specified with
 300 .Li ipcomp
 301 line, the kernel will use well-known IPComp CPI
 302 (compression parameter index)
 303 on IPComp CPI field on packets, and
 304 .Ar spi
 305 field will be ignored.
 306 .Ar spi
 307 field is only for kernel internal use in this case.
 308 .\"Therefore, compression protocol number will appear on IPComp CPI field.
 309 If
 310 .Fl R
 311 is used,
 312 the value on
 313 .Ar spi
 314 field will appear on IPComp CPI field on outgoing packets.
 315 .Ar spi
 316 field needs to be smaller than
 317 .Li 0x10000
 318 in this case.
 319 .El
 320 .Pp
 321 .Ar protocol Li esp
 322 accepts
 323 .Fl E
 324 and
 325 .Fl A .
 326 .Ar protocol Li esp-old
 327 accepts
 328 .Fl E
 329 only.
 330 .Ar protocol Li ah
 331 and
 332 .Li ah-old
 333 accept
 334 .Fl A
 335 only.
 336 .Ar protocol Li ipcomp
 337 accepts
 338 .Fl C
 339 only.
 340 .Pp
 341 .Ar key
 342 must be double-quoted character string or series of hexadecimal digits.
 343 .Pp
 344 Possible values for
 345 .Ar ealgo ,
 346 .Ar aalgo
 347 and
 348 .Ar calgo
 349 are specified in separate section.
 350 .\"
 351 .Pp
 352 .It Ar src_range
 353 .It Ar dst_range
 354 These are selections of the secure communication specified as
 355 IPv4/v6 address or IPv4/v6 address range, and it may accompany
 356 TCP/UDP port specification.
 357 This takes the following form:
 358 .Bd -literal -offset
 359 .Ar address
 360 .Ar address/prefixlen
 361 .Ar address[port]
 362 .Ar address/prefixlen[port]
 363 .Ed
 364 .Pp
 365 .Ar prefixlen
 366 and
 367 .Ar port
 368 must be decimal number.
 369 The square bracket around
 370 .Ar port
 371 is really necessary.
 372 They are not manpage metacharacters.
 373 .Pp
 374 The
 375 .Nm
 376 utility does not consult hostname-to-address for arguments
 377 .Ar src
 378 and
 379 .Ar dst .
 380 They must be in numeric form.
 381 .\"
 382 .Pp
 383 .It Ar upperspec
 384 Upper-layer protocol to be used.
 385 You can use one of words in
 386 .Pa /etc/protocols
 387 as
 388 .Ar upperspec .
 389 Or
 390 .Li icmp6 ,
 391 .Li ip4 ,
 392 and
 393 .Li any
 394 can be specified.
 395 .Li any
 396 stands for
 397 .Dq any protocol .
 398 Also you can use the protocol number.
 399 .Pp
 400 NOTE:
 401 .Ar upperspec
 402 does not work against forwarding case at this moment,
 403 as it requires extra reassembly at forwarding node
 404 (not implemented at this moment).
 405 We have many protocols in
 406 .Pa /etc/protocols ,
 407 but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.
 408 You have to consider and be careful to use them.
 409 .Li icmp
 410 .Li tcp
 411 .Li udp
 412 all protocols
 413 .\"
 414 .Pp
 415 .It Ar policy
 416 .Ar policy
 417 is the one of following:
 418 .Bd -literal -offset
 419 .Xo
 420 .Fl P Ar direction Li discard
 421 .Xc
 422 .Xo
 423 .Fl P Ar direction Li none
 424 .Xc
 425 .Xo
 426 .Fl P Ar direction Li ipsec Ar protocol/mode/src-dst/level
 427 .Xc
 428 .Ed
 429 .Pp
 430 You must specify the direction of its policy as
 431 .Ar direction .
 432 Either
 433 .Li out
 434 or
 435 .Li in
 436 are used.
 437 .Li discard
 438 means the packet matching indexes will be discarded.
 439 .Li none
 440 means that IPsec operation will not take place onto the packet.
 441 .Li ipsec
 442 means that IPsec operation will take place onto the packet.
 443 Either
 444 .Li ah ,
 445 .Li esp
 446 or
 447 .Li ipcomp
 448 is to be set as
 449 .Ar protocol .
 450 .Ar mode
 451 is either
 452 .Li transport
 453 or
 454 .Li tunnel .
 455 If
 456 .Ar mode
 457 is
 458 .Li tunnel ,
 459 you must specify the end-points addresses of the SA as
 460 .Ar src
 461 and
 462 .Ar dst
 463 with
 464 .Sq -
 465 between these addresses which is used to specify the SA to use.
 466 If
 467 .Ar mode
 468 is
 469 .Li transport ,
 470 both
 471 .Ar src
 472 and
 473 .Ar dst
 474 can be omitted.
 475 .Ar level
 476 is to be one of the following:
 477 .Li default , use , require
 478 or
 479 .Li unique .
 480 If the SA is not available in every level, the kernel will request
 481 getting SA to the key exchange daemon.
 482 .Li default
 483 means the kernel consults to the system wide default against protocol you
 484 specified, e.g.\&
 485 .Li esp_trans_deflev
 486 sysctl variable, when the kernel processes the packet.
 487 .Li use
 488 means that the kernel use a SA if it's available,
 489 otherwise the kernel keeps normal operation.
 490 .Li require
 491 means SA is required whenever the kernel sends a packet matched
 492 with the policy.
 493 .Li unique
 494 is the same to require.
 495 In addition, it allows the policy to bind with the unique out-bound SA.
 496 If you use the SA by manual keying,
 497 you can put the decimal number as the policy identifier after
 498 .Li unique
 499 separated by colon
 500 .Sq \:
 501 like the following;
 502 .Li unique:number .
 503 .Li number
 504 must be between 1 and 32767.
 505 It corresponds to
 506 .Ar extensions Fl u .
 507 .Pp
 508 Note that
 509 .Dq Li discard
 510 and
 511 .Dq Li none
 512 are not in the syntax described in
 513 .Xr ipsec_set_policy 3 .
 514 There are little differences in the syntax.
 515 See
 516 .Xr ipsec_set_policy 3
 517 for detail.
 518 .El
 519 .\"
 520 .Sh ALGORITHMS
 521 The following list shows the supported algorithms.
 522 .Sy protocol
 523 and
 524 .Sy algorithm
 525 are almost orthogonal.
 526 Followings are the list of authentication algorithms that can be used as
 527 .Ar aalgo
 528 in
 529 .Fl A Ar aalgo
 530 of
 531 .Ar protocol
 532 parameter:
 533 .Pp
 534 .Bd -literal -offset indent
 535 algorithm       keylen (bits)   comment
 536 hmac-md5        128             ah: rfc2403
 537                 128             ah-old: rfc2085
 538 hmac-sha1       160             ah: rfc2404
 539                 160             ah-old: 128bit ICV (no document)
 540 keyed-md5       128             ah: 96bit ICV (no document)
 541                 128             ah-old: rfc1828
 542 keyed-sha1      160             ah: 96bit ICV (no document)
 543                 160             ah-old: 128bit ICV (no document)
 544 null            0 to 2048       for debugging
 545 hmac-sha2-256   256             ah: 96bit ICV (no document)
 546                 256             ah-old: 128bit ICV (no document)
 547 hmac-sha2-384   384             ah: 96bit ICV (no document)
 548                 384             ah-old: 128bit ICV (no document)
 549 hmac-sha2-512   512             ah: 96bit ICV (no document)
 550                 512             ah-old: 128bit ICV (no document)
 551 .Ed
 552 .Pp
 553 Followings are the list of encryption algorithms that can be used as
 554 .Ar ealgo
 555 in
 556 .Fl E Ar ealgo
 557 of
 558 .Ar protocol
 559 parameter:
 560 .Pp
 561 .Bd -literal -offset indent
 562 algorithm       keylen (bits)   comment
 563 des-cbc         64              esp-old: rfc1829, esp: rfc2405
 564 3des-cbc        192             rfc2451
 565 simple          0 to 2048       rfc2410
 566 blowfish-cbc    40 to 448       rfc2451
 567 cast128-cbc     40 to 128       rfc2451
 568 des-deriv       64              ipsec-ciph-des-derived-01 (expired)
 569 3des-deriv      192             no document
 570 rijndael-cbc    128/192/256     draft-ietf-ipsec-ciph-aes-cbc-00
 571 .Ed
 572 .Pp
 573 Followings are the list of compression algorithms that can be used as
 574 .Ar calgo
 575 in
 576 .Fl C Ar calgo
 577 of
 578 .Ar protocol
 579 parameter:
 580 .Pp
 581 .Bd -literal -offset indent
 582 algorithm       comment
 583 deflate         rfc2394
 584 lzs             rfc2395
 585 .Ed
 586 .\"
 587 .Sh EXAMPLES
 588 .Bd -literal -offset
 589 add     3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
 590                 -E des-cbc "ESP SA!!" ;
 591
 592 add     3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
 593                 -A hmac-sha1 "AH SA configuration!" ;
 594
 595 add     10.0.11.41 10.0.11.33 esp 0x10001
 596                 -E des-cbc "ESP with"
 597                 -A hmac-md5 "authentication!!" ;
 598
 599 get     3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
 600
 601 flush ;
 602
 603 dump esp ;
 604
 605 spdadd  10.0.11.41/32[21] 10.0.11.33/32[any] any
 606                 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
 607
 608 .Ed
 609 .\"
 610 .Sh DIAGNOSTICS
 611 The command exits with 0 on success, and non-zero on errors.
 612 .\"
 613 .Sh SEE ALSO
 614 .Xr ipsec_set_policy 3 ,
 615 .Xr racoon 8 ,
 616 .Xr sysctl 8
 617 .\"
 618 .Sh HISTORY
 619 The
 620 .Nm
 621 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 622 The command was completely re-designed in June 1998.
 623 .\"
 624 .\" .Sh BUGS