setkey.tproj/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.12 2001/08/16 15:56:32 ru 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 .Nm
  58 adds, updates, dumps, or flushes
  59 Security Association Database (SAD) entries
  60 as well as Security Policy Database (SPD) entries in the kernel.
  61 .Pp
  62 .Nm
  63 takes a series of operations from the standard input
  64 (if invoked with
  65 .Fl c )
  66 or the file named
  67 .Ar filename
  68 (if invoked with
  69 .Fl f Ar filename ) .
  70 .Bl -tag -width Ds
  71 .It Fl D
  72 Dump the SAD entries.
  73 If with
  74 .Fl P ,
  75 the SPD entries are dumped.
  76 .It Fl F
  77 Flush the SAD entries.
  78 If with
  79 .Fl P ,
  80 the SPD entries are flushed.
  81 .It Fl a
  82 .Nm
  83 usually does not display dead SAD entries with
  84 .Fl D .
  85 If with
  86 .Fl a ,
  87 the dead SAD entries will be displayed as well.
  88 A dead SAD entry means that
  89 it has been expired but remains
  90 because it is referenced by SPD entries.
  91 .It Fl d
  92 Enable to print debugging messages for command parser,
  93 without talking to kernel.
  94 It is not used usually.
  95 .It Fl x
  96 Loop forever and dump all the messages transmitted to
  97 .Dv PF_KEY
  98 socket.
  99 .Fl xx
 100 makes each timestamps unformatted.
 101 .It Fl h
 102 Add hexadecimal dump on
 103 .Fl x
 104 mode.
 105 .It Fl l
 106 Loop forever with short output on
 107 .Fl D .
 108 .It Fl v
 109 Be verbose.
 110 The program will dump messages exchanged on
 111 .Dv PF_KEY
 112 socket, including messages sent from other processes to the kernel.
 113 .El
 114 .Pp
 115 Operations have the following grammar.
 116 Note that lines starting with
 117 hashmarks ('#') are treated as comment lines.
 118 .Bl -tag -width Ds
 119 .It Xo
 120 .Li add
 121 .Ar src Ar dst Ar protocol Ar spi
 122 .Op Ar extensions
 123 .Ar algorithm...
 124 .Li ;
 125 .Xc
 126 Add an SAD entry.
 127 .\"
 128 .It Xo
 129 .Li get
 130 .Ar src Ar dst Ar protocol Ar spi
 131 .Li ;
 132 .Xc
 133 Show an SAD entry.
 134 .\"
 135 .It Xo
 136 .Li delete
 137 .Ar src Ar dst Ar protocol Ar spi
 138 .Li ;
 139 .Xc
 140 Remove an SAD entry.
 141 .\"
 142 .It Xo
 143 .Li deleteall
 144 .Ar src Ar dst Ar protocol
 145 .Li ;
 146 .Xc
 147 Remove all SAD entries that match the specification.
 148 .\"
 149 .It Xo
 150 .Li flush
 151 .Op Ar protocol
 152 .Li ;
 153 .Xc
 154 Clear all SAD entries matched by the options.
 155 .\"
 156 .It Xo
 157 .Li dump
 158 .Op Ar protocol
 159 .Li ;
 160 .Xc
 161 Dumps all SAD entries matched by the options.
 162 .\"
 163 .It Xo
 164 .Li spdadd
 165 .Ar src_range Ar dst_range Ar upperspec Ar policy
 166 .Li ;
 167 .Xc
 168 Add an SPD entry.
 169 .\"
 170 .It Xo
 171 .Li spddelete
 172 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
 173 .Li ;
 174 .Xc
 175 Delete an SPD entry.
 176 .\"
 177 .It Xo
 178 .Li spdflush
 179 .Li ;
 180 .Xc
 181 Clear all SPD entries.
 182 .\"
 183 .It Xo
 184 .Li spddump
 185 .Li ;
 186 .Xc
 187 Dumps all SPD entries.
 188 .El
 189 .\"
 190 .Pp
 191 Meta-arguments are as follows:
 192 .Pp
 193 .Bl -tag -compact -width Ds
 194 .It Ar src
 195 .It Ar dst
 196 Source/destination of the secure communication is specified as
 197 IPv4/v6 address.
 198 .Nm
 199 does not consult hostname-to-address for arguments
 200 .Ar src
 201 and
 202 .Ar dst .
 203 They must be in numeric form.
 204 .\"
 205 .Pp
 206 .It Ar protocol
 207 .Ar protocol
 208 is one of following:
 209 .Bl -tag -width Fl -compact
 210 .It Li esp
 211 ESP based on rfc2405
 212 .It Li esp-old
 213 ESP based on rfc1827
 214 .It Li ah
 215 AH based on rfc2402
 216 .It Li ah-old
 217 AH based on rfc1826
 218 .It Li ipcomp
 219 IPCOMP
 220 .El
 221 .\"
 222 .Pp
 223 .It Ar spi
 224 Security Parameter Index (SPI) for the SAD and the SPD.
 225 It must be decimal number or hexadecimal number
 226 You cannot use the set of SPI values in the range 0 through 255.
 227 (with
 228 .Li 0x
 229 attached).
 230 .\"
 231 .Pp
 232 .It Ar extensions
 233 takes some of the following:
 234 .Bl -tag -width Fl -compact
 235 .\"
 236 .It Fl m Ar mode
 237 Specify a security protocol mode for use.
 238 .Ar mode
 239 is one of following:
 240 .Li transport , tunnel
 241 or
 242 .Li any .
 243 The default value is
 244 .Li any .
 245 .\"
 246 .It Fl r Ar size
 247 Specify window size of bytes for replay prevention.
 248 .Ar size
 249 must be decimal number in 32-bit word.
 250 If
 251 .Ar size
 252 is zero or not specified, replay check don't take place.
 253 .\"
 254 .It Fl u Ar id
 255 Specify the identifier of the policy entry in SPD.
 256 See
 257 .Ar policy .
 258 .\"
 259 .It Fl f Ar pad_option
 260 defines the content of the ESP padding.
 261 .Ar pad_option
 262 is one of following:
 263 .Bl -tag -width random-pad -compact
 264 .It Li zero-pad
 265 All of the padding are zero.
 266 .It Li random-pad
 267 A series of randomized values are set.
 268 .It Li seq-pad
 269 A series of sequential increasing numbers started from 1 are set.
 270 .El
 271 .\"
 272 .It Fl f Li nocyclic-seq
 273 Don't allow cyclic sequence number.
 274 .\"
 275 .It Fl lh Ar time
 276 .It Fl ls Ar time
 277 Specify hard/soft life time duration of the SA.
 278 .El
 279 .\"
 280 .Pp
 281 .It Ar algorithm
 282 .Bl -tag -width Fl -compact
 283 .It Fl E Ar ealgo Ar key
 284 Specify a encryption algorithm.
 285 .It Fl A Ar aalgo Ar key
 286 Specify a authentication algorithm.
 287 If
 288 .Fl A
 289 is used with
 290 .Ar protocol Li esp ,
 291 it will be treated as ESP payload authentication algorithm.
 292 .It Fl C Ar calgo Op Fl R
 293 Specify compression algorithm.
 294 If
 295 .Fl R
 296 is not specified with
 297 .Li ipcomp
 298 line, the kernel will use well-known IPComp CPI
 299 (compression parameter index)
 300 on IPComp CPI field on packets, and
 301 .Ar spi
 302 field will be ignored.
 303 .Ar spi
 304 field is only for kernel internal use in this case.
 305 .\"Therefore, compression protocol number will appear on IPComp CPI field.
 306 If
 307 .Fl R
 308 is used,
 309 the value on
 310 .Ar spi
 311 field will appear on IPComp CPI field on outgoing packets.
 312 .Ar spi
 313 field needs to be smaller than
 314 .Li 0x10000
 315 in this case.
 316 .El
 317 .Pp
 318 .Ar protocol Li esp
 319 accepts
 320 .Fl E
 321 and
 322 .Fl A .
 323 .Ar protocol Li esp-old
 324 accepts
 325 .Fl E
 326 only.
 327 .Ar protocol Li ah
 328 and
 329 .Li ah-old
 330 accept
 331 .Fl A
 332 only.
 333 .Ar protocol Li ipcomp
 334 accepts
 335 .Fl C
 336 only.
 337 .Pp
 338 .Ar key
 339 must be double-quoted character string or series of hexadecimal digits.
 340 .Pp
 341 Possible values for
 342 .Ar ealgo ,
 343 .Ar aalgo
 344 and
 345 .Ar calgo
 346 are specified in separate section.
 347 .\"
 348 .Pp
 349 .It Ar src_range
 350 .It Ar dst_range
 351 These are selections of the secure communication specified as
 352 IPv4/v6 address or IPv4/v6 address range, and it may accompany
 353 TCP/UDP port specification.
 354 This takes the following form:
 355 .Bd -literal -offset
 356 .Ar address
 357 .Ar address/prefixlen
 358 .Ar address[port]
 359 .Ar address/prefixlen[port]
 360 .Ed
 361 .Pp
 362 .Ar prefixlen
 363 and
 364 .Ar port
 365 must be decimal number.
 366 The square bracket around
 367 .Ar port
 368 is really necessary.
 369 They are not manpage metacharacters.
 370 .Pp
 371 .Nm
 372 does not consult hostname-to-address for arguments
 373 .Ar src
 374 and
 375 .Ar dst .
 376 They must be in numeric form.
 377 .\"
 378 .Pp
 379 .It Ar upperspec
 380 Upper-layer protocol to be used.
 381 You can use one of words in
 382 .Pa /etc/protocols
 383 as
 384 .Ar upperspec .
 385 Or
 386 .Li icmp6 ,
 387 .Li ip4 ,
 388 and
 389 .Li any
 390 can be specified.
 391 .Li any
 392 stands for
 393 .Dq any protocol .
 394 Also you can use the protocol number.
 395 .Pp
 396 NOTE:
 397 .Ar upperspec
 398 does not work against forwarding case at this moment,
 399 as it requires extra reassembly at forwarding node
 400 (not implemented at this moment).
 401 We have many protocols in
 402 .Pa /etc/protocols ,
 403 but protocols except of TCP, UDP and ICMP may not be suitable to use with IPSec.
 404 You have to consider and be careful to use them.
 405 .Li icmp
 406 .Li tcp
 407 .Li udp
 408 all protocols
 409 .\"
 410 .Pp
 411 .It Ar policy
 412 .Ar policy
 413 is the one of following:
 414 .Bd -literal -offset
 415 .Xo
 416 .Fl P
 417 .Ar direction
 418 .Li discard
 419 .Xc
 420 .Xo
 421 .Fl P
 422 .Ar direction
 423 .Li none
 424 .Xc
 425 .Xo
 426 .Fl P
 427 .Ar direction
 428 .Li ipsec
 429 .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 omited.
 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 .Pp
 522 .El
 523 .Pp
 524 .\"
 525 .Sh ALGORITHMS
 526 The following list shows the supported algorithms.
 527 .Sy protocol
 528 and
 529 .Sy algorithm
 530 are almost orthogonal.
 531 Followings are the list of authentication algorithms that can be used as
 532 .Ar aalgo
 533 in
 534 .Fl A Ar aalgo
 535 of
 536 .Ar protocol
 537 parameter:
 538 .Pp
 539 .Bd -literal -offset indent
 540 algorithm       keylen (bits)   comment
 541 hmac-md5        128             ah: rfc2403
 542                 128             ah-old: rfc2085
 543 hmac-sha1       160             ah: rfc2404
 544                 160             ah-old: 128bit ICV (no document)
 545 keyed-md5       128             ah: 96bit ICV (no document)
 546                 128             ah-old: rfc1828
 547 keyed-sha1      160             ah: 96bit ICV (no document)
 548                 160             ah-old: 128bit ICV (no document)
 549 null            0 to 2048       for debugging
 550 hmac-sha2-256   256             ah: 96bit ICV (no document)
 551                 256             ah-old: 128bit ICV (no document)
 552 hmac-sha2-384   384             ah: 96bit ICV (no document)
 553                 384             ah-old: 128bit ICV (no document)
 554 hmac-sha2-512   512             ah: 96bit ICV (no document)
 555                 512             ah-old: 128bit ICV (no document)
 556 .Ed
 557 .Pp
 558 Followings are the list of encryption algorithms that can be used as
 559 .Ar ealgo
 560 in
 561 .Fl E Ar ealgo
 562 of
 563 .Ar protocol
 564 parameter:
 565 .Pp
 566 .Bd -literal -offset indent
 567 algorithm       keylen (bits)   comment
 568 des-cbc         64              esp-old: rfc1829, esp: rfc2405
 569 3des-cbc        192             rfc2451
 570 simple          0 to 2048       rfc2410
 571 blowfish-cbc    40 to 448       rfc2451
 572 cast128-cbc     40 to 128       rfc2451
 573 des-deriv       64              ipsec-ciph-des-derived-01 (expired)
 574 3des-deriv      192             no document
 575 rijndael-cbc    128/192/256     draft-ietf-ipsec-ciph-aes-cbc-00
 576 .Ed
 577 .Pp
 578 Followings are the list of compression algorithms that can be used as
 579 .Ar calgo
 580 in
 581 .Fl C Ar calgo
 582 of
 583 .Ar protocol
 584 parameter:
 585 .Pp
 586 .Bd -literal -offset indent
 587 algorithm       comment
 588 deflate         rfc2394
 589 lzs             rfc2395
 590 .Ed
 591 .\"
 592 .Sh EXAMPLES
 593 .Bd -literal -offset
 594 add     3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
 595                 -E des-cbc "ESP SA!!" ;
 596
 597 add     3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
 598                 -A hmac-sha1 "AH SA configuration!" ;
 599
 600 add     10.0.11.41 10.0.11.33 esp 0x10001
 601                 -E des-cbc "ESP with"
 602                 -A hmac-md5 "authentication!!" ;
 603
 604 get     3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
 605
 606 flush ;
 607
 608 dump esp ;
 609
 610 spdadd  10.0.11.41/32[21] 10.0.11.33/32[any] any
 611                 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
 612
 613 .Ed
 614 .\"
 615 .Sh RETURN VALUES
 616 The command exits with 0 on success, and non-zero on errors.
 617 .\"
 618 .Sh SEE ALSO
 619 .Xr ipsec_set_policy 3 ,
 620 .Xr racoon 8 ,
 621 .Xr sysctl 8
 622 .\"
 623 .Sh HISTORY
 624 The
 625 .Nm
 626 command first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 627 The command was completely re-designed in June 1998.
 628 .\"
 629 .\" .Sh BUGS