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