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 an 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.It Fl esn 345Enable Extended Sequence Number extension for this SA. 346.El 347.\" 348.Pp 349.It Ar algorithm 350.Bl -tag -width Fl -compact 351.It Fl E Ar ealgo Ar key 352Specify an encryption or Authenticated Encryption with Associated Data 353(AEAD) algorithm 354.Ar ealgo 355for ESP. 356.It Xo 357.Fl E Ar ealgo Ar key 358.Fl A Ar aalgo Ar key 359.Xc 360Specify a encryption algorithm 361.Ar ealgo , 362as well as a payload authentication algorithm 363.Ar aalgo , 364for ESP. 365.It Fl A Ar aalgo Ar key 366Specify an authentication algorithm for AH. 367.It Fl C Ar calgo Op Fl R 368Specify a compression algorithm for IPComp. 369If 370.Fl R 371is specified, the 372.Ar spi 373field value will be used as the IPComp CPI 374(compression parameter index) 375on wire as is. 376If 377.Fl R 378is not specified, 379the kernel will use well-known CPI on wire, and 380.Ar spi 381field will be used only as an index for kernel internal usage. 382.El 383.Pp 384.Ar key 385must be double-quoted character string, or a series of hexadecimal digits 386preceded by 387.Ql 0x . 388.Pp 389Possible values for 390.Ar ealgo , 391.Ar aalgo 392and 393.Ar calgo 394are specified in separate section. 395.\" 396.Pp 397.It Ar src_range 398.It Ar dst_range 399These are selections of the secure communication specified as 400IPv4/v6 address or IPv4/v6 address range, and it may accompany 401TCP/UDP port specification. 402This takes the following form: 403.Bd -unfilled 404.Ar address 405.Ar address/prefixlen 406.Ar address[port] 407.Ar address/prefixlen[port] 408.Ed 409.Pp 410.Ar prefixlen 411and 412.Ar port 413must be a decimal number. 414The square brackets around 415.Ar port 416are necessary and are not manpage metacharacters. 417For FQDN resolution, the rules applicable to 418.Ar src 419and 420.Ar dst 421apply here as well. 422.\" 423.Pp 424.It Ar upperspec 425The upper layer protocol to be used. 426You can use one of the words in 427.Pa /etc/protocols 428as 429.Ar upperspec , 430as well as 431.Li icmp6 , 432.Li ip4 , 433or 434.Li any . 435The word 436.Li any 437stands for 438.Dq any protocol . 439The protocol number may also be used to specify the 440.Ar upperspec . 441A type and code related to ICMPv6 may also be specified as an 442.Ar upperspec . 443The type is specified first, followed by a comma and then the relevant 444code. 445The specification must be placed after 446.Li icmp6 . 447The kernel considers a zero to be a wildcard but 448cannot distinguish between a wildcard and an ICMPv6 449type which is zero. 450The following example shows a policy where IPSec is not required for 451inbound Neighbor Solicitations: 452.Pp 453.Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;" 454.Pp 455NOTE: 456.Ar upperspec 457does not work in the forwarding case at this moment, 458as it requires extra reassembly at forwarding node, 459which is not implemented at this moment. 460Although there are many protocols in 461.Pa /etc/protocols , 462protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec. 463.\" 464.Pp 465.It Ar policy 466.Ar policy 467is expressed in one of the following three formats: 468.Pp 469.Bl -tag -width 2n -compact 470.It Fl P Ar direction Li discard 471.It Fl P Ar direction Li none 472.It Xo Fl P Ar direction Li ipsec 473.Ar protocol/mode/src-dst/level Op ... 474.Xc 475.El 476.Pp 477.Bl -tag -compact -width "policy level" 478.It Ar direction 479The 480.Ar direction 481of a policy must be specified as one of: 482.Li out 483or 484.Li in . 485.It Ar policy level 486The direction is followed by one of the following policy levels: 487.Li discard , 488.Li none , 489or 490.Li ipsec . 491.Bl -compact -bullet 492.It 493The 494.Li discard 495policy level means that packets matching the supplied indices will 496be discarded. 497.It 498The 499.Li none 500policy level means that IPsec operations will not take place on 501the packet. 502.It 503The 504.Li ipsec 505policy level means that IPsec operation will take place onto 506the packet. 507.El 508.It Ar protocol/mode/src-dst/level 509The 510.Ar protocol/mode/src-dst/level 511statement gives the rule for how to process the packet. 512.Bl -compact -bullet 513.It 514The 515.Ar protocol 516is specified as 517.Li ah , 518.Li esp 519or 520.Li ipcomp . 521.It 522The 523.Ar mode 524is either 525.Li transport 526or 527.Li tunnel . 528.El 529.Pp 530If 531.Ar mode 532is 533.Li tunnel , 534you must specify the end-point addresses of the SA as 535.Ar src 536and 537.Ar dst 538with a dash, 539.Sq - , 540between the addresses. 541.Pp 542If 543.Ar mode 544is 545.Li transport , 546both 547.Ar src 548and 549.Ar dst 550can be omitted. 551.Pp 552The 553.Ar level 554is one of the following: 555.Li default , use , require 556or 557.Li unique . 558If the SA is not available in every level, the kernel will request 559the SA from the key exchange daemon. 560.Pp 561.Bl -compact -bullet 562.It 563A value of 564.Li default 565tells the kernel to use the system wide default protocol 566e.g.,\& the one from the 567.Li esp_trans_deflev 568sysctl variable, when the kernel processes the packet. 569.It 570A value of 571.Li use 572means that the kernel will use an SA if it is available, 573otherwise the kernel will pass the packet as it would normally. 574.It 575A value of 576.Li require 577means that an SA is required whenever the kernel sends a packet matched 578that matches the policy. 579.It 580The 581.Li unique 582level is the same as 583.Li require 584but, in addition, it allows the policy to bind with the unique out-bound SA. 585.Pp 586For example, if you specify the policy level 587.Li unique , 588.Xr racoon 8 Pq Pa ports/security/ipsec-tools 589will configure the SA for the policy. 590If you configure the SA by manual keying for that policy, 591you can put the decimal number as the policy identifier after 592.Li unique 593separated by colon 594.Ql :\& 595as in the following example: 596.Li unique:number . 597In order to bind this policy to the SA, 598.Li number 599must be between 1 and 32767, 600which corresponds to 601.Ar extensions Fl u 602of manual SA configuration. 603.El 604.El 605.Pp 606When you want to use an SA bundle, you can define multiple rules. 607For 608example, if an IP header was followed by an AH header followed by an 609ESP header followed by an upper layer protocol header, the rule would 610be: 611.Pp 612.Dl esp/transport//require ah/transport//require ; 613.Pp 614The rule order is very important. 615.Pp 616Note that 617.Dq Li discard 618and 619.Dq Li none 620are not in the syntax described in 621.Xr ipsec_set_policy 3 . 622There are small, but important, differences in the syntax. 623See 624.Xr ipsec_set_policy 3 625for details. 626.El 627.\" 628.Sh ALGORITHMS 629The following lists show the supported algorithms. 630.Ss Authentication Algorithms 631The following authentication algorithms can be used as 632.Ar aalgo 633in the 634.Fl A Ar aalgo 635of the 636.Ar protocol 637parameter: 638.Bd -literal -offset indent 639algorithm keylen (bits) comment 640hmac-sha1 160 ah/esp: rfc2404 641 160 ah-old/esp-old: 128bit ICV (no document) 642null 0 to 2048 for debugging 643hmac-sha2-256 256 ah/esp: 128bit ICV (RFC4868) 644 256 ah-old/esp-old: 128bit ICV (no document) 645hmac-sha2-384 384 ah/esp: 192bit ICV (RFC4868) 646 384 ah-old/esp-old: 128bit ICV (no document) 647hmac-sha2-512 512 ah/esp: 256bit ICV (RFC4868) 648 512 ah-old/esp-old: 128bit ICV (no document) 649aes-xcbc-mac 128 ah/esp: 96bit ICV (RFC3566) 650 128 ah-old/esp-old: 128bit ICV (no document) 651tcp-md5 8 to 640 tcp: rfc2385 652chacha20-poly1305 256 ah/esp: 128bit ICV (RFC7634) 653.Ed 654.Ss Encryption Algorithms 655The following encryption algorithms can be used as the 656.Ar ealgo 657in the 658.Fl E Ar ealgo 659of the 660.Ar protocol 661parameter: 662.Bd -literal -offset indent 663algorithm keylen (bits) comment 664null 0 to 2048 rfc2410 665aes-cbc 128/192/256 rfc3602 666aes-ctr 160/224/288 rfc3686 667aes-gcm-16 160/224/288 AEAD; rfc4106 668chacha20-poly1305 256 rfc7634 669.Ed 670.Pp 671Note that the first 128/192/256 bits of a key for 672.Li aes-ctr 673or 674.Li aes-gcm-16 675will be used as the AES key, 676and the remaining 32 bits will be used as the nonce. 677.Pp 678AEAD encryption algorithms such as 679.Li aes-gcm-16 680include authentication and should not be 681paired with a separate authentication algorithm via 682.Fl A . 683.Ss Compression Algorithms 684The following compression algorithms can be used 685as the 686.Ar calgo 687in the 688.Fl C Ar calgo 689of the 690.Ar protocol 691parameter: 692.Bd -literal -offset indent 693algorithm comment 694deflate rfc2394 695.Ed 696.\" 697.Sh EXIT STATUS 698.Ex -std 699.\" 700.Sh EXAMPLES 701Add an ESP SA between two IPv6 addresses using the 702AES-GCM AEAD algorithm. 703.Bd -literal -offset indent 704add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 705 -E aes-gcm-16 0x3ffe050148193ffe050148193ffe050148193ffe ; 706.Pp 707.Ed 708.\" 709Add an authentication SA between two FQDN specified hosts: 710.Bd -literal -offset indent 711add -6 myhost.example.com yourhost.example.com ah 123456 712 -A hmac-sha2-256 "AH SA configuration!" ; 713.Pp 714.Ed 715Get the SA information associated with first example above: 716.Bd -literal -offset indent 717get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 718.Pp 719.Ed 720Flush all entries from the database: 721.Bd -literal -offset indent 722flush ; 723.Pp 724.Ed 725Dump the ESP entries from the database: 726.Bd -literal -offset indent 727dump esp ; 728.Pp 729.Ed 730Add a security policy between two networks that uses ESP in tunnel mode: 731.Bd -literal -offset indent 732spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 733 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 734.Pp 735.Ed 736Use TCP MD5 between two numerically specified hosts: 737.Bd -literal -offset indent 738add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; 739add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ; 740.Ed 741.\" 742.Sh SEE ALSO 743.Xr ipsec_set_policy 3 , 744.Xr if_ipsec 4 , 745.Xr racoon 8 Pq Pa ports/security/ipsec-tools , 746.Xr sysctl 8 747.Rs 748.%T "Changed manual key configuration for IPsec" 749.%U https://www.kame.net/newsletter/19991007/ 750.%D "October 1999" 751.Re 752.\" 753.Sh HISTORY 754The 755.Nm 756utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 757The utility was completely re-designed in June 1998. 758It first appeared in 759.Fx 4.0 . 760.\" 761.Sh BUGS 762The 763.Nm 764utility 765should report and handle syntax errors better. 766.Pp 767For IPsec gateway configuration, 768.Ar src_range 769and 770.Ar dst_range 771with TCP/UDP port number do not work, as the gateway does not reassemble 772packets 773(cannot inspect upper-layer headers). 774