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