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