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