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