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