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