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 timestamp 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 .It Li tcp
 223 TCP-MD5 based on rfc2385
 224 .El
 225 .\"
 226 .Pp
 227 .It Ar spi
 228 Security Parameter Index (SPI) for the SAD and the SPD.
 229 It must be decimal number or hexadecimal number
 230 You cannot use the set of SPI values in the range 0 through 255.
 231 (with
 232 .Li 0x
 233 attached).
 234 TCP-MD5 associations must use 0x1000 and therefore only have per-host
 235 granularity at this time.
 236 .\"
 237 .Pp
 238 .It Ar extensions
 239 takes some of the following:
 240 .Bl -tag -width Fl -compact
 241 .\"
 242 .It Fl m Ar mode
 243 Specify a security protocol mode for use.
 244 .Ar mode
 245 is one of following:
 246 .Li transport , tunnel
 247 or
 248 .Li any .
 249 The default value is
 250 .Li any .
 251 .\"
 252 .It Fl r Ar size
 253 Specify window size of bytes for replay prevention.
 254 .Ar size
 255 must be decimal number in 32-bit word.
 256 If
 257 .Ar size
 258 is zero or not specified, replay check don't take place.
 259 .\"
 260 .It Fl u Ar id
 261 Specify the identifier of the policy entry in SPD.
 262 See
 263 .Ar policy .
 264 .\"
 265 .It Fl f Ar pad_option
 266 defines the content of the ESP padding.
 267 .Ar pad_option
 268 is one of following:
 269 .Bl -tag -width random-pad -compact
 270 .It Li zero-pad
 271 All of the padding are zero.
 272 .It Li random-pad
 273 A series of randomized values are set.
 274 .It Li seq-pad
 275 A series of sequential increasing numbers started from 1 are set.
 276 .El
 277 .\"
 278 .It Fl f Li nocyclic-seq
 279 Don't allow cyclic sequence number.
 280 .\"
 281 .It Fl lh Ar time
 282 .It Fl ls Ar time
 283 Specify hard/soft life time duration of the SA.
 284 .El
 285 .\"
 286 .Pp
 287 .It Ar algorithm
 288 .Bl -tag -width Fl -compact
 289 .It Fl E Ar ealgo Ar key
 290 Specify an encryption algorithm.
 291 .It Fl A Ar aalgo Ar key
 292 Specify an authentication algorithm.
 293 If
 294 .Fl A
 295 is used with
 296 .Ar protocol Li esp ,
 297 it will be treated as ESP payload authentication algorithm.
 298 .It Fl C Ar calgo Op Fl R
 299 Specify compression algorithm.
 300 If
 301 .Fl R
 302 is not specified with
 303 .Li ipcomp
 304 line, the kernel will use well-known IPComp CPI
 305 (compression parameter index)
 306 on IPComp CPI field on packets, and
 307 .Ar spi
 308 field will be ignored.
 309 .Ar spi
 310 field is only for kernel internal use in this case.
 311 .\"Therefore, compression protocol number will appear on IPComp CPI field.
 312 If
 313 .Fl R
 314 is used,
 315 the value on
 316 .Ar spi
 317 field will appear on IPComp CPI field on outgoing packets.
 318 .Ar spi
 319 field needs to be smaller than
 320 .Li 0x10000
 321 in this case.
 322 .El
 323 .Pp
 324 .Ar protocol Li esp
 325 accepts
 326 .Fl E
 327 and
 328 .Fl A .
 329 .Ar protocol Li esp-old
 330 accepts
 331 .Fl E
 332 only.
 333 .Ar protocol Li ah
 334 and
 335 .Li ah-old
 336 accept
 337 .Fl A
 338 only.
 339 .Ar protocol Li ipcomp
 340 accepts
 341 .Fl C
 342 only.
 343 .Pp
 344 .Ar key
 345 must be double-quoted character string or series of hexadecimal digits.
 346 .Pp
 347 Possible values for
 348 .Ar ealgo ,
 349 .Ar aalgo
 350 and
 351 .Ar calgo
 352 are specified in separate section.
 353 .\"
 354 .Pp
 355 .It Ar src_range
 356 .It Ar dst_range
 357 These are selections of the secure communication specified as
 358 IPv4/v6 address or IPv4/v6 address range, and it may accompany
 359 TCP/UDP port specification.
 360 This takes the following form:
 361 .Bd -literal
 362 .Ar address
 363 .Ar address/prefixlen
 364 .Ar address[port]
 365 .Ar address/prefixlen[port]
 366 .Ed
 367 .Pp
 368 .Ar prefixlen
 369 and
 370 .Ar port
 371 must be decimal number.
 372 The square bracket around
 373 .Ar port
 374 is really necessary.
 375 They are not manpage metacharacters.
 376 .Pp
 377 The
 378 .Nm
 379 utility does not consult hostname-to-address for arguments
 380 .Ar src
 381 and
 382 .Ar dst .
 383 They must be in numeric form.
 384 .\"
 385 .Pp
 386 .It Ar upperspec
 387 Upper-layer protocol to be used.
 388 You can use one of words in
 389 .Pa /etc/protocols
 390 as
 391 .Ar upperspec .
 392 Or
 393 .Li icmp6 ,
 394 .Li ip4 ,
 395 and
 396 .Li any
 397 can be specified.
 398 .Li any
 399 stands for
 400 .Dq any protocol .
 401 Also you can use the protocol number.
 402 .Pp
 403 NOTE:
 404 .Ar upperspec
 405 does not work against forwarding case at this moment,
 406 as it requires extra reassembly at forwarding node
 407 (not implemented at this moment).
 408 We have many protocols in
 409 .Pa /etc/protocols ,
 410 but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.
 411 You have to consider and be careful to use them.
 412 .Li icmp
 413 .Li tcp
 414 .Li udp
 415 all protocols
 416 .\"
 417 .Pp
 418 .It Ar policy
 419 .Ar policy
 420 is the one of following:
 421 .Bd -literal
 422 .Xo
 423 .Fl P Ar direction Li discard
 424 .Xc
 425 .Xo
 426 .Fl P Ar direction Li none
 427 .Xc
 428 .Xo
 429 .Fl P Ar direction Li ipsec Ar protocol/mode/src-dst/level
 430 .Xc
 431 .Ed
 432 .Pp
 433 You must specify the direction of its policy as
 434 .Ar direction .
 435 Either
 436 .Li out
 437 or
 438 .Li in
 439 are used.
 440 .Li discard
 441 means the packet matching indexes will be discarded.
 442 .Li none
 443 means that IPsec operation will not take place onto the packet.
 444 .Li ipsec
 445 means that IPsec operation will take place onto the packet.
 446 Either
 447 .Li ah ,
 448 .Li esp
 449 or
 450 .Li ipcomp
 451 is to be set as
 452 .Ar protocol .
 453 .Ar mode
 454 is either
 455 .Li transport
 456 or
 457 .Li tunnel .
 458 If
 459 .Ar mode
 460 is
 461 .Li tunnel ,
 462 you must specify the end-points addresses of the SA as
 463 .Ar src
 464 and
 465 .Ar dst
 466 with
 467 .Sq -
 468 between these addresses which is used to specify the SA to use.
 469 If
 470 .Ar mode
 471 is
 472 .Li transport ,
 473 both
 474 .Ar src
 475 and
 476 .Ar dst
 477 can be omitted.
 478 .Ar level
 479 is to be one of the following:
 480 .Li default , use , require
 481 or
 482 .Li unique .
 483 If the SA is not available in every level, the kernel will request
 484 getting SA to the key exchange daemon.
 485 .Li default
 486 means the kernel consults to the system wide default against protocol you
 487 specified, e.g.\&
 488 .Li esp_trans_deflev
 489 sysctl variable, when the kernel processes the packet.
 490 .Li use
 491 means that the kernel use a SA if it's available,
 492 otherwise the kernel keeps normal operation.
 493 .Li require
 494 means SA is required whenever the kernel sends a packet matched
 495 with the policy.
 496 .Li unique
 497 is the same to require.
 498 In addition, it allows the policy to bind with the unique out-bound SA.
 499 If you use the SA by manual keying,
 500 you can put the decimal number as the policy identifier after
 501 .Li unique
 502 separated by colon
 503 .Sq \:
 504 like the following;
 505 .Li unique:number .
 506 .Li number
 507 must be between 1 and 32767.
 508 It corresponds to
 509 .Ar extensions Fl u .
 510 .Pp
 511 Note that
 512 .Dq Li discard
 513 and
 514 .Dq Li none
 515 are not in the syntax described in
 516 .Xr ipsec_set_policy 3 .
 517 There are little differences in the syntax.
 518 See
 519 .Xr ipsec_set_policy 3
 520 for detail.
 521 .El
 522 .\"
 523 .Sh ALGORITHMS
 524 The following list shows the supported algorithms.
 525 .Sy protocol
 526 and
 527 .Sy algorithm
 528 are almost orthogonal.
 529 Followings are the list of authentication algorithms that can be used as
 530 .Ar aalgo
 531 in
 532 .Fl A Ar aalgo
 533 of
 534 .Ar protocol
 535 parameter:
 536 .Bd -literal -offset indent
 537 algorithm       keylen (bits)   comment
 538 hmac-md5        128             ah: rfc2403
 539                 128             ah-old: rfc2085
 540 hmac-sha1       160             ah: rfc2404
 541                 160             ah-old: 128bit ICV (no document)
 542 keyed-md5       128             ah: 96bit ICV (no document)
 543                 128             ah-old: rfc1828
 544 keyed-sha1      160             ah: 96bit ICV (no document)
 545                 160             ah-old: 128bit ICV (no document)
 546 null            0 to 2048       for debugging
 547 hmac-sha2-256   256             ah: 96bit ICV (no document)
 548                 256             ah-old: 128bit ICV (no document)
 549 hmac-sha2-384   384             ah: 96bit ICV (no document)
 550                 384             ah-old: 128bit ICV (no document)
 551 hmac-sha2-512   512             ah: 96bit ICV (no document)
 552                 512             ah-old: 128bit ICV (no document)
 553 tcp-md5         8 to 640        tcp: rfc2385
 554 .Ed
 555 .Pp
 556 Followings are the list of encryption algorithms that can be used as
 557 .Ar ealgo
 558 in
 559 .Fl E Ar ealgo
 560 of
 561 .Ar protocol
 562 parameter:
 563 .Bd -literal -offset indent
 564 algorithm       keylen (bits)   comment
 565 des-cbc         64              esp-old: rfc1829, esp: rfc2405
 566 3des-cbc        192             rfc2451
 567 simple          0 to 2048       rfc2410
 568 blowfish-cbc    40 to 448       rfc2451
 569 cast128-cbc     40 to 128       rfc2451
 570 des-deriv       64              ipsec-ciph-des-derived-01 (expired)
 571 3des-deriv      192             no document
 572 rijndael-cbc    128/192/256     draft-ietf-ipsec-ciph-aes-cbc-00
 573 .Ed
 574 .Pp
 575 Followings are the list of compression algorithms that can be used as
 576 .Ar calgo
 577 in
 578 .Fl C Ar calgo
 579 of
 580 .Ar protocol
 581 parameter:
 582 .Bd -literal -offset indent
 583 algorithm       comment
 584 deflate         rfc2394
 585 lzs             rfc2395
 586 .Ed
 587 .\"
 588 .Sh EXAMPLES
 589 .Bd -literal
 590 add     2001:db8:4819::1 2001:db8:481d::1 esp 123457
 591                 -E des-cbc "ESP SA!!" ;
 592
 593 add     2001:db8:4819::1 2001:db8: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     2001:db8:4819::1 2001:db8: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 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
 610
 611 .Ed
 612 .\"
 613 .Sh DIAGNOSTICS
 614 The command exits with 0 on success, and non-zero on errors.
 615 .\"
 616 .Sh SEE ALSO
 617 .Xr ipsec_set_policy 3 ,
 618 .Xr racoon 8 ,
 619 .Xr sysctl 8
 620 .\"
 621 .Sh HISTORY
 622 The
 623 .Nm
 624 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 625 The command was completely re-designed in June 1998.
 626 .\"
 627 .\" .Sh BUGS