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