1.\" $KAME: setkey.8,v 1.49 2001/05/18 05:49:51 sakane 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 dv 42.Fl c 43.Nm 44.Op Fl dv 45.Fl f Ar filename 46.Nm 47.Op Fl adPlv 48.Fl D 49.Nm 50.Op Fl dPv 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 Ds 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 84Dead SAD entries are usually not displayed with 85.Fl D . 86If with 87.Fl a , 88the dead SAD entries will be displayed as well. 89A dead SAD entry means that 90it has been expired but remains 91because it is referenced by SPD entries. 92.It Fl d 93Enable to print debugging messages for command parser, 94without talking to kernel. 95It is not used usually. 96.It Fl x 97Loop forever and dump all the messages transmitted to 98.Dv PF_KEY 99socket. 100.Fl xx 101makes each timestamps unformatted. 102.It Fl h 103Add hexadecimal dump on 104.Fl x 105mode. 106.It Fl l 107Loop forever with short output on 108.Fl D . 109.It Fl v 110Be verbose. 111The program will dump messages exchanged on 112.Dv PF_KEY 113socket, including messages sent from other processes to the kernel. 114.El 115.Pp 116Operations have the following grammar. 117Note that lines starting with 118hashmarks ('#') are treated as comment lines. 119.Bl -tag -width Ds 120.It Xo 121.Li add 122.Ar src Ar dst Ar protocol Ar spi 123.Op Ar extensions 124.Ar algorithm... 125.Li ; 126.Xc 127Add an SAD entry. 128.\" 129.It Xo 130.Li get 131.Ar src Ar dst Ar protocol Ar spi 132.Li ; 133.Xc 134Show an SAD entry. 135.\" 136.It Xo 137.Li delete 138.Ar src Ar dst Ar protocol Ar spi 139.Li ; 140.Xc 141Remove an SAD entry. 142.\" 143.It Xo 144.Li deleteall 145.Ar src Ar dst Ar protocol 146.Li ; 147.Xc 148Remove all SAD entries that match the specification. 149.\" 150.It Xo 151.Li flush 152.Op Ar protocol 153.Li ; 154.Xc 155Clear all SAD entries matched by the options. 156.\" 157.It Xo 158.Li dump 159.Op Ar protocol 160.Li ; 161.Xc 162Dumps all SAD entries matched by the options. 163.\" 164.It Xo 165.Li spdadd 166.Ar src_range Ar dst_range Ar upperspec Ar policy 167.Li ; 168.Xc 169Add an SPD entry. 170.\" 171.It Xo 172.Li spddelete 173.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction 174.Li ; 175.Xc 176Delete an SPD entry. 177.\" 178.It Xo 179.Li spdflush 180.Li ; 181.Xc 182Clear all SPD entries. 183.\" 184.It Xo 185.Li spddump 186.Li ; 187.Xc 188Dumps all SPD entries. 189.El 190.\" 191.Pp 192Meta-arguments are as follows: 193.Pp 194.Bl -tag -compact -width Ds 195.It Ar src 196.It Ar dst 197Source/destination of the secure communication is specified as 198IPv4/v6 address. 199The 200.Nm 201utility does not consult hostname-to-address for arguments 202.Ar src 203and 204.Ar dst . 205They must be in numeric form. 206.\" 207.Pp 208.It Ar protocol 209.Ar protocol 210is one of following: 211.Bl -tag -width Fl -compact 212.It Li esp 213ESP based on rfc2405 214.It Li esp-old 215ESP based on rfc1827 216.It Li ah 217AH based on rfc2402 218.It Li ah-old 219AH based on rfc1826 220.It Li ipcomp 221IPCOMP 222.El 223.\" 224.Pp 225.It Ar spi 226Security Parameter Index (SPI) for the SAD and the SPD. 227It must be decimal number or hexadecimal number 228You cannot use the set of SPI values in the range 0 through 255. 229(with 230.Li 0x 231attached). 232.\" 233.Pp 234.It Ar extensions 235takes some of the following: 236.Bl -tag -width Fl -compact 237.\" 238.It Fl m Ar mode 239Specify a security protocol mode for use. 240.Ar mode 241is one of following: 242.Li transport , tunnel 243or 244.Li any . 245The default value is 246.Li any . 247.\" 248.It Fl r Ar size 249Specify window size of bytes for replay prevention. 250.Ar size 251must be decimal number in 32-bit word. 252If 253.Ar size 254is zero or not specified, replay check don't take place. 255.\" 256.It Fl u Ar id 257Specify the identifier of the policy entry in SPD. 258See 259.Ar policy . 260.\" 261.It Fl f Ar pad_option 262defines the content of the ESP padding. 263.Ar pad_option 264is one of following: 265.Bl -tag -width random-pad -compact 266.It Li zero-pad 267All of the padding are zero. 268.It Li random-pad 269A series of randomized values are set. 270.It Li seq-pad 271A series of sequential increasing numbers started from 1 are set. 272.El 273.\" 274.It Fl f Li nocyclic-seq 275Don't allow cyclic sequence number. 276.\" 277.It Fl lh Ar time 278.It Fl ls Ar time 279Specify hard/soft life time duration of the SA. 280.El 281.\" 282.Pp 283.It Ar algorithm 284.Bl -tag -width Fl -compact 285.It Fl E Ar ealgo Ar key 286Specify an encryption algorithm. 287.It Fl A Ar aalgo Ar key 288Specify an authentication algorithm. 289If 290.Fl A 291is used with 292.Ar protocol Li esp , 293it will be treated as ESP payload authentication algorithm. 294.It Fl C Ar calgo Op Fl R 295Specify compression algorithm. 296If 297.Fl R 298is not specified with 299.Li ipcomp 300line, the kernel will use well-known IPComp CPI 301(compression parameter index) 302on IPComp CPI field on packets, and 303.Ar spi 304field will be ignored. 305.Ar spi 306field is only for kernel internal use in this case. 307.\"Therefore, compression protocol number will appear on IPComp CPI field. 308If 309.Fl R 310is used, 311the value on 312.Ar spi 313field will appear on IPComp CPI field on outgoing packets. 314.Ar spi 315field needs to be smaller than 316.Li 0x10000 317in this case. 318.El 319.Pp 320.Ar protocol Li esp 321accepts 322.Fl E 323and 324.Fl A . 325.Ar protocol Li esp-old 326accepts 327.Fl E 328only. 329.Ar protocol Li ah 330and 331.Li ah-old 332accept 333.Fl A 334only. 335.Ar protocol Li ipcomp 336accepts 337.Fl C 338only. 339.Pp 340.Ar key 341must be double-quoted character string or series of hexadecimal digits. 342.Pp 343Possible values for 344.Ar ealgo , 345.Ar aalgo 346and 347.Ar calgo 348are specified in separate section. 349.\" 350.Pp 351.It Ar src_range 352.It Ar dst_range 353These are selections of the secure communication specified as 354IPv4/v6 address or IPv4/v6 address range, and it may accompany 355TCP/UDP port specification. 356This takes the following form: 357.Bd -literal -offset 358.Ar address 359.Ar address/prefixlen 360.Ar address[port] 361.Ar address/prefixlen[port] 362.Ed 363.Pp 364.Ar prefixlen 365and 366.Ar port 367must be decimal number. 368The square bracket around 369.Ar port 370is really necessary. 371They are not manpage metacharacters. 372.Pp 373The 374.Nm 375utility does not consult hostname-to-address for arguments 376.Ar src 377and 378.Ar dst . 379They must be in numeric form. 380.\" 381.Pp 382.It Ar upperspec 383Upper-layer protocol to be used. 384You can use one of words in 385.Pa /etc/protocols 386as 387.Ar upperspec . 388Or 389.Li icmp6 , 390.Li ip4 , 391and 392.Li any 393can be specified. 394.Li any 395stands for 396.Dq any protocol . 397Also you can use the protocol number. 398.Pp 399NOTE: 400.Ar upperspec 401does not work against forwarding case at this moment, 402as it requires extra reassembly at forwarding node 403(not implemented at this moment). 404We have many protocols in 405.Pa /etc/protocols , 406but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec. 407You have to consider and be careful to use them. 408.Li icmp 409.Li tcp 410.Li udp 411all protocols 412.\" 413.Pp 414.It Ar policy 415.Ar policy 416is the one of following: 417.Bd -literal -offset 418.Xo 419.Fl P Ar direction Li discard 420.Xc 421.Xo 422.Fl P Ar direction Li none 423.Xc 424.Xo 425.Fl P Ar direction Li ipsec Ar protocol/mode/src-dst/level 426.Xc 427.Ed 428.Pp 429You must specify the direction of its policy as 430.Ar direction . 431Either 432.Li out 433or 434.Li in 435are used. 436.Li discard 437means the packet matching indexes will be discarded. 438.Li none 439means that IPsec operation will not take place onto the packet. 440.Li ipsec 441means that IPsec operation will take place onto the packet. 442Either 443.Li ah , 444.Li esp 445or 446.Li ipcomp 447is to be set as 448.Ar protocol . 449.Ar mode 450is either 451.Li transport 452or 453.Li tunnel . 454If 455.Ar mode 456is 457.Li tunnel , 458you must specify the end-points addresses of the SA as 459.Ar src 460and 461.Ar dst 462with 463.Sq - 464between these addresses which is used to specify the SA to use. 465If 466.Ar mode 467is 468.Li transport , 469both 470.Ar src 471and 472.Ar dst 473can be omitted. 474.Ar level 475is to be one of the following: 476.Li default , use , require 477or 478.Li unique . 479If the SA is not available in every level, the kernel will request 480getting SA to the key exchange daemon. 481.Li default 482means the kernel consults to the system wide default against protocol you 483specified, e.g.\& 484.Li esp_trans_deflev 485sysctl variable, when the kernel processes the packet. 486.Li use 487means that the kernel use a SA if it's available, 488otherwise the kernel keeps normal operation. 489.Li require 490means SA is required whenever the kernel sends a packet matched 491with the policy. 492.Li unique 493is the same to require. 494In addition, it allows the policy to bind with the unique out-bound SA. 495If you use the SA by manual keying, 496you can put the decimal number as the policy identifier after 497.Li unique 498separated by colon 499.Sq \: 500like the following; 501.Li unique:number . 502.Li number 503must be between 1 and 32767. 504It corresponds to 505.Ar extensions Fl u . 506.Pp 507Note that 508.Dq Li discard 509and 510.Dq Li none 511are not in the syntax described in 512.Xr ipsec_set_policy 3 . 513There are little differences in the syntax. 514See 515.Xr ipsec_set_policy 3 516for detail. 517.Pp 518.El 519.Pp 520.\" 521.Sh ALGORITHMS 522The following list shows the supported algorithms. 523.Sy protocol 524and 525.Sy algorithm 526are almost orthogonal. 527Followings are the list of authentication algorithms that can be used as 528.Ar aalgo 529in 530.Fl A Ar aalgo 531of 532.Ar protocol 533parameter: 534.Pp 535.Bd -literal -offset indent 536algorithm keylen (bits) comment 537hmac-md5 128 ah: rfc2403 538 128 ah-old: rfc2085 539hmac-sha1 160 ah: rfc2404 540 160 ah-old: 128bit ICV (no document) 541keyed-md5 128 ah: 96bit ICV (no document) 542 128 ah-old: rfc1828 543keyed-sha1 160 ah: 96bit ICV (no document) 544 160 ah-old: 128bit ICV (no document) 545null 0 to 2048 for debugging 546hmac-sha2-256 256 ah: 96bit ICV (no document) 547 256 ah-old: 128bit ICV (no document) 548hmac-sha2-384 384 ah: 96bit ICV (no document) 549 384 ah-old: 128bit ICV (no document) 550hmac-sha2-512 512 ah: 96bit ICV (no document) 551 512 ah-old: 128bit ICV (no document) 552hmac-ripemd160 160 ah: 96bit ICV (RFC2857) 553 ah-old: 128bit ICV (no document) 554aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 555 128 ah-old: 128bit ICV (no document) 556.Ed 557.Pp 558Followings are the list of encryption algorithms that can be used as 559.Ar ealgo 560in 561.Fl E Ar ealgo 562of 563.Ar protocol 564parameter: 565.Pp 566.Bd -literal -offset indent 567algorithm keylen (bits) comment 568des-cbc 64 esp-old: rfc1829, esp: rfc2405 5693des-cbc 192 rfc2451 570simple 0 to 2048 rfc2410 571blowfish-cbc 40 to 448 rfc2451 572cast128-cbc 40 to 128 rfc2451 573des-deriv 64 ipsec-ciph-des-derived-01 (expired) 5743des-deriv 192 no document 575rijndael-cbc 128/192/256 draft-ietf-ipsec-ciph-aes-cbc-00 576aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03 577.Ed 578.Pp 579Note that the first 128 bits of a key for 580.Li aes-ctr 581will be used as AES key, and remaining 32 bits will be used as nonce. 582.Pp 583Followings are the list of compression algorithms that can be used as 584.Ar calgo 585in 586.Fl C Ar calgo 587of 588.Ar protocol 589parameter: 590.Pp 591.Bd -literal -offset indent 592algorithm comment 593deflate rfc2394 594lzs rfc2395 595.Ed 596.\" 597.Sh EXAMPLES 598.Bd -literal -offset 599add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 600 -E des-cbc "ESP SA!!" ; 601 602add 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 603 -A hmac-sha1 "AH SA configuration!" ; 604 605add 10.0.11.41 10.0.11.33 esp 0x10001 606 -E des-cbc "ESP with" 607 -A hmac-md5 "authentication!!" ; 608 609get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 610 611flush ; 612 613dump esp ; 614 615spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 616 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 617 618.Ed 619.\" 620.Sh RETURN VALUES 621The command exits with 0 on success, and non-zero on errors. 622.\" 623.Sh SEE ALSO 624.Xr ipsec_set_policy 3 , 625.Xr racoon 8 , 626.Xr sysctl 8 627.\" 628.Sh HISTORY 629The 630.Nm 631utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 632The command was completely re-designed in June 1998. 633.\" 634.\" .Sh BUGS 635