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 October 31, 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 475.Bl -tag -compact -width "policy level" 476.It Ar direction 477The 478.Ar direction 479of a policy must be specified as one of: 480.Li out 481or 482.Li in . 483.It Ar policy level 484The direction is followed by one of the following policy levels: 485.Li discard , 486.Li none , 487or 488.Li ipsec . 489.Bl -compact -bullet 490.It 491The 492.Li discard 493policy level means that packets matching the supplied indices will 494be discarded. 495.It 496The 497.Li none 498policy level means that IPsec operations will not take place on 499the packet. 500.It 501The 502.Li ipsec 503policy level means that IPsec operation will take place onto 504the packet. 505.El 506.It Ar protocol/mode/src-dst/level 507The 508.Ar protocol/mode/src-dst/level 509statement gives the rule for how to process the packet. 510.Bl -compact -bullet 511.It 512The 513.Ar protocol 514is specified as 515.Li ah , 516.Li esp 517or 518.Li ipcomp . 519.It 520The 521.Ar mode 522is either 523.Li transport 524or 525.Li tunnel . 526.El 527.Pp 528If 529.Ar mode 530is 531.Li tunnel , 532you must specify the end-point addresses of the SA as 533.Ar src 534and 535.Ar dst 536with a dash, 537.Sq - , 538between the addresses. 539.Pp 540If 541.Ar mode 542is 543.Li transport , 544both 545.Ar src 546and 547.Ar dst 548can be omitted. 549.Pp 550The 551.Ar level 552is one of the following: 553.Li default , use , require 554or 555.Li unique . 556If the SA is not available in every level, the kernel will request 557the SA from the key exchange daemon. 558.Pp 559.Bl -compact -bullet 560.It 561A value of 562.Li default 563tells the kernel to use the system wide default protocol 564e.g.,\& the one from the 565.Li esp_trans_deflev 566sysctl variable, when the kernel processes the packet. 567.It 568A value of 569.Li use 570means that the kernel will use an SA if it is available, 571otherwise the kernel will pass the packet as it would normally. 572.It 573A value of 574.Li require 575means that an SA is required whenever the kernel sends a packet matched 576that matches the policy. 577.It 578The 579.Li unique 580level is the same as 581.Li require 582but, in addition, it allows the policy to bind with the unique out-bound SA. 583.Pp 584For example, if you specify the policy level 585.Li unique , 586.Xr racoon 8 Pq Pa ports/security/ipsec-tools 587will configure the SA for the policy. 588If you configure the SA by manual keying for that policy, 589you can put the decimal number as the policy identifier after 590.Li unique 591separated by colon 592.Ql :\& 593as in the following example: 594.Li unique:number . 595In order to bind this policy to the SA, 596.Li number 597must be between 1 and 32767, 598which corresponds to 599.Ar extensions Fl u 600of manual SA configuration. 601.El 602.El 603.Pp 604When you want to use an SA bundle, you can define multiple rules. 605For 606example, if an IP header was followed by an AH header followed by an 607ESP header followed by an upper layer protocol header, the rule would 608be: 609.Pp 610.Dl esp/transport//require ah/transport//require ; 611.Pp 612The rule order is very important. 613.Pp 614Note that 615.Dq Li discard 616and 617.Dq Li none 618are not in the syntax described in 619.Xr ipsec_set_policy 3 . 620There are small, but important, differences in the syntax. 621See 622.Xr ipsec_set_policy 3 623for details. 624.El 625.\" 626.Sh ALGORITHMS 627The following lists show the supported algorithms. 628.Ss Authentication Algorithms 629The following authentication algorithms can be used as 630.Ar aalgo 631in the 632.Fl A Ar aalgo 633of the 634.Ar protocol 635parameter: 636.Bd -literal -offset indent 637algorithm keylen (bits) comment 638hmac-sha1 160 ah/esp: rfc2404 639 160 ah-old/esp-old: 128bit ICV (no document) 640null 0 to 2048 for debugging 641hmac-sha2-256 256 ah/esp: 128bit ICV (RFC4868) 642 256 ah-old/esp-old: 128bit ICV (no document) 643hmac-sha2-384 384 ah/esp: 192bit ICV (RFC4868) 644 384 ah-old/esp-old: 128bit ICV (no document) 645hmac-sha2-512 512 ah/esp: 256bit ICV (RFC4868) 646 512 ah-old/esp-old: 128bit ICV (no document) 647aes-xcbc-mac 128 ah/esp: 96bit ICV (RFC3566) 648 128 ah-old/esp-old: 128bit ICV (no document) 649tcp-md5 8 to 640 tcp: rfc2385 650chacha20-poly1305 256 ah/esp: 128bit ICV (RFC7634) 651.Ed 652.Ss Encryption Algorithms 653The following encryption algorithms can be used as the 654.Ar ealgo 655in the 656.Fl E Ar ealgo 657of the 658.Ar protocol 659parameter: 660.Bd -literal -offset indent 661algorithm keylen (bits) comment 662null 0 to 2048 rfc2410 663aes-cbc 128/192/256 rfc3602 664aes-ctr 160/224/288 rfc3686 665aes-gcm-16 160/224/288 AEAD; rfc4106 666chacha20-poly1305 256 rfc7634 667.Ed 668.Pp 669Note that the first 128/192/256 bits of a key for 670.Li aes-ctr 671or 672.Li aes-gcm-16 673will be used as the AES key, 674and the remaining 32 bits will be used as the nonce. 675.Pp 676AEAD encryption algorithms such as 677.Li aes-gcm-16 678include authentication and should not be 679paired with a separate authentication algorithm via 680.Fl A . 681.Ss Compression Algorithms 682The following compression algorithms can be used 683as the 684.Ar calgo 685in the 686.Fl C Ar calgo 687of the 688.Ar protocol 689parameter: 690.Bd -literal -offset indent 691algorithm comment 692deflate rfc2394 693.Ed 694.\" 695.Sh EXIT STATUS 696.Ex -std 697.\" 698.Sh EXAMPLES 699Add an ESP SA between two IPv6 addresses using the 700AES-GCM AEAD algorithm. 701.Bd -literal -offset indent 702add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 703 -E aes-gcm-16 0x3ffe050148193ffe050148193ffe050148193ffe ; 704.Pp 705.Ed 706.\" 707Add an authentication SA between two FQDN specified hosts: 708.Bd -literal -offset indent 709add -6 myhost.example.com yourhost.example.com ah 123456 710 -A hmac-sha2-256 "AH SA configuration!" ; 711.Pp 712.Ed 713Get the SA information associated with first example above: 714.Bd -literal -offset indent 715get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 716.Pp 717.Ed 718Flush all entries from the database: 719.Bd -literal -offset indent 720flush ; 721.Pp 722.Ed 723Dump the ESP entries from the database: 724.Bd -literal -offset indent 725dump esp ; 726.Pp 727.Ed 728Add a security policy between two networks that uses ESP in tunnel mode: 729.Bd -literal -offset indent 730spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 731 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 732.Pp 733.Ed 734Use TCP MD5 between two numerically specified hosts: 735.Bd -literal -offset indent 736add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; 737add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ; 738.Ed 739.\" 740.Sh SEE ALSO 741.Xr ipsec_set_policy 3 , 742.Xr if_ipsec 4 , 743.Xr racoon 8 Pq Pa ports/security/ipsec-tools , 744.Xr sysctl 8 745.Rs 746.%T "Changed manual key configuration for IPsec" 747.%U https://www.kame.net/newsletter/19991007/ 748.%D "October 1999" 749.Re 750.\" 751.Sh HISTORY 752The 753.Nm 754utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 755The utility was completely re-designed in June 1998. 756It first appeared in 757.Fx 4.0 . 758.\" 759.Sh BUGS 760The 761.Nm 762utility 763should report and handle syntax errors better. 764.Pp 765For IPsec gateway configuration, 766.Ar src_range 767and 768.Ar dst_range 769with TCP/UDP port number do not work, as the gateway does not reassemble 770packets 771(cannot inspect upper-layer headers). 772