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