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