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