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 27, 2022 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 Pgltv 49.Fl D 50.Nm 51.Op Fl Pv 52.Fl F 53.Nm 54.Op Fl h 55.Fl x 56.\" 57.Sh DESCRIPTION 58The 59.Nm 60utility adds, updates, dumps, or flushes 61Security Association Database (SAD) entries 62as well as Security Policy Database (SPD) entries in the kernel. 63.Pp 64The 65.Nm 66utility takes a series of operations from the standard input 67(if invoked with 68.Fl c ) 69or the file named 70.Ar filename 71(if invoked with 72.Fl f Ar filename ) . 73.Bl -tag -width indent 74.It Fl D 75Dump the SAD entries. 76If with 77.Fl P , 78the SPD entries are dumped. 79.It Fl F 80Flush the SAD entries. 81If with 82.Fl P , 83the SPD entries are flushed. 84.It Fl g 85Only SPD entries with global scope are dumped with 86.Fl D 87and 88.Fl P 89flags. 90.It Fl t 91Only SPD entries with ifnet scope are dumped with 92.Fl D 93and 94.Fl P 95flags. 96Such SPD entries are linked to the corresponding 97.Xr if_ipsec 4 98virtual tunneling interface. 99.It Fl h 100Add hexadecimal dump on 101.Fl x 102mode. 103.It Fl l 104Loop forever with short output on 105.Fl D . 106.It Fl v 107Be verbose. 108The program will dump messages exchanged on 109.Dv PF_KEY 110socket, including messages sent from other processes to the kernel. 111.It Fl x 112Loop forever and dump all the messages transmitted to 113.Dv PF_KEY 114socket. 115.Fl xx 116makes each timestamp unformatted. 117.El 118.Ss Configuration syntax 119With 120.Fl c 121or 122.Fl f 123on the command line, 124.Nm 125accepts the following configuration syntax. 126Lines starting with hash signs 127.Pq Ql # 128are treated as comment lines. 129.Bl -tag -width indent 130.It Xo 131.Li add 132.Op Fl 46n 133.Ar src Ar dst Ar protocol Ar spi 134.Op Ar extensions 135.Ar algorithm ... 136.Li \&; 137.Xc 138Add an SAD entry. 139.Li add 140can fail with multiple reasons, 141including when the key length does not match the specified algorithm. 142.\" 143.It Xo 144.Li get 145.Op Fl 46n 146.Ar src Ar dst Ar protocol Ar spi 147.Li \&; 148.Xc 149Show an SAD entry. 150.\" 151.It Xo 152.Li delete 153.Op Fl 46n 154.Ar src Ar dst Ar protocol Ar spi 155.Li \&; 156.Xc 157Remove an SAD entry. 158.\" 159.It Xo 160.Li deleteall 161.Op Fl 46n 162.Ar src Ar dst Ar protocol 163.Li \&; 164.Xc 165Remove all SAD entries that match the specification. 166.\" 167.It Xo 168.Li flush 169.Op Ar protocol 170.Li \&; 171.Xc 172Clear all SAD entries matched by the options. 173.Fl F 174on the command line achieves the same functionality. 175.\" 176.It Xo 177.Li dump 178.Op Ar protocol 179.Li \&; 180.Xc 181Dumps all SAD entries matched by the options. 182.Fl D 183on the command line achieves the same functionality. 184.\" 185.It Xo 186.Li spdadd 187.Op Fl 46n 188.Ar src_range Ar dst_range Ar upperspec Ar policy 189.Li \&; 190.Xc 191Add an SPD entry. 192.\" 193.It Xo 194.Li spddelete 195.Op Fl 46n 196.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction 197.Li \&; 198.Xc 199Delete an SPD entry. 200.\" 201.It Xo 202.Li spdflush 203.Li \&; 204.Xc 205Clear all SPD entries. 206.Fl FP 207on the command line achieves the same functionality. 208.\" 209.It Xo 210.Li spddump 211.Li \&; 212.Xc 213Dumps all SPD entries. 214.Fl DP 215on the command line achieves the same functionality. 216.El 217.\" 218.Pp 219Meta-arguments are as follows: 220.Pp 221.Bl -tag -compact -width indent 222.It Ar src 223.It Ar dst 224Source/destination of the secure communication is specified as 225IPv4/v6 address. 226The 227.Nm 228utility 229can resolve a FQDN into numeric addresses. 230If the FQDN resolves into multiple addresses, 231.Nm 232will install multiple SAD/SPD entries into the kernel 233by trying all possible combinations. 234.Fl 4 , 235.Fl 6 236and 237.Fl n 238restricts the address resolution of FQDN in certain ways. 239.Fl 4 240and 241.Fl 6 242restrict results into IPv4/v6 addresses only, respectively. 243.Fl n 244avoids FQDN resolution and requires addresses to be numeric addresses. 245.\" 246.Pp 247.It Ar protocol 248.Ar protocol 249is one of following: 250.Bl -tag -width Fl -compact 251.It Li esp 252ESP based on rfc2406 253.It Li esp-old 254ESP based on rfc1827 255.It Li ah 256AH based on rfc2402 257.It Li ah-old 258AH based on rfc1826 259.It Li ipcomp 260IPComp 261.It Li tcp 262TCP-MD5 based on rfc2385 263.El 264.\" 265.Pp 266.It Ar spi 267Security Parameter Index 268(SPI) 269for the SAD and the SPD. 270.Ar spi 271must be a decimal number, or a hexadecimal number with 272.Ql 0x 273prefix. 274SPI values between 0 and 255 are reserved for future use by IANA 275and they cannot be used. 276.\" 277.Pp 278.It Ar extensions 279take some of the following: 280.Bl -tag -width Fl -compact 281.\" 282.It Fl m Ar mode 283Specify a security protocol mode for use. 284.Ar mode 285is one of following: 286.Li transport , tunnel 287or 288.Li any . 289The default value is 290.Li any . 291.\" 292.It Fl r Ar size 293Specify the bitmap size in octets of the anti-replay window. 294.Ar size 295is a 32-bit unsigned integer, and its value is one eighth of the 296anti-replay window size in packets. 297If 298.Ar size 299is zero or not specified, an anti-replay check does not take place. 300.\" 301.It Fl u Ar id 302Specify the identifier of the policy entry in SPD. 303See 304.Ar policy . 305.\" 306.It Fl f Ar pad_option 307defines the content of the ESP padding. 308.Ar pad_option 309is one of following: 310.Bl -tag -width random-pad -compact 311.It Li zero-pad 312All of the padding are zero. 313.It Li random-pad 314A series of randomized values are set. 315.It Li seq-pad 316A series of sequential increasing numbers started from 1 are set. 317.El 318.\" 319.It Fl f Li nocyclic-seq 320Do not allow cyclic sequence number. 321.\" 322.It Fl lh Ar time 323.It Fl ls Ar time 324Specify hard/soft life time duration of the SA. 325.El 326.\" 327.Pp 328.It Ar algorithm 329.Bl -tag -width Fl -compact 330.It Fl E Ar ealgo Ar key 331Specify an encryption or Authenticated Encryption with Associated Data 332(AEAD) algorithm 333.Ar ealgo 334for ESP. 335.It Xo 336.Fl E Ar ealgo Ar key 337.Fl A Ar aalgo Ar key 338.Xc 339Specify a encryption algorithm 340.Ar ealgo , 341as well as a payload authentication algorithm 342.Ar aalgo , 343for ESP. 344.It Fl A Ar aalgo Ar key 345Specify an authentication algorithm for AH. 346.It Fl C Ar calgo Op Fl R 347Specify a compression algorithm for IPComp. 348If 349.Fl R 350is specified, the 351.Ar spi 352field value will be used as the IPComp CPI 353(compression parameter index) 354on wire as is. 355If 356.Fl R 357is not specified, 358the kernel will use well-known CPI on wire, and 359.Ar spi 360field will be used only as an index for kernel internal usage. 361.El 362.Pp 363.Ar key 364must be double-quoted character string, or a series of hexadecimal digits 365preceded by 366.Ql 0x . 367.Pp 368Possible values for 369.Ar ealgo , 370.Ar aalgo 371and 372.Ar calgo 373are specified in separate section. 374.\" 375.Pp 376.It Ar src_range 377.It Ar dst_range 378These are selections of the secure communication specified as 379IPv4/v6 address or IPv4/v6 address range, and it may accompany 380TCP/UDP port specification. 381This takes the following form: 382.Bd -unfilled 383.Ar address 384.Ar address/prefixlen 385.Ar address[port] 386.Ar address/prefixlen[port] 387.Ed 388.Pp 389.Ar prefixlen 390and 391.Ar port 392must be a decimal number. 393The square brackets around 394.Ar port 395are necessary and are not manpage metacharacters. 396For FQDN resolution, the rules applicable to 397.Ar src 398and 399.Ar dst 400apply here as well. 401.\" 402.Pp 403.It Ar upperspec 404The upper layer protocol to be used. 405You can use one of the words in 406.Pa /etc/protocols 407as 408.Ar upperspec , 409as well as 410.Li icmp6 , 411.Li ip4 , 412or 413.Li any . 414The word 415.Li any 416stands for 417.Dq any protocol . 418The protocol number may also be used to specify the 419.Ar upperspec . 420A type and code related to ICMPv6 may also be specified as an 421.Ar upperspec . 422The type is specified first, followed by a comma and then the relevant 423code. 424The specification must be placed after 425.Li icmp6 . 426The kernel considers a zero to be a wildcard but 427cannot distinguish between a wildcard and an ICMPv6 428type which is zero. 429The following example shows a policy where IPSec is not required for 430inbound Neighbor Solicitations: 431.Pp 432.Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;" 433.Pp 434NOTE: 435.Ar upperspec 436does not work in the forwarding case at this moment, 437as it requires extra reassembly at forwarding node, 438which is not implemented at this moment. 439Although there are many protocols in 440.Pa /etc/protocols , 441protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec. 442.\" 443.Pp 444.It Ar policy 445.Ar policy 446is expressed in one of the following three formats: 447.Pp 448.Bl -tag -width 2n -compact 449.It Fl P Ar direction Li discard 450.It Fl P Ar direction Li none 451.It Xo Fl P Ar direction Li ipsec 452.Ar protocol/mode/src-dst/level Op ... 453.Xc 454.El 455.Pp 456The direction of a policy must be specified as 457one of: 458.Li out , 459.Li in , 460.Li discard , 461.Li none , 462or 463.Li ipsec . 464The 465.Li discard 466direction 467means that packets matching the supplied indices will be discarded 468while 469.Li none 470means that IPsec operations will not take place on the packet and 471.Li ipsec 472means that IPsec operation will take place onto the packet. 473The 474.Ar protocol/mode/src-dst/level 475statement gives the rule for how to process the packet. 476The 477.Ar protocol 478is specified as 479.Li ah , 480.Li esp 481or 482.Li ipcomp . 483The 484.Ar mode 485is either 486.Li transport 487or 488.Li tunnel . 489If 490.Ar mode 491is 492.Li tunnel , 493you must specify the end-point addresses of the SA as 494.Ar src 495and 496.Ar dst 497with a dash, 498.Sq - , 499between the addresses. 500If 501.Ar mode 502is 503.Li transport , 504both 505.Ar src 506and 507.Ar dst 508can be omitted. 509The 510.Ar level 511is one of the following: 512.Li default , use , require 513or 514.Li unique . 515If the SA is not available in every level, the kernel will request 516the SA from the key exchange daemon. 517A value of 518.Li default 519tells the kernel to use the system wide default protocol 520e.g.,\& the one from the 521.Li esp_trans_deflev 522sysctl variable, when the kernel processes the packet. 523A value of 524.Li use 525means that the kernel will use an SA if it is available, 526otherwise the kernel will pass the packet as it would normally. 527A value of 528.Li require 529means that an SA is required whenever the kernel sends a packet matched 530that matches the policy. 531The 532.Li unique 533level is the same as 534.Li require 535but, in addition, it allows the policy to bind with the unique out-bound SA. 536For example, if you specify the policy level 537.Li unique , 538.Xr racoon 8 Pq Pa ports/security/ipsec-tools 539will configure the SA for the policy. 540If you configure the SA by manual keying for that policy, 541you can put the decimal number as the policy identifier after 542.Li unique 543separated by colon 544.Ql :\& 545as in the following example: 546.Li unique:number . 547In order to bind this policy to the SA, 548.Li number 549must be between 1 and 32767, 550which corresponds to 551.Ar extensions Fl u 552of manual SA configuration. 553.Pp 554When you want to use an SA bundle, you can define multiple rules. 555For 556example, if an IP header was followed by an AH header followed by an 557ESP header followed by an upper layer protocol header, the rule would 558be: 559.Pp 560.Dl esp/transport//require ah/transport//require ; 561.Pp 562The rule order is very important. 563.Pp 564Note that 565.Dq Li discard 566and 567.Dq Li none 568are not in the syntax described in 569.Xr ipsec_set_policy 3 . 570There are small, but important, differences in the syntax. 571See 572.Xr ipsec_set_policy 3 573for details. 574.El 575.\" 576.Sh ALGORITHMS 577The following lists show the supported algorithms. 578.Ss Authentication Algorithms 579The following authentication algorithms can be used as 580.Ar aalgo 581in the 582.Fl A Ar aalgo 583of the 584.Ar protocol 585parameter: 586.Bd -literal -offset indent 587algorithm keylen (bits) comment 588hmac-sha1 160 ah/esp: rfc2404 589 160 ah-old/esp-old: 128bit ICV (no document) 590null 0 to 2048 for debugging 591hmac-sha2-256 256 ah/esp: 128bit ICV (RFC4868) 592 256 ah-old/esp-old: 128bit ICV (no document) 593hmac-sha2-384 384 ah/esp: 192bit ICV (RFC4868) 594 384 ah-old/esp-old: 128bit ICV (no document) 595hmac-sha2-512 512 ah/esp: 256bit ICV (RFC4868) 596 512 ah-old/esp-old: 128bit ICV (no document) 597aes-xcbc-mac 128 ah/esp: 96bit ICV (RFC3566) 598 128 ah-old/esp-old: 128bit ICV (no document) 599tcp-md5 8 to 640 tcp: rfc2385 600.Ed 601.Ss Encryption Algorithms 602The following encryption algorithms can be used as the 603.Ar ealgo 604in the 605.Fl E Ar ealgo 606of the 607.Ar protocol 608parameter: 609.Bd -literal -offset indent 610algorithm keylen (bits) comment 611null 0 to 2048 rfc2410 612aes-cbc 128/192/256 rfc3602 613aes-ctr 160/224/288 rfc3686 614aes-gcm-16 160/224/288 AEAD; rfc4106 615.Ed 616.Pp 617Note that the first 128/192/256 bits of a key for 618.Li aes-ctr 619or 620.Li aes-gcm-16 621will be used as the AES key, 622and the remaining 32 bits will be used as the nonce. 623.Pp 624AEAD encryption algorithms such as 625.Li aes-gcm-16 626include authentication and should not be 627paired with a separate authentication algorithm via 628.Fl A . 629.Ss Compression Algorithms 630The following compression algorithms can be used 631as the 632.Ar calgo 633in the 634.Fl C Ar calgo 635of the 636.Ar protocol 637parameter: 638.Bd -literal -offset indent 639algorithm comment 640deflate rfc2394 641.Ed 642.\" 643.Sh EXIT STATUS 644.Ex -std 645.\" 646.Sh EXAMPLES 647Add an ESP SA between two IPv6 addresses using the 648AES-GCM AEAD algorithm. 649.Bd -literal -offset indent 650add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 651 -E aes-gcm-16 0x3ffe050148193ffe050148193ffe050148193ffe ; 652.Pp 653.Ed 654.\" 655Add an authentication SA between two FQDN specified hosts: 656.Bd -literal -offset indent 657add -6 myhost.example.com yourhost.example.com ah 123456 658 -A hmac-sha2-256 "AH SA configuration!" ; 659.Pp 660.Ed 661Get the SA information associated with first example above: 662.Bd -literal -offset indent 663get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 664.Pp 665.Ed 666Flush all entries from the database: 667.Bd -literal -offset indent 668flush ; 669.Pp 670.Ed 671Dump the ESP entries from the database: 672.Bd -literal -offset indent 673dump esp ; 674.Pp 675.Ed 676Add a security policy between two networks that uses ESP in tunnel mode: 677.Bd -literal -offset indent 678spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 679 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 680.Pp 681.Ed 682Use TCP MD5 between two numerically specified hosts: 683.Bd -literal -offset indent 684add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; 685add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ; 686.Ed 687.\" 688.Sh SEE ALSO 689.Xr ipsec_set_policy 3 , 690.Xr if_ipsec 4 , 691.Xr racoon 8 Pq Pa ports/security/ipsec-tools , 692.Xr sysctl 8 693.Rs 694.%T "Changed manual key configuration for IPsec" 695.%U https://www.kame.net/newsletter/19991007/ 696.%D "October 1999" 697.Re 698.\" 699.Sh HISTORY 700The 701.Nm 702utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 703The utility was completely re-designed in June 1998. 704It first appeared in 705.Fx 4.0 . 706.\" 707.Sh BUGS 708The 709.Nm 710utility 711should report and handle syntax errors better. 712.Pp 713For IPsec gateway configuration, 714.Ar src_range 715and 716.Ar dst_range 717with TCP/UDP port number do not work, as the gateway does not reassemble 718packets 719(cannot inspect upper-layer headers). 720