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 February 27, 2017
  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 timestamp 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 .\"
 274 .Pp
 275 .It Ar extensions
 276 take some of the following:
 277 .Bl -tag -width Fl -compact
 278 .\"
 279 .It Fl m Ar mode
 280 Specify a security protocol mode for use.
 281 .Ar mode
 282 is one of following:
 283 .Li transport , tunnel
 284 or
 285 .Li any .
 286 The default value is
 287 .Li any .
 288 .\"
 289 .It Fl r Ar size
 290 Specify window size of bytes for replay prevention.
 291 .Ar size
 292 must be decimal number in 32-bit word.
 293 If
 294 .Ar size
 295 is zero or not specified, replay check does not take place.
 296 .\"
 297 .It Fl u Ar id
 298 Specify the identifier of the policy entry in SPD.
 299 See
 300 .Ar policy .
 301 .\"
 302 .It Fl f Ar pad_option
 303 defines the content of the ESP padding.
 304 .Ar pad_option
 305 is one of following:
 306 .Bl -tag -width random-pad -compact
 307 .It Li zero-pad
 308 All of the padding are zero.
 309 .It Li random-pad
 310 A series of randomized values are set.
 311 .It Li seq-pad
 312 A series of sequential increasing numbers started from 1 are set.
 313 .El
 314 .\"
 315 .It Fl f Li nocyclic-seq
 316 Do not allow cyclic sequence number.
 317 .\"
 318 .It Fl lh Ar time
 319 .It Fl ls Ar time
 320 Specify hard/soft life time duration of the SA.
 321 .El
 322 .\"
 323 .Pp
 324 .It Ar algorithm
 325 .Bl -tag -width Fl -compact
 326 .It Fl E Ar ealgo Ar key
 327 Specify an encryption algorithm
 328 .Ar ealgo
 329 for ESP.
 330 .It Xo
 331 .Fl E Ar ealgo Ar key
 332 .Fl A Ar aalgo Ar key
 333 .Xc
 334 Specify a encryption algorithm
 335 .Ar ealgo ,
 336 as well as a payload authentication algorithm
 337 .Ar aalgo ,
 338 for ESP.
 339 .It Fl A Ar aalgo Ar key
 340 Specify an authentication algorithm for AH.
 341 .It Fl C Ar calgo Op Fl R
 342 Specify a compression algorithm for IPComp.
 343 If
 344 .Fl R
 345 is specified, the
 346 .Ar spi
 347 field value will be used as the IPComp CPI
 348 (compression parameter index)
 349 on wire as is.
 350 If
 351 .Fl R
 352 is not specified,
 353 the kernel will use well-known CPI on wire, and
 354 .Ar spi
 355 field will be used only as an index for kernel internal usage.
 356 .El
 357 .Pp
 358 .Ar key
 359 must be double-quoted character string, or a series of hexadecimal digits
 360 preceded by
 361 .Ql 0x .
 362 .Pp
 363 Possible values for
 364 .Ar ealgo ,
 365 .Ar aalgo
 366 and
 367 .Ar calgo
 368 are specified in separate section.
 369 .\"
 370 .Pp
 371 .It Ar src_range
 372 .It Ar dst_range
 373 These are selections of the secure communication specified as
 374 IPv4/v6 address or IPv4/v6 address range, and it may accompany
 375 TCP/UDP port specification.
 376 This takes the following form:
 377 .Bd -unfilled
 378 .Ar address
 379 .Ar address/prefixlen
 380 .Ar address[port]
 381 .Ar address/prefixlen[port]
 382 .Ed
 383 .Pp
 384 .Ar prefixlen
 385 and
 386 .Ar port
 387 must be a decimal number.
 388 The square brackets around
 389 .Ar port
 390 are necessary and are not manpage metacharacters.
 391 For FQDN resolution, the rules applicable to
 392 .Ar src
 393 and
 394 .Ar dst
 395 apply here as well.
 396 .\"
 397 .Pp
 398 .It Ar upperspec
 399 The upper layer protocol to be used.
 400 You can use one of the words in
 401 .Pa /etc/protocols
 402 as
 403 .Ar upperspec ,
 404 as well as
 405 .Li icmp6 ,
 406 .Li ip4 ,
 407 or
 408 .Li any .
 409 The word
 410 .Li any
 411 stands for
 412 .Dq any protocol .
 413 The protocol number may also be used to specify the
 414 .Ar upperspec .
 415 A type and code related to ICMPv6 may also be specified as an
 416 .Ar upperspec .
 417 The type is specified first, followed by a comma and then the relevant
 418 code.
 419 The specification must be placed after
 420 .Li icmp6 .
 421 The kernel considers a zero to be a wildcard but
 422 cannot distinguish between a wildcard and an ICMPv6
 423 type which is zero.
 424 The following example shows a policy where IPSec is not required for
 425 inbound Neighbor Solicitations:
 426 .Pp
 427 .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"
 428 .Pp
 429 NOTE:
 430 .Ar upperspec
 431 does not work in the forwarding case at this moment,
 432 as it requires extra reassembly at forwarding node,
 433 which is not implemented at this moment.
 434 Although there are many protocols in
 435 .Pa /etc/protocols ,
 436 protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec.
 437 .\"
 438 .Pp
 439 .It Ar policy
 440 .Ar policy
 441 is expressed in one of the following three formats:
 442 .Pp
 443 .Bl -tag -width 2n -compact
 444 .It Fl P Ar direction Li discard
 445 .It Fl P Ar direction Li none
 446 .It Xo Fl P Ar direction Li ipsec
 447 .Ar protocol/mode/src-dst/level Op ...
 448 .Xc
 449 .El
 450 .Pp
 451 The direction of a policy must be specified as
 452 one of:
 453 .Li out ,
 454 .Li in ,
 455 .Li discard ,
 456 .Li none ,
 457 or
 458 .Li ipsec .
 459 The
 460 .Li discard
 461 direction
 462 means that packets matching the supplied indices will be discarded
 463 while
 464 .Li none
 465 means that IPsec operations will not take place on the packet and
 466 .Li ipsec
 467 means that IPsec operation will take place onto the packet.
 468 The
 469 .Ar protocol/mode/src-dst/level
 470 statement gives the rule for how to process the packet.
 471 The
 472 .Ar protocol
 473 is specified as
 474 .Li ah ,
 475 .Li esp
 476 or
 477 .Li ipcomp .
 478 The
 479 .Ar mode
 480 is either
 481 .Li transport
 482 or
 483 .Li tunnel .
 484 If
 485 .Ar mode
 486 is
 487 .Li tunnel ,
 488 you must specify the end-point addresses of the SA as
 489 .Ar src
 490 and
 491 .Ar dst
 492 with a dash,
 493 .Sq - ,
 494 between the addresses.
 495 If
 496 .Ar mode
 497 is
 498 .Li transport ,
 499 both
 500 .Ar src
 501 and
 502 .Ar dst
 503 can be omitted.
 504 The
 505 .Ar level
 506 is one of the following:
 507 .Li default , use , require
 508 or
 509 .Li unique .
 510 If the SA is not available in every level, the kernel will request
 511 the SA from the key exchange daemon.
 512 A value of
 513 .Li default
 514 tells the kernel to use the system wide default protocol
 515 e.g.,\& the one from the
 516 .Li esp_trans_deflev
 517 sysctl variable, when the kernel processes the packet.
 518 A value of
 519 .Li use
 520 means that the kernel will use an SA if it is available,
 521 otherwise the kernel will pass the packet as it would normally.
 522 A value of
 523 .Li require
 524 means that an SA is required whenever the kernel sends a packet matched
 525 that matches the policy.
 526 The
 527 .Li unique
 528 level is the same as
 529 .Li require
 530 but, in addition, it allows the policy to bind with the unique out-bound SA.
 531 For example, if you specify the policy level
 532 .Li unique ,
 533 .Xr racoon 8
 534 will configure the SA for the policy.
 535 If you configure the SA by manual keying for that policy,
 536 you can put the decimal number as the policy identifier after
 537 .Li unique
 538 separated by colon
 539 .Ql :\&
 540 as in the following example:
 541 .Li unique:number .
 542 In order to bind this policy to the SA,
 543 .Li number
 544 must be between 1 and 32767,
 545 which corresponds to
 546 .Ar extensions Fl u
 547 of manual SA configuration.
 548 .Pp
 549 When you want to use an SA bundle, you can define multiple rules.
 550 For
 551 example, if an IP header was followed by an AH header followed by an
 552 ESP header followed by an upper layer protocol header, the rule would
 553 be:
 554 .Pp
 555 .Dl esp/transport//require ah/transport//require ;
 556 .Pp
 557 The rule order is very important.
 558 .Pp
 559 Note that
 560 .Dq Li discard
 561 and
 562 .Dq Li none
 563 are not in the syntax described in
 564 .Xr ipsec_set_policy 3 .
 565 There are small, but important, differences in the syntax.
 566 See
 567 .Xr ipsec_set_policy 3
 568 for details.
 569 .El
 570 .\"
 571 .Sh ALGORITHMS
 572 The following list shows the supported algorithms.
 573 The
 574 .Sy protocol
 575 and
 576 .Sy algorithm
 577 are almost completely orthogonal.
 578 The following list of authentication algorithms can be used as
 579 .Ar aalgo
 580 in the
 581 .Fl A Ar aalgo
 582 of the
 583 .Ar protocol
 584 parameter:
 585 .Bd -literal -offset indent
 586 algorithm       keylen (bits)   comment
 587 hmac-md5        128             ah: rfc2403
 588                 128             ah-old: rfc2085
 589 hmac-sha1       160             ah: rfc2404
 590                 160             ah-old: 128bit ICV (no document)
 591 keyed-md5       128             ah: 96bit ICV (no document)
 592                 128             ah-old: rfc1828
 593 keyed-sha1      160             ah: 96bit ICV (no document)
 594                 160             ah-old: 128bit ICV (no document)
 595 null            0 to 2048       for debugging
 596 hmac-sha2-256   256             ah: 128bit ICV (RFC4868)
 597                 256             ah-old: 128bit ICV (no document)
 598 hmac-sha2-384   384             ah: 192bit ICV (RFC4868)
 599                 384             ah-old: 128bit ICV (no document)
 600 hmac-sha2-512   512             ah: 256bit ICV (RFC4868)
 601                 512             ah-old: 128bit ICV (no document)
 602 hmac-ripemd160  160             ah: 96bit ICV (RFC2857)
 603                                 ah-old: 128bit ICV (no document)
 604 aes-xcbc-mac    128             ah: 96bit ICV (RFC3566)
 605                 128             ah-old: 128bit ICV (no document)
 606 tcp-md5         8 to 640        tcp: rfc2385
 607 .Ed
 608 .Pp
 609 The following is the list of encryption algorithms that can be used as the
 610 .Ar ealgo
 611 in the
 612 .Fl E Ar ealgo
 613 of the
 614 .Ar protocol
 615 parameter:
 616 .Bd -literal -offset indent
 617 algorithm       keylen (bits)   comment
 618 des-cbc         64              esp-old: rfc1829, esp: rfc2405
 619 3des-cbc        192             rfc2451
 620 null            0 to 2048       rfc2410
 621 blowfish-cbc    40 to 448       rfc2451
 622 cast128-cbc     40 to 128       rfc2451
 623 des-deriv       64              ipsec-ciph-des-derived-01
 624 rijndael-cbc    128/192/256     rfc3602
 625 aes-ctr         160/224/288     draft-ietf-ipsec-ciph-aes-ctr-03
 626 aes-gcm-16      160/224/288     rfc4106
 627 camellia-cbc    128/192/256     rfc4312
 628 .Ed
 629 .Pp
 630 Note that the first 128/192/256 bits of a key for
 631 .Li aes-ctr or aes-gcm-16
 632 will be used as AES key, and remaining 32 bits will be used as nonce.
 633 .Pp
 634 The following are the list of compression algorithms that can be used
 635 as the
 636 .Ar calgo
 637 in the
 638 .Fl C Ar calgo
 639 of the
 640 .Ar protocol
 641 parameter:
 642 .Bd -literal -offset indent
 643 algorithm       comment
 644 deflate         rfc2394
 645 .Ed
 646 .\"
 647 .Sh EXIT STATUS
 648 .Ex -std
 649 .\"
 650 .Sh EXAMPLES
 651 Add an ESP SA between two IPv6 addresses using the
 652 des-cbc encryption algorithm.
 653 .Bd -literal -offset indent
 654 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
 655         -E des-cbc 0x3ffe05014819ffff ;
 656 .Pp
 657 .Ed
 658 .\"
 659 Add an authentication SA between two FQDN specified hosts:
 660 .Bd -literal -offset indent
 661 add -6 myhost.example.com yourhost.example.com ah 123456
 662         -A hmac-sha1 "AH SA configuration!" ;
 663 .Pp
 664 .Ed
 665 Use both ESP and AH between two numerically specified hosts:
 666 .Bd -literal -offset indent
 667 add 10.0.11.41 10.0.11.33 esp 0x10001
 668         -E des-cbc 0x3ffe05014819ffff
 669         -A hmac-md5 "authentication!!" ;
 670 .Pp
 671 .Ed
 672 Get the SA information associated with first example above:
 673 .Bd -literal -offset indent
 674 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
 675 .Pp
 676 .Ed
 677 Flush all entries from the database:
 678 .Bd -literal -offset indent
 679 flush ;
 680 .Pp
 681 .Ed
 682 Dump the ESP entries from the database:
 683 .Bd -literal -offset indent
 684 dump esp ;
 685 .Pp
 686 .Ed
 687 Add a security policy between two networks that uses ESP in tunnel mode:
 688 .Bd -literal -offset indent
 689 spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
 690         -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
 691 .Pp
 692 .Ed
 693 Use TCP MD5 between two numerically specified hosts:
 694 .Bd -literal -offset indent
 695 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
 696 .Ed
 697 .\"
 698 .Sh SEE ALSO
 699 .Xr ipsec_set_policy 3 ,
 700 .Xr racoon 8 ,
 701 .Xr sysctl 8
 702 .Rs
 703 .%T "Changed manual key configuration for IPsec"
 704 .%U http://www.kame.net/newsletter/19991007/
 705 .%D "October 1999"
 706 .Re
 707 .\"
 708 .Sh HISTORY
 709 The
 710 .Nm
 711 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 712 The utility was completely re-designed in June 1998.
 713 It first appeared in
 714 .Fx 4.0 .
 715 .\"
 716 .Sh BUGS
 717 The
 718 .Nm
 719 utility
 720 should report and handle syntax errors better.
 721 .Pp
 722 For IPsec gateway configuration,
 723 .Ar src_range
 724 and
 725 .Ar dst_range
 726 with TCP/UDP port number do not work, as the gateway does not reassemble
 727 packets
 728 (cannot inspect upper-layer headers).