1.\" $KAME: setkey.8,v 1.89 2003/09/07 22:17:41 itojun Exp $ 2.\" $FreeBSD$ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd November 20, 2000 32.Dt SETKEY 8 33.Os 34.\" 35.Sh NAME 36.Nm setkey 37.Nd "manually manipulate the IPsec SA/SP database" 38.\" 39.Sh SYNOPSIS 40.Nm 41.Op Fl v 42.Fl c 43.Nm 44.Op Fl v 45.Fl f Ar filename 46.Nm 47.Op Fl aPlv 48.Fl D 49.Nm 50.Op Fl Pv 51.Fl F 52.Nm 53.Op Fl h 54.Fl x 55.\" 56.Sh DESCRIPTION 57The 58.Nm 59utility adds, updates, dumps, or flushes 60Security Association Database (SAD) entries 61as well as Security Policy Database (SPD) entries in the kernel. 62.Pp 63The 64.Nm 65utility takes a series of operations from the standard input 66(if invoked with 67.Fl c ) 68or the file named 69.Ar filename 70(if invoked with 71.Fl f Ar filename ) . 72.Bl -tag -width indent 73.It Fl D 74Dump the SAD entries. 75If with 76.Fl P , 77the SPD entries are dumped. 78.It Fl F 79Flush the SAD entries. 80If with 81.Fl P , 82the SPD entries are flushed. 83.It Fl a 84The 85.Nm 86utility 87usually does not display dead SAD entries with 88.Fl D . 89If with 90.Fl a , 91the dead SAD entries will be displayed as well. 92A dead SAD entry means that 93it has been expired but remains in the system 94because it is referenced by some SPD entries. 95.It Fl h 96Add hexadecimal dump on 97.Fl x 98mode. 99.It Fl l 100Loop forever with short output on 101.Fl D . 102.It Fl v 103Be verbose. 104The program will dump messages exchanged on 105.Dv PF_KEY 106socket, including messages sent from other processes to the kernel. 107.It Fl x 108Loop forever and dump all the messages transmitted to 109.Dv PF_KEY 110socket. 111.Fl xx 112makes each timestamps unformatted. 113.El 114.Ss Configuration syntax 115With 116.Fl c 117or 118.Fl f 119on the command line, 120.Nm 121accepts the following configuration syntax. 122Lines starting with hash signs 123.Pq Ql # 124are treated as comment lines. 125.Bl -tag -width indent 126.It Xo 127.Li add 128.Op Fl 46n 129.Ar src Ar dst Ar protocol Ar spi 130.Op Ar extensions 131.Ar algorithm ... 132.Li ; 133.Xc 134Add an SAD entry. 135.Li add 136can fail with multiple reasons, 137including when the key length does not match the specified algorithm. 138.\" 139.It Xo 140.Li get 141.Op Fl 46n 142.Ar src Ar dst Ar protocol Ar spi 143.Li ; 144.Xc 145Show an SAD entry. 146.\" 147.It Xo 148.Li delete 149.Op Fl 46n 150.Ar src Ar dst Ar protocol Ar spi 151.Li ; 152.Xc 153Remove an SAD entry. 154.\" 155.It Xo 156.Li deleteall 157.Op Fl 46n 158.Ar src Ar dst Ar protocol 159.Li ; 160.Xc 161Remove all SAD entries that match the specification. 162.\" 163.It Xo 164.Li flush 165.Op Ar protocol 166.Li ; 167.Xc 168Clear all SAD entries matched by the options. 169.Fl F 170on the command line achieves the same functionality. 171.\" 172.It Xo 173.Li dump 174.Op Ar protocol 175.Li ; 176.Xc 177Dumps all SAD entries matched by the options. 178.Fl D 179on the command line achieves the same functionality. 180.\" 181.It Xo 182.Li spdadd 183.Op Fl 46n 184.Ar src_range Ar dst_range Ar upperspec Ar policy 185.Li ; 186.Xc 187Add an SPD entry. 188.\" 189.It Xo 190.Li spddelete 191.Op Fl 46n 192.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction 193.Li ; 194.Xc 195Delete an SPD entry. 196.\" 197.It Xo 198.Li spdflush 199.Li ; 200.Xc 201Clear all SPD entries. 202.Fl FP 203on the command line achieves the same functionality. 204.\" 205.It Xo 206.Li spddump 207.Li ; 208.Xc 209Dumps all SPD entries. 210.Fl DP 211on the command line achieves the same functionality. 212.El 213.\" 214.Pp 215Meta-arguments are as follows: 216.Pp 217.Bl -tag -compact -width indent 218.It Ar src 219.It Ar dst 220Source/destination of the secure communication is specified as 221IPv4/v6 address. 222The 223.Nm 224utility 225can resolve a FQDN into numeric addresses. 226If the FQDN resolves into multiple addresses, 227.Nm 228will install multiple SAD/SPD entries into the kernel 229by trying all possible combinations. 230.Fl 4 , 231.Fl 6 232and 233.Fl n 234restricts the address resolution of FQDN in certain ways. 235.Fl 4 236and 237.Fl 6 238restrict results into IPv4/v6 addresses only, respectively. 239.Fl n 240avoids FQDN resolution and requires addresses to be numeric addresses. 241.\" 242.Pp 243.It Ar protocol 244.Ar protocol 245is one of following: 246.Bl -tag -width Fl -compact 247.It Li esp 248ESP based on rfc2406 249.It Li esp-old 250ESP based on rfc1827 251.It Li ah 252AH based on rfc2402 253.It Li ah-old 254AH based on rfc1826 255.It Li ipcomp 256IPComp 257.It Li tcp 258TCP-MD5 based on rfc2385 259.El 260.\" 261.Pp 262.It Ar spi 263Security Parameter Index 264(SPI) 265for the SAD and the SPD. 266.Ar spi 267must be a decimal number, or a hexadecimal number with 268.Ql 0x 269prefix. 270SPI values between 0 and 255 are reserved for future use by IANA 271and they cannot be used. 272TCP-MD5 associations must use 0x1000 and therefore only have per-host 273granularity at this time. 274.\" 275.Pp 276.It Ar extensions 277take some of the following: 278.Bl -tag -width Fl -compact 279.\" 280.It Fl m Ar mode 281Specify a security protocol mode for use. 282.Ar mode 283is one of following: 284.Li transport , tunnel 285or 286.Li any . 287The default value is 288.Li any . 289.\" 290.It Fl r Ar size 291Specify window size of bytes for replay prevention. 292.Ar size 293must be decimal number in 32-bit word. 294If 295.Ar size 296is zero or not specified, replay check does not take place. 297.\" 298.It Fl u Ar id 299Specify the identifier of the policy entry in SPD. 300See 301.Ar policy . 302.\" 303.It Fl f Ar pad_option 304defines the content of the ESP padding. 305.Ar pad_option 306is one of following: 307.Bl -tag -width random-pad -compact 308.It Li zero-pad 309All of the padding are zero. 310.It Li random-pad 311A series of randomized values are set. 312.It Li seq-pad 313A series of sequential increasing numbers started from 1 are set. 314.El 315.\" 316.It Fl f Li nocyclic-seq 317Do not allow cyclic sequence number. 318.\" 319.It Fl lh Ar time 320.It Fl ls Ar time 321Specify hard/soft life time duration of the SA. 322.El 323.\" 324.Pp 325.It Ar algorithm 326.Bl -tag -width Fl -compact 327.It Fl E Ar ealgo Ar key 328Specify an encryption algorithm 329.Ar ealgo 330for ESP. 331.It Xo 332.Fl E Ar ealgo Ar key 333.Fl A Ar aalgo Ar key 334.Xc 335Specify a encryption algorithm 336.Ar ealgo , 337as well as a payload authentication algorithm 338.Ar aalgo , 339for ESP. 340.It Fl A Ar aalgo Ar key 341Specify an authentication algorithm for AH. 342.It Fl C Ar calgo Op Fl R 343Specify a compression algorithm for IPComp. 344If 345.Fl R 346is specified, 347.Ar spi 348field value will be used as the IPComp CPI 349(compression parameter index) 350on wire as is. 351If 352.Fl R 353is not specified, 354the kernel will use well-known CPI on wire, and 355.Ar spi 356field will be used only as an index for kernel internal usage. 357.El 358.Pp 359.Ar key 360must be double-quoted character string, or a series of hexadecimal digits 361preceded by 362.Ql 0x . 363.Pp 364Possible values for 365.Ar ealgo , 366.Ar aalgo 367and 368.Ar calgo 369are specified in separate section. 370.\" 371.Pp 372.It Ar src_range 373.It Ar dst_range 374These are selections of the secure communication specified as 375IPv4/v6 address or IPv4/v6 address range, and it may accompany 376TCP/UDP port specification. 377This takes the following form: 378.Bd -literal -offset 379.Ar address 380.Ar address/prefixlen 381.Ar address[port] 382.Ar address/prefixlen[port] 383.Ed 384.Pp 385.Ar prefixlen 386and 387.Ar port 388must be decimal number. 389The square bracket around 390.Ar port 391is really necessary. 392They 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 401Upper-layer protocol to be used. 402You can use one of words in 403.Pa /etc/protocols 404as 405.Ar upperspec . 406Or 407.Li icmp6 , 408.Li ip4 , 409and 410.Li any 411can be specified. 412.Li any 413stands for 414.Dq any protocol . 415Also you can use the protocol number. 416You can specify a type and/or a code of ICMPv6 when 417upper-layer protocol is ICMPv6. 418The specification can be placed after 419.Li icmp6 . 420A type is separated with a code by single comma. 421A code must be specified anytime. 422When a zero is specified, the kernel deals with it as a wildcard. 423Note that the kernel cannot distinguish a wildcard from that a type 424of ICMPv6 is zero. 425For example, the following means the policy does not require IPsec 426for any inbound Neighbor Solicitation: 427.Pp 428.Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;" 429.Pp 430NOTE: 431.Ar upperspec 432does not work against forwarding case at this moment, 433as it requires extra reassembly at forwarding node 434(not implemented at this moment). 435We have many protocols in 436.Pa /etc/protocols , 437but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec. 438You have to consider and be careful to use them. 439.\" 440.Pp 441.It Ar policy 442.Ar policy 443is the one of the following three formats: 444.Bd -ragged -offset indent 445.It Fl P Ar direction Li discard 446.It Fl P Ar direction Li none 447.It Xo Fl P Ar direction Li ipsec 448.Ar protocol/mode/src-dst/level Op ... 449.Xc 450.Ed 451.Pp 452You must specify the direction of its policy as 453.Ar direction . 454Either 455.Li out 456or 457.Li in 458are used. 459.Li discard 460means the packet matching indexes will be discarded. 461.Li none 462means that IPsec operation will not take place onto the packet. 463.Li ipsec 464means that IPsec operation will take place onto the packet. 465The part of 466.Ar protocol/mode/src-dst/level 467specifies the rule how to process the packet. 468Either 469.Li ah , 470.Li esp 471or 472.Li ipcomp 473is to be set as 474.Ar protocol . 475.Ar mode 476is either 477.Li transport 478or 479.Li tunnel . 480If 481.Ar mode 482is 483.Li tunnel , 484you must specify the end-points addresses of the SA as 485.Ar src 486and 487.Ar dst 488with 489.Sq - 490between these addresses which is used to specify the SA to use. 491If 492.Ar mode 493is 494.Li transport , 495both 496.Ar src 497and 498.Ar dst 499can be omitted. 500.Ar level 501is to be one of the following: 502.Li default , use , require 503or 504.Li unique . 505If the SA is not available in every level, the kernel will request 506getting SA to the key exchange daemon. 507.Li default 508means the kernel consults to the system wide default against protocol you 509specified, e.g., 510.Li esp_trans_deflev 511sysctl variable, when the kernel processes the packet. 512.Li use 513means that the kernel use a SA if it is available, 514otherwise the kernel keeps normal operation. 515.Li require 516means SA is required whenever the kernel sends a packet matched 517with the policy. 518.Li unique 519is the same to require. 520In addition, it allows the policy to bind with the unique out-bound SA. 521You just specify the policy level 522.Li unique , 523.Xr racoon 8 524will configure the SA for the policy. 525If you configure the SA by manual keying for that policy, 526you can put the decimal number as the policy identifier after 527.Li unique 528separated by colon 529.Ql :\& 530like the following; 531.Li unique:number . 532In order to bind this policy to the SA, 533.Li number 534must be between 1 and 32767. 535It corresponds to 536.Ar extensions Fl u 537of the manual SA configuration. 538When you want to use SA bundle, you can define multiple rules. 539For example, if an IP header was followed by AH header followed by ESP header 540followed by an upper layer protocol header, the rule 541would be: 542.Dl esp/transport//require ah/transport//require ; 543The rule order is very important. 544.Pp 545Note that 546.Dq Li discard 547and 548.Dq Li none 549are not in the syntax described in 550.Xr ipsec_set_policy 3 . 551There are little differences in the syntax. 552See 553.Xr ipsec_set_policy 3 554for detail. 555.Pp 556.El 557.Pp 558.\" 559.Sh ALGORITHMS 560The following list shows the supported algorithms. 561.Sy protocol 562and 563.Sy algorithm 564are almost orthogonal. 565Followings are the list of authentication algorithms that can be used as 566.Ar aalgo 567in 568.Fl A Ar aalgo 569of 570.Ar protocol 571parameter: 572.Pp 573.Bd -literal -offset indent 574algorithm keylen (bits) comment 575hmac-md5 128 ah: rfc2403 576 128 ah-old: rfc2085 577hmac-sha1 160 ah: rfc2404 578 160 ah-old: 128bit ICV (no document) 579keyed-md5 128 ah: 96bit ICV (no document) 580 128 ah-old: rfc1828 581keyed-sha1 160 ah: 96bit ICV (no document) 582 160 ah-old: 128bit ICV (no document) 583null 0 to 2048 for debugging 584hmac-sha2-256 256 ah: 96bit ICV 585 (draft-ietf-ipsec-ciph-sha-256-00) 586 256 ah-old: 128bit ICV (no document) 587hmac-sha2-384 384 ah: 96bit ICV (no document) 588 384 ah-old: 128bit ICV (no document) 589hmac-sha2-512 512 ah: 96bit ICV (no document) 590 512 ah-old: 128bit ICV (no document) 591hmac-ripemd160 160 ah: 96bit ICV (RFC2857) 592 ah-old: 128bit ICV (no document) 593aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 594 128 ah-old: 128bit ICV (no document) 595tcp-md5 8 to 640 tcp: rfc2385 596.Ed 597.Pp 598Followings are the list of encryption algorithms that can be used as 599.Ar ealgo 600in 601.Fl E Ar ealgo 602of 603.Ar protocol 604parameter: 605.Pp 606.Bd -literal -offset indent 607algorithm keylen (bits) comment 608des-cbc 64 esp-old: rfc1829, esp: rfc2405 6093des-cbc 192 rfc2451 610null 0 to 2048 rfc2410 611blowfish-cbc 40 to 448 rfc2451 612cast128-cbc 40 to 128 rfc2451 613des-deriv 64 ipsec-ciph-des-derived-01 6143des-deriv 192 no document 615rijndael-cbc 128/192/256 rfc3602 616aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03 617.Ed 618.Pp 619Note that the first 128 bits of a key for 620.Li aes-ctr 621will be used as AES key, and remaining 32 bits will be used as nonce. 622.Pp 623Followings are the list of compression algorithms that can be used as 624.Ar calgo 625in 626.Fl C Ar calgo 627of 628.Ar protocol 629parameter: 630.Pp 631.Bd -literal -offset indent 632algorithm comment 633deflate rfc2394 634.Ed 635.\" 636.Sh DIAGNOSTICS 637.Ex -std 638.\" 639.Sh EXAMPLES 640.Bd -literal -offset 641add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 642 -E des-cbc 0x3ffe05014819ffff ; 643 644add -6 myhost.example.com yourhost.example.com ah 123456 645 -A hmac-sha1 "AH SA configuration!" ; 646 647add 10.0.11.41 10.0.11.33 esp 0x10001 648 -E des-cbc 0x3ffe05014819ffff 649 -A hmac-md5 "authentication!!" ; 650 651get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 652 653flush ; 654 655dump esp ; 656 657spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 658 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 659 660add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; 661 662.Ed 663.\" 664.Sh SEE ALSO 665.Xr ipsec_set_policy 3 , 666.Xr racoon 8 , 667.Xr sysctl 8 668.Rs 669.%T "Changed manual key configuration for IPsec" 670.%O "http://www.kame.net/newsletter/19991007/" 671.%D "October 1999" 672.Re 673.\" 674.Sh HISTORY 675The 676.Nm 677utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 678The utility was completely re-designed in June 1998. 679.\" 680.Sh BUGS 681The 682.Nm 683utility 684should report and handle syntax errors better. 685.Pp 686For IPsec gateway configuration, 687.Ar src_range 688and 689.Ar dst_range 690with TCP/UDP port number do not work, as the gateway does not reassemble 691packets 692(cannot inspect upper-layer headers). 693