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