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 March 7, 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 Pgltv 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 58The 59.Nm 60utility adds, updates, dumps, or flushes 61Security Association Database (SAD) entries 62as well as Security Policy Database (SPD) entries in the kernel. 63.Pp 64The 65.Nm 66utility takes a series of operations from the standard input 67(if invoked with 68.Fl c ) 69or the file named 70.Ar filename 71(if invoked with 72.Fl f Ar filename ) . 73.Bl -tag -width indent 74.It Fl D 75Dump the SAD entries. 76If with 77.Fl P , 78the SPD entries are dumped. 79.It Fl F 80Flush the SAD entries. 81If with 82.Fl P , 83the SPD entries are flushed. 84.It Fl g 85Only SPD entries with global scope are dumped with 86.Fl D 87and 88.Fl P 89flags. 90.It Fl t 91Only SPD entries with ifnet scope are dumped with 92.Fl D 93and 94.Fl P 95flags. 96Such SPD entries are linked to the corresponding 97.Xr if_ipsec 4 98virtual tunneling interface. 99.It Fl h 100Add hexadecimal dump on 101.Fl x 102mode. 103.It Fl l 104Loop forever with short output on 105.Fl D . 106.It Fl v 107Be verbose. 108The program will dump messages exchanged on 109.Dv PF_KEY 110socket, including messages sent from other processes to the kernel. 111.It Fl x 112Loop forever and dump all the messages transmitted to 113.Dv PF_KEY 114socket. 115.Fl xx 116makes each timestamp unformatted. 117.El 118.Ss Configuration syntax 119With 120.Fl c 121or 122.Fl f 123on the command line, 124.Nm 125accepts the following configuration syntax. 126Lines starting with hash signs 127.Pq Ql # 128are treated as comment lines. 129.Bl -tag -width indent 130.It Xo 131.Li add 132.Op Fl 46n 133.Ar src Ar dst Ar protocol Ar spi 134.Op Ar extensions 135.Ar algorithm ... 136.Li \&; 137.Xc 138Add an SAD entry. 139.Li add 140can fail with multiple reasons, 141including when the key length does not match the specified algorithm. 142.\" 143.It Xo 144.Li get 145.Op Fl 46n 146.Ar src Ar dst Ar protocol Ar spi 147.Li \&; 148.Xc 149Show an SAD entry. 150.\" 151.It Xo 152.Li delete 153.Op Fl 46n 154.Ar src Ar dst Ar protocol Ar spi 155.Li \&; 156.Xc 157Remove an SAD entry. 158.\" 159.It Xo 160.Li deleteall 161.Op Fl 46n 162.Ar src Ar dst Ar protocol 163.Li \&; 164.Xc 165Remove all SAD entries that match the specification. 166.\" 167.It Xo 168.Li flush 169.Op Ar protocol 170.Li \&; 171.Xc 172Clear all SAD entries matched by the options. 173.Fl F 174on the command line achieves the same functionality. 175.\" 176.It Xo 177.Li dump 178.Op Ar protocol 179.Li \&; 180.Xc 181Dumps all SAD entries matched by the options. 182.Fl D 183on the command line achieves the same functionality. 184.\" 185.It Xo 186.Li spdadd 187.Op Fl 46n 188.Ar src_range Ar dst_range Ar upperspec Ar policy 189.Li \&; 190.Xc 191Add an SPD entry. 192.\" 193.It Xo 194.Li spddelete 195.Op Fl 46n 196.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction 197.Li \&; 198.Xc 199Delete an SPD entry. 200.\" 201.It Xo 202.Li spdflush 203.Li \&; 204.Xc 205Clear all SPD entries. 206.Fl FP 207on the command line achieves the same functionality. 208.\" 209.It Xo 210.Li spddump 211.Li \&; 212.Xc 213Dumps all SPD entries. 214.Fl DP 215on the command line achieves the same functionality. 216.El 217.\" 218.Pp 219Meta-arguments are as follows: 220.Pp 221.Bl -tag -compact -width indent 222.It Ar src 223.It Ar dst 224Source/destination of the secure communication is specified as 225IPv4/v6 address. 226The 227.Nm 228utility 229can resolve a FQDN into numeric addresses. 230If the FQDN resolves into multiple addresses, 231.Nm 232will install multiple SAD/SPD entries into the kernel 233by trying all possible combinations. 234.Fl 4 , 235.Fl 6 236and 237.Fl n 238restricts the address resolution of FQDN in certain ways. 239.Fl 4 240and 241.Fl 6 242restrict results into IPv4/v6 addresses only, respectively. 243.Fl n 244avoids FQDN resolution and requires addresses to be numeric addresses. 245.\" 246.Pp 247.It Ar protocol 248.Ar protocol 249is one of following: 250.Bl -tag -width Fl -compact 251.It Li esp 252ESP based on rfc2406 253.It Li esp-old 254ESP based on rfc1827 255.It Li ah 256AH based on rfc2402 257.It Li ah-old 258AH based on rfc1826 259.It Li ipcomp 260IPComp 261.It Li tcp 262TCP-MD5 based on rfc2385 263.El 264.\" 265.Pp 266.It Ar spi 267Security Parameter Index 268(SPI) 269for the SAD and the SPD. 270.Ar spi 271must be a decimal number, or a hexadecimal number with 272.Ql 0x 273prefix. 274SPI values between 0 and 255 are reserved for future use by IANA 275and they cannot be used. 276.\" 277.Pp 278.It Ar extensions 279take some of the following: 280.Bl -tag -width Fl -compact 281.\" 282.It Fl m Ar mode 283Specify a security protocol mode for use. 284.Ar mode 285is one of following: 286.Li transport , tunnel 287or 288.Li any . 289The default value is 290.Li any . 291.\" 292.It Fl r Ar size 293Specify window size of bytes for replay prevention. 294.Ar size 295must be decimal number in 32-bit word. 296If 297.Ar size 298is zero or not specified, replay check does not take place. 299.\" 300.It Fl u Ar id 301Specify the identifier of the policy entry in SPD. 302See 303.Ar policy . 304.\" 305.It Fl f Ar pad_option 306defines the content of the ESP padding. 307.Ar pad_option 308is one of following: 309.Bl -tag -width random-pad -compact 310.It Li zero-pad 311All of the padding are zero. 312.It Li random-pad 313A series of randomized values are set. 314.It Li seq-pad 315A series of sequential increasing numbers started from 1 are set. 316.El 317.\" 318.It Fl f Li nocyclic-seq 319Do not allow cyclic sequence number. 320.\" 321.It Fl lh Ar time 322.It Fl ls Ar time 323Specify hard/soft life time duration of the SA. 324.El 325.\" 326.Pp 327.It Ar algorithm 328.Bl -tag -width Fl -compact 329.It Fl E Ar ealgo Ar key 330Specify an encryption algorithm 331.Ar ealgo 332for ESP. 333.It Xo 334.Fl E Ar ealgo Ar key 335.Fl A Ar aalgo Ar key 336.Xc 337Specify a encryption algorithm 338.Ar ealgo , 339as well as a payload authentication algorithm 340.Ar aalgo , 341for ESP. 342.It Fl A Ar aalgo Ar key 343Specify an authentication algorithm for AH. 344.It Fl C Ar calgo Op Fl R 345Specify a compression algorithm for IPComp. 346If 347.Fl R 348is specified, the 349.Ar spi 350field value will be used as the IPComp CPI 351(compression parameter index) 352on wire as is. 353If 354.Fl R 355is not specified, 356the kernel will use well-known CPI on wire, and 357.Ar spi 358field will be used only as an index for kernel internal usage. 359.El 360.Pp 361.Ar key 362must be double-quoted character string, or a series of hexadecimal digits 363preceded by 364.Ql 0x . 365.Pp 366Possible values for 367.Ar ealgo , 368.Ar aalgo 369and 370.Ar calgo 371are specified in separate section. 372.\" 373.Pp 374.It Ar src_range 375.It Ar dst_range 376These are selections of the secure communication specified as 377IPv4/v6 address or IPv4/v6 address range, and it may accompany 378TCP/UDP port specification. 379This takes the following form: 380.Bd -unfilled 381.Ar address 382.Ar address/prefixlen 383.Ar address[port] 384.Ar address/prefixlen[port] 385.Ed 386.Pp 387.Ar prefixlen 388and 389.Ar port 390must be a decimal number. 391The square brackets around 392.Ar port 393are necessary and are not manpage metacharacters. 394For FQDN resolution, the rules applicable to 395.Ar src 396and 397.Ar dst 398apply here as well. 399.\" 400.Pp 401.It Ar upperspec 402The upper layer protocol to be used. 403You can use one of the words in 404.Pa /etc/protocols 405as 406.Ar upperspec , 407as well as 408.Li icmp6 , 409.Li ip4 , 410or 411.Li any . 412The word 413.Li any 414stands for 415.Dq any protocol . 416The protocol number may also be used to specify the 417.Ar upperspec . 418A type and code related to ICMPv6 may also be specified as an 419.Ar upperspec . 420The type is specified first, followed by a comma and then the relevant 421code. 422The specification must be placed after 423.Li icmp6 . 424The kernel considers a zero to be a wildcard but 425cannot distinguish between a wildcard and an ICMPv6 426type which is zero. 427The following example shows a policy where IPSec is not required for 428inbound Neighbor Solicitations: 429.Pp 430.Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;" 431.Pp 432NOTE: 433.Ar upperspec 434does not work in the forwarding case at this moment, 435as it requires extra reassembly at forwarding node, 436which is not implemented at this moment. 437Although there are many protocols in 438.Pa /etc/protocols , 439protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec. 440.\" 441.Pp 442.It Ar policy 443.Ar policy 444is expressed in one of the following three formats: 445.Pp 446.Bl -tag -width 2n -compact 447.It Fl P Ar direction Li discard 448.It Fl P Ar direction Li none 449.It Xo Fl P Ar direction Li ipsec 450.Ar protocol/mode/src-dst/level Op ... 451.Xc 452.El 453.Pp 454The direction of a policy must be specified as 455one of: 456.Li out , 457.Li in , 458.Li discard , 459.Li none , 460or 461.Li ipsec . 462The 463.Li discard 464direction 465means that packets matching the supplied indices will be discarded 466while 467.Li none 468means that IPsec operations will not take place on the packet and 469.Li ipsec 470means that IPsec operation will take place onto the packet. 471The 472.Ar protocol/mode/src-dst/level 473statement gives the rule for how to process the packet. 474The 475.Ar protocol 476is specified as 477.Li ah , 478.Li esp 479or 480.Li ipcomp . 481The 482.Ar mode 483is either 484.Li transport 485or 486.Li tunnel . 487If 488.Ar mode 489is 490.Li tunnel , 491you must specify the end-point addresses of the SA as 492.Ar src 493and 494.Ar dst 495with a dash, 496.Sq - , 497between the addresses. 498If 499.Ar mode 500is 501.Li transport , 502both 503.Ar src 504and 505.Ar dst 506can be omitted. 507The 508.Ar level 509is one of the following: 510.Li default , use , require 511or 512.Li unique . 513If the SA is not available in every level, the kernel will request 514the SA from the key exchange daemon. 515A value of 516.Li default 517tells the kernel to use the system wide default protocol 518e.g.,\& the one from the 519.Li esp_trans_deflev 520sysctl variable, when the kernel processes the packet. 521A value of 522.Li use 523means that the kernel will use an SA if it is available, 524otherwise the kernel will pass the packet as it would normally. 525A value of 526.Li require 527means that an SA is required whenever the kernel sends a packet matched 528that matches the policy. 529The 530.Li unique 531level is the same as 532.Li require 533but, in addition, it allows the policy to bind with the unique out-bound SA. 534For example, if you specify the policy level 535.Li unique , 536.Xr racoon 8 537will configure the SA for the policy. 538If you configure the SA by manual keying for that policy, 539you can put the decimal number as the policy identifier after 540.Li unique 541separated by colon 542.Ql :\& 543as in the following example: 544.Li unique:number . 545In order to bind this policy to the SA, 546.Li number 547must be between 1 and 32767, 548which corresponds to 549.Ar extensions Fl u 550of manual SA configuration. 551.Pp 552When you want to use an SA bundle, you can define multiple rules. 553For 554example, if an IP header was followed by an AH header followed by an 555ESP header followed by an upper layer protocol header, the rule would 556be: 557.Pp 558.Dl esp/transport//require ah/transport//require ; 559.Pp 560The rule order is very important. 561.Pp 562Note that 563.Dq Li discard 564and 565.Dq Li none 566are not in the syntax described in 567.Xr ipsec_set_policy 3 . 568There are small, but important, differences in the syntax. 569See 570.Xr ipsec_set_policy 3 571for details. 572.El 573.\" 574.Sh ALGORITHMS 575The following list shows the supported algorithms. 576The 577.Sy protocol 578and 579.Sy algorithm 580are almost completely orthogonal. 581The following list of authentication algorithms can be used as 582.Ar aalgo 583in the 584.Fl A Ar aalgo 585of the 586.Ar protocol 587parameter: 588.Bd -literal -offset indent 589algorithm keylen (bits) comment 590hmac-md5 128 ah: rfc2403 591 128 ah-old: rfc2085 592hmac-sha1 160 ah: rfc2404 593 160 ah-old: 128bit ICV (no document) 594keyed-md5 128 ah: 96bit ICV (no document) 595 128 ah-old: rfc1828 596keyed-sha1 160 ah: 96bit ICV (no document) 597 160 ah-old: 128bit ICV (no document) 598null 0 to 2048 for debugging 599hmac-sha2-256 256 ah: 128bit ICV (RFC4868) 600 256 ah-old: 128bit ICV (no document) 601hmac-sha2-384 384 ah: 192bit ICV (RFC4868) 602 384 ah-old: 128bit ICV (no document) 603hmac-sha2-512 512 ah: 256bit ICV (RFC4868) 604 512 ah-old: 128bit ICV (no document) 605hmac-ripemd160 160 ah: 96bit ICV (RFC2857) 606 ah-old: 128bit ICV (no document) 607aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 608 128 ah-old: 128bit ICV (no document) 609tcp-md5 8 to 640 tcp: rfc2385 610.Ed 611.Pp 612The following is the list of encryption algorithms that can be used as the 613.Ar ealgo 614in the 615.Fl E Ar ealgo 616of the 617.Ar protocol 618parameter: 619.Bd -literal -offset indent 620algorithm keylen (bits) comment 621des-cbc 64 esp-old: rfc1829, esp: rfc2405 6223des-cbc 192 rfc2451 623null 0 to 2048 rfc2410 624blowfish-cbc 40 to 448 rfc2451 625cast128-cbc 40 to 128 rfc2451 626des-deriv 64 ipsec-ciph-des-derived-01 627rijndael-cbc 128/192/256 rfc3602 628aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03 629aes-gcm-16 160/224/288 rfc4106 630camellia-cbc 128/192/256 rfc4312 631.Ed 632.Pp 633Note that the first 128/192/256 bits of a key for 634.Li aes-ctr or aes-gcm-16 635will be used as AES key, and remaining 32 bits will be used as nonce. 636.Pp 637The following are the list of compression algorithms that can be used 638as the 639.Ar calgo 640in the 641.Fl C Ar calgo 642of the 643.Ar protocol 644parameter: 645.Bd -literal -offset indent 646algorithm comment 647deflate rfc2394 648.Ed 649.\" 650.Sh EXIT STATUS 651.Ex -std 652.\" 653.Sh EXAMPLES 654Add an ESP SA between two IPv6 addresses using the 655des-cbc encryption algorithm. 656.Bd -literal -offset indent 657add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 658 -E des-cbc 0x3ffe05014819ffff ; 659.Pp 660.Ed 661.\" 662Add an authentication SA between two FQDN specified hosts: 663.Bd -literal -offset indent 664add -6 myhost.example.com yourhost.example.com ah 123456 665 -A hmac-sha1 "AH SA configuration!" ; 666.Pp 667.Ed 668Use both ESP and AH between two numerically specified hosts: 669.Bd -literal -offset indent 670add 10.0.11.41 10.0.11.33 esp 0x10001 671 -E des-cbc 0x3ffe05014819ffff 672 -A hmac-md5 "authentication!!" ; 673.Pp 674.Ed 675Get the SA information associated with first example above: 676.Bd -literal -offset indent 677get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 678.Pp 679.Ed 680Flush all entries from the database: 681.Bd -literal -offset indent 682flush ; 683.Pp 684.Ed 685Dump the ESP entries from the database: 686.Bd -literal -offset indent 687dump esp ; 688.Pp 689.Ed 690Add a security policy between two networks that uses ESP in tunnel mode: 691.Bd -literal -offset indent 692spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 693 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 694.Pp 695.Ed 696Use TCP MD5 between two numerically specified hosts: 697.Bd -literal -offset indent 698add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; 699.Ed 700.\" 701.Sh SEE ALSO 702.Xr ipsec_set_policy 3 , 703.Xr if_ipsec 4 , 704.Xr racoon 8 , 705.Xr sysctl 8 706.Rs 707.%T "Changed manual key configuration for IPsec" 708.%U http://www.kame.net/newsletter/19991007/ 709.%D "October 1999" 710.Re 711.\" 712.Sh HISTORY 713The 714.Nm 715utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 716The utility was completely re-designed in June 1998. 717It first appeared in 718.Fx 4.0 . 719.\" 720.Sh BUGS 721The 722.Nm 723utility 724should report and handle syntax errors better. 725.Pp 726For IPsec gateway configuration, 727.Ar src_range 728and 729.Ar dst_range 730with TCP/UDP port number do not work, as the gateway does not reassemble 731packets 732(cannot inspect upper-layer headers). 733