sbin/setkey/setkey.8

   1 .\"     $KAME: setkey.8,v 1.89 2003/09/07 22:17:41 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  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 v
  43 .Fl c
  44 .Nm
  45 .Op Fl v
  46 .Fl f Ar filename
  47 .Nm
  48 .Op Fl aPlv
  49 .Fl D
  50 .Nm
  51 .Op Fl Pv
  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 indent
  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 The
  86 .Nm
  87 utility
  88 usually does not display dead SAD entries with
  89 .Fl D .
  90 If with
  91 .Fl a ,
  92 the dead SAD entries will be displayed as well.
  93 A dead SAD entry means that
  94 it has been expired but remains in the system
  95 because it is referenced by some SPD entries.
  96 .It Fl h
  97 Add hexadecimal dump on
  98 .Fl x
  99 mode.
 100 .It Fl l
 101 Loop forever with short output on
 102 .Fl D .
 103 .It Fl v
 104 Be verbose.
 105 The program will dump messages exchanged on
 106 .Dv PF_KEY
 107 socket, including messages sent from other processes to the kernel.
 108 .It Fl x
 109 Loop forever and dump all the messages transmitted to
 110 .Dv PF_KEY
 111 socket.
 112 .Fl xx
 113 makes each timestamps unformatted.
 114 .El
 115 .Ss Configuration syntax
 116 With
 117 .Fl c
 118 or
 119 .Fl f
 120 on the command line,
 121 .Nm
 122 accepts the following configuration syntax.
 123 Lines starting with hash signs
 124 .Pq Ql #
 125 are treated as comment lines.
 126 .Bl -tag -width indent
 127 .It Xo
 128 .Li add
 129 .Op Fl 46n
 130 .Ar src Ar dst Ar protocol Ar spi
 131 .Op Ar extensions
 132 .Ar algorithm ...
 133 .Li ;
 134 .Xc
 135 Add an SAD entry.
 136 .Li add
 137 can fail with multiple reasons,
 138 including when the key length does not match the specified algorithm.
 139 .\"
 140 .It Xo
 141 .Li get
 142 .Op Fl 46n
 143 .Ar src Ar dst Ar protocol Ar spi
 144 .Li ;
 145 .Xc
 146 Show an SAD entry.
 147 .\"
 148 .It Xo
 149 .Li delete
 150 .Op Fl 46n
 151 .Ar src Ar dst Ar protocol Ar spi
 152 .Li ;
 153 .Xc
 154 Remove an SAD entry.
 155 .\"
 156 .It Xo
 157 .Li deleteall
 158 .Op Fl 46n
 159 .Ar src Ar dst Ar protocol
 160 .Li ;
 161 .Xc
 162 Remove all SAD entries that match the specification.
 163 .\"
 164 .It Xo
 165 .Li flush
 166 .Op Ar protocol
 167 .Li ;
 168 .Xc
 169 Clear all SAD entries matched by the options.
 170 .Fl F
 171 on the command line achieves the same functionality.
 172 .\"
 173 .It Xo
 174 .Li dump
 175 .Op Ar protocol
 176 .Li ;
 177 .Xc
 178 Dumps all SAD entries matched by the options.
 179 .Fl D
 180 on the command line achieves the same functionality.
 181 .\"
 182 .It Xo
 183 .Li spdadd
 184 .Op Fl 46n
 185 .Ar src_range Ar dst_range Ar upperspec Ar policy
 186 .Li ;
 187 .Xc
 188 Add an SPD entry.
 189 .\"
 190 .It Xo
 191 .Li spddelete
 192 .Op Fl 46n
 193 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
 194 .Li ;
 195 .Xc
 196 Delete an SPD entry.
 197 .\"
 198 .It Xo
 199 .Li spdflush
 200 .Li ;
 201 .Xc
 202 Clear all SPD entries.
 203 .Fl FP
 204 on the command line achieves the same functionality.
 205 .\"
 206 .It Xo
 207 .Li spddump
 208 .Li ;
 209 .Xc
 210 Dumps all SPD entries.
 211 .Fl DP
 212 on the command line achieves the same functionality.
 213 .El
 214 .\"
 215 .Pp
 216 Meta-arguments are as follows:
 217 .Pp
 218 .Bl -tag -compact -width indent
 219 .It Ar src
 220 .It Ar dst
 221 Source/destination of the secure communication is specified as
 222 IPv4/v6 address.
 223 The
 224 .Nm
 225 utility
 226 can resolve a FQDN into numeric addresses.
 227 If the FQDN resolves into multiple addresses,
 228 .Nm
 229 will install multiple SAD/SPD entries into the kernel
 230 by trying all possible combinations.
 231 .Fl 4 ,
 232 .Fl 6
 233 and
 234 .Fl n
 235 restricts the address resolution of FQDN in certain ways.
 236 .Fl 4
 237 and
 238 .Fl 6
 239 restrict results into IPv4/v6 addresses only, respectively.
 240 .Fl n
 241 avoids FQDN resolution and requires addresses to be numeric addresses.
 242 .\"
 243 .Pp
 244 .It Ar protocol
 245 .Ar protocol
 246 is one of following:
 247 .Bl -tag -width Fl -compact
 248 .It Li esp
 249 ESP based on rfc2406
 250 .It Li esp-old
 251 ESP based on rfc1827
 252 .It Li ah
 253 AH based on rfc2402
 254 .It Li ah-old
 255 AH based on rfc1826
 256 .It Li ipcomp
 257 IPComp
 258 .It Li tcp
 259 TCP-MD5 based on rfc2385
 260 .El
 261 .\"
 262 .Pp
 263 .It Ar spi
 264 Security Parameter Index
 265 (SPI)
 266 for the SAD and the SPD.
 267 .Ar spi
 268 must be a decimal number, or a hexadecimal number with
 269 .Ql 0x
 270 prefix.
 271 SPI values between 0 and 255 are reserved for future use by IANA
 272 and they cannot be used.
 273 TCP-MD5 associations must use 0x1000 and therefore only have per-host
 274 granularity at this time.
 275 .\"
 276 .Pp
 277 .It Ar extensions
 278 take some of the following:
 279 .Bl -tag -width Fl -compact
 280 .\"
 281 .It Fl m Ar mode
 282 Specify a security protocol mode for use.
 283 .Ar mode
 284 is one of following:
 285 .Li transport , tunnel
 286 or
 287 .Li any .
 288 The default value is
 289 .Li any .
 290 .\"
 291 .It Fl r Ar size
 292 Specify window size of bytes for replay prevention.
 293 .Ar size
 294 must be decimal number in 32-bit word.
 295 If
 296 .Ar size
 297 is zero or not specified, replay check does not take place.
 298 .\"
 299 .It Fl u Ar id
 300 Specify the identifier of the policy entry in SPD.
 301 See
 302 .Ar policy .
 303 .\"
 304 .It Fl f Ar pad_option
 305 defines the content of the ESP padding.
 306 .Ar pad_option
 307 is one of following:
 308 .Bl -tag -width random-pad -compact
 309 .It Li zero-pad
 310 All of the padding are zero.
 311 .It Li random-pad
 312 A series of randomized values are set.
 313 .It Li seq-pad
 314 A series of sequential increasing numbers started from 1 are set.
 315 .El
 316 .\"
 317 .It Fl f Li nocyclic-seq
 318 Do not allow cyclic sequence number.
 319 .\"
 320 .It Fl lh Ar time
 321 .It Fl ls Ar time
 322 Specify hard/soft life time duration of the SA.
 323 .El
 324 .\"
 325 .Pp
 326 .It Ar algorithm
 327 .Bl -tag -width Fl -compact
 328 .It Fl E Ar ealgo Ar key
 329 Specify an encryption algorithm
 330 .Ar ealgo
 331 for ESP.
 332 .It Xo
 333 .Fl E Ar ealgo Ar key
 334 .Fl A Ar aalgo Ar key
 335 .Xc
 336 Specify a encryption algorithm
 337 .Ar ealgo ,
 338 as well as a payload authentication algorithm
 339 .Ar aalgo ,
 340 for ESP.
 341 .It Fl A Ar aalgo Ar key
 342 Specify an authentication algorithm for AH.
 343 .It Fl C Ar calgo Op Fl R
 344 Specify a compression algorithm for IPComp.
 345 If
 346 .Fl R
 347 is specified,
 348 .Ar spi
 349 field value will be used as the IPComp CPI
 350 (compression parameter index)
 351 on wire as is.
 352 If
 353 .Fl R
 354 is not specified,
 355 the kernel will use well-known CPI on wire, and
 356 .Ar spi
 357 field will be used only as an index for kernel internal usage.
 358 .El
 359 .Pp
 360 .Ar key
 361 must be double-quoted character string, or a series of hexadecimal digits
 362 preceded by
 363 .Ql 0x .
 364 .Pp
 365 Possible values for
 366 .Ar ealgo ,
 367 .Ar aalgo
 368 and
 369 .Ar calgo
 370 are specified in separate section.
 371 .\"
 372 .Pp
 373 .It Ar src_range
 374 .It Ar dst_range
 375 These are selections of the secure communication specified as
 376 IPv4/v6 address or IPv4/v6 address range, and it may accompany
 377 TCP/UDP port specification.
 378 This takes the following form:
 379 .Bd -unfilled
 380 .Ar address
 381 .Ar address/prefixlen
 382 .Ar address[port]
 383 .Ar address/prefixlen[port]
 384 .Ed
 385 .Pp
 386 .Ar prefixlen
 387 and
 388 .Ar port
 389 must be decimal number.
 390 The square bracket around
 391 .Ar port
 392 is really necessary.
 393 They are not manpage metacharacters.
 394 For FQDN resolution, the rules applicable to
 395 .Ar src
 396 and
 397 .Ar dst
 398 apply here as well.
 399 .\"
 400 .Pp
 401 .It Ar upperspec
 402 Upper-layer protocol to be used.
 403 You can use one of words in
 404 .Pa /etc/protocols
 405 as
 406 .Ar upperspec .
 407 Or
 408 .Li icmp6 ,
 409 .Li ip4 ,
 410 and
 411 .Li any
 412 can be specified.
 413 .Li any
 414 stands for
 415 .Dq any protocol .
 416 Also you can use the protocol number.
 417 You can specify a type and/or a code of ICMPv6 when
 418 upper-layer protocol is ICMPv6.
 419 The specification can be placed after
 420 .Li icmp6 .
 421 A type is separated with a code by single comma.
 422 A code must be specified anytime.
 423 When a zero is specified, the kernel deals with it as a wildcard.
 424 Note that the kernel cannot distinguish a wildcard from that a type
 425 of ICMPv6 is zero.
 426 For example, the following means the policy does not require IPsec
 427 for any inbound Neighbor Solicitation:
 428 .Pp
 429 .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"
 430 .Pp
 431 NOTE:
 432 .Ar upperspec
 433 does not work against forwarding case at this moment,
 434 as it requires extra reassembly at forwarding node
 435 (not implemented at this moment).
 436 We have many protocols in
 437 .Pa /etc/protocols ,
 438 but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.
 439 You have to consider and be careful to use them.
 440 .\"
 441 .Pp
 442 .It Ar policy
 443 .Ar policy
 444 is the one of the following three formats:
 445 .Bd -ragged -offset indent
 446 .It Fl P Ar direction Li discard
 447 .It Fl P Ar direction Li none
 448 .It Xo Fl P Ar direction Li ipsec
 449 .Ar protocol/mode/src-dst/level Op ...
 450 .Xc
 451 .Ed
 452 .Pp
 453 You must specify the direction of its policy as
 454 .Ar direction .
 455 Either
 456 .Li out
 457 or
 458 .Li in
 459 are used.
 460 .Li discard
 461 means the packet matching indexes will be discarded.
 462 .Li none
 463 means that IPsec operation will not take place onto the packet.
 464 .Li ipsec
 465 means that IPsec operation will take place onto the packet.
 466 The part of
 467 .Ar protocol/mode/src-dst/level
 468 specifies the rule how to process the packet.
 469 Either
 470 .Li ah ,
 471 .Li esp
 472 or
 473 .Li ipcomp
 474 is to be set as
 475 .Ar protocol .
 476 .Ar mode
 477 is either
 478 .Li transport
 479 or
 480 .Li tunnel .
 481 If
 482 .Ar mode
 483 is
 484 .Li tunnel ,
 485 you must specify the end-points addresses of the SA as
 486 .Ar src
 487 and
 488 .Ar dst
 489 with
 490 .Sq -
 491 between these addresses which is used to specify the SA to use.
 492 If
 493 .Ar mode
 494 is
 495 .Li transport ,
 496 both
 497 .Ar src
 498 and
 499 .Ar dst
 500 can be omitted.
 501 .Ar level
 502 is to be one of the following:
 503 .Li default , use , require
 504 or
 505 .Li unique .
 506 If the SA is not available in every level, the kernel will request
 507 getting SA to the key exchange daemon.
 508 .Li default
 509 means the kernel consults to the system wide default against protocol you
 510 specified, e.g.,
 511 .Li esp_trans_deflev
 512 sysctl variable, when the kernel processes the packet.
 513 .Li use
 514 means that the kernel use a SA if it is available,
 515 otherwise the kernel keeps normal operation.
 516 .Li require
 517 means SA is required whenever the kernel sends a packet matched
 518 with the policy.
 519 .Li unique
 520 is the same to require.
 521 In addition, it allows the policy to bind with the unique out-bound SA.
 522 You just specify the policy level
 523 .Li unique ,
 524 .Xr racoon 8
 525 will configure the SA for the policy.
 526 If you configure the SA by manual keying for that policy,
 527 you can put the decimal number as the policy identifier after
 528 .Li unique
 529 separated by colon
 530 .Ql :\&
 531 like the following;
 532 .Li unique:number .
 533 In order to bind this policy to the SA,
 534 .Li number
 535 must be between 1 and 32767.
 536 It corresponds to
 537 .Ar extensions Fl u
 538 of the manual SA configuration.
 539 When you want to use SA bundle, you can define multiple rules.
 540 For example, if an IP header was followed by AH header followed by ESP header
 541 followed by an upper layer protocol header, the rule
 542 would be:
 543 .Dl esp/transport//require ah/transport//require ;
 544 The rule order is very important.
 545 .Pp
 546 Note that
 547 .Dq Li discard
 548 and
 549 .Dq Li none
 550 are not in the syntax described in
 551 .Xr ipsec_set_policy 3 .
 552 There are little differences in the syntax.
 553 See
 554 .Xr ipsec_set_policy 3
 555 for detail.
 556 .Pp
 557 .El
 558 .Pp
 559 .\"
 560 .Sh ALGORITHMS
 561 The following list shows the supported algorithms.
 562 .Sy protocol
 563 and
 564 .Sy algorithm
 565 are almost orthogonal.
 566 Followings are the list of authentication algorithms that can be used as
 567 .Ar aalgo
 568 in
 569 .Fl A Ar aalgo
 570 of
 571 .Ar protocol
 572 parameter:
 573 .Pp
 574 .Bd -literal -offset indent
 575 algorithm       keylen (bits)   comment
 576 hmac-md5        128             ah: rfc2403
 577                 128             ah-old: rfc2085
 578 hmac-sha1       160             ah: rfc2404
 579                 160             ah-old: 128bit ICV (no document)
 580 keyed-md5       128             ah: 96bit ICV (no document)
 581                 128             ah-old: rfc1828
 582 keyed-sha1      160             ah: 96bit ICV (no document)
 583                 160             ah-old: 128bit ICV (no document)
 584 null            0 to 2048       for debugging
 585 hmac-sha2-256   256             ah: 96bit ICV
 586                                 (draft-ietf-ipsec-ciph-sha-256-00)
 587                 256             ah-old: 128bit ICV (no document)
 588 hmac-sha2-384   384             ah: 96bit ICV (no document)
 589                 384             ah-old: 128bit ICV (no document)
 590 hmac-sha2-512   512             ah: 96bit ICV (no document)
 591                 512             ah-old: 128bit ICV (no document)
 592 hmac-ripemd160  160             ah: 96bit ICV (RFC2857)
 593                                 ah-old: 128bit ICV (no document)
 594 aes-xcbc-mac    128             ah: 96bit ICV (RFC3566)
 595                 128             ah-old: 128bit ICV (no document)
 596 tcp-md5         8 to 640        tcp: rfc2385
 597 .Ed
 598 .Pp
 599 Followings are the list of encryption algorithms that can be used as
 600 .Ar ealgo
 601 in
 602 .Fl E Ar ealgo
 603 of
 604 .Ar protocol
 605 parameter:
 606 .Pp
 607 .Bd -literal -offset indent
 608 algorithm       keylen (bits)   comment
 609 des-cbc         64              esp-old: rfc1829, esp: rfc2405
 610 3des-cbc        192             rfc2451
 611 null            0 to 2048       rfc2410
 612 blowfish-cbc    40 to 448       rfc2451
 613 cast128-cbc     40 to 128       rfc2451
 614 des-deriv       64              ipsec-ciph-des-derived-01
 615 3des-deriv      192             no document
 616 rijndael-cbc    128/192/256     rfc3602
 617 aes-ctr         160/224/288     draft-ietf-ipsec-ciph-aes-ctr-03
 618 .Ed
 619 .Pp
 620 Note that the first 128 bits of a key for
 621 .Li aes-ctr
 622 will be used as AES key, and remaining 32 bits will be used as nonce.
 623 .Pp
 624 Followings are the list of compression algorithms that can be used as
 625 .Ar calgo
 626 in
 627 .Fl C Ar calgo
 628 of
 629 .Ar protocol
 630 parameter:
 631 .Pp
 632 .Bd -literal -offset indent
 633 algorithm       comment
 634 deflate         rfc2394
 635 .Ed
 636 .\"
 637 .Sh EXIT STATUS
 638 .Ex -std
 639 .\"
 640 .Sh EXAMPLES
 641 .Bd -literal -offset
 642 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
 643         -E des-cbc 0x3ffe05014819ffff ;
 644
 645 add -6 myhost.example.com yourhost.example.com ah 123456
 646         -A hmac-sha1 "AH SA configuration!" ;
 647
 648 add 10.0.11.41 10.0.11.33 esp 0x10001
 649         -E des-cbc 0x3ffe05014819ffff
 650         -A hmac-md5 "authentication!!" ;
 651
 652 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
 653
 654 flush ;
 655
 656 dump esp ;
 657
 658 spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
 659         -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
 660
 661 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
 662
 663 .Ed
 664 .\"
 665 .Sh SEE ALSO
 666 .Xr ipsec_set_policy 3 ,
 667 .Xr racoon 8 ,
 668 .Xr sysctl 8
 669 .Rs
 670 .%T "Changed manual key configuration for IPsec"
 671 .%O "http://www.kame.net/newsletter/19991007/"
 672 .%D "October 1999"
 673 .Re
 674 .\"
 675 .Sh HISTORY
 676 The
 677 .Nm
 678 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 679 The utility was completely re-designed in June 1998.
 680 .\"
 681 .Sh BUGS
 682 The
 683 .Nm
 684 utility
 685 should report and handle syntax errors better.
 686 .Pp
 687 For IPsec gateway configuration,
 688 .Ar src_range
 689 and
 690 .Ar dst_range
 691 with TCP/UDP port number do not work, as the gateway does not reassemble
 692 packets
 693 (cannot inspect upper-layer headers).