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 a encryption algorithm. 287.It Fl A Ar aalgo Ar key 288Specify a 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 420.Ar direction 421.Li discard 422.Xc 423.Xo 424.Fl P 425.Ar direction 426.Li none 427.Xc 428.Xo 429.Fl P 430.Ar direction 431.Li ipsec 432.Ar protocol/mode/src-dst/level 433.Xc 434.Ed 435.Pp 436You must specify the direction of its policy as 437.Ar direction . 438Either 439.Li out 440or 441.Li in 442are used. 443.Li discard 444means the packet matching indexes will be discarded. 445.Li none 446means that IPsec operation will not take place onto the packet. 447.Li ipsec 448means that IPsec operation will take place onto the packet. 449Either 450.Li ah , 451.Li esp 452or 453.Li ipcomp 454is to be set as 455.Ar protocol . 456.Ar mode 457is either 458.Li transport 459or 460.Li tunnel . 461If 462.Ar mode 463is 464.Li tunnel , 465you must specify the end-points addresses of the SA as 466.Ar src 467and 468.Ar dst 469with 470.Sq - 471between these addresses which is used to specify the SA to use. 472If 473.Ar mode 474is 475.Li transport , 476both 477.Ar src 478and 479.Ar dst 480can be omited. 481.Ar level 482is to be one of the following: 483.Li default , use , require 484or 485.Li unique . 486If the SA is not available in every level, the kernel will request 487getting SA to the key exchange daemon. 488.Li default 489means the kernel consults to the system wide default against protocol you 490specified, e.g.\& 491.Li esp_trans_deflev 492sysctl variable, when the kernel processes the packet. 493.Li use 494means that the kernel use a SA if it's available, 495otherwise the kernel keeps normal operation. 496.Li require 497means SA is required whenever the kernel sends a packet matched 498with the policy. 499.Li unique 500is the same to require. 501In addition, it allows the policy to bind with the unique out-bound SA. 502If you use the SA by manual keying, 503you can put the decimal number as the policy identifier after 504.Li unique 505separated by colon 506.Sq \: 507like the following; 508.Li unique:number . 509.Li number 510must be between 1 and 32767. 511It corresponds to 512.Ar extensions Fl u . 513.Pp 514Note that 515.Dq Li discard 516and 517.Dq Li none 518are not in the syntax described in 519.Xr ipsec_set_policy 3 . 520There are little differences in the syntax. 521See 522.Xr ipsec_set_policy 3 523for detail. 524.Pp 525.El 526.Pp 527.\" 528.Sh ALGORITHMS 529The following list shows the supported algorithms. 530.Sy protocol 531and 532.Sy algorithm 533are almost orthogonal. 534Followings are the list of authentication algorithms that can be used as 535.Ar aalgo 536in 537.Fl A Ar aalgo 538of 539.Ar protocol 540parameter: 541.Pp 542.Bd -literal -offset indent 543algorithm keylen (bits) comment 544hmac-md5 128 ah: rfc2403 545 128 ah-old: rfc2085 546hmac-sha1 160 ah: rfc2404 547 160 ah-old: 128bit ICV (no document) 548keyed-md5 128 ah: 96bit ICV (no document) 549 128 ah-old: rfc1828 550keyed-sha1 160 ah: 96bit ICV (no document) 551 160 ah-old: 128bit ICV (no document) 552null 0 to 2048 for debugging 553hmac-sha2-256 256 ah: 96bit ICV (no document) 554 256 ah-old: 128bit ICV (no document) 555hmac-sha2-384 384 ah: 96bit ICV (no document) 556 384 ah-old: 128bit ICV (no document) 557hmac-sha2-512 512 ah: 96bit ICV (no document) 558 512 ah-old: 128bit ICV (no document) 559.Ed 560.Pp 561Followings are the list of encryption algorithms that can be used as 562.Ar ealgo 563in 564.Fl E Ar ealgo 565of 566.Ar protocol 567parameter: 568.Pp 569.Bd -literal -offset indent 570algorithm keylen (bits) comment 571des-cbc 64 esp-old: rfc1829, esp: rfc2405 5723des-cbc 192 rfc2451 573simple 0 to 2048 rfc2410 574blowfish-cbc 40 to 448 rfc2451 575cast128-cbc 40 to 128 rfc2451 576des-deriv 64 ipsec-ciph-des-derived-01 (expired) 5773des-deriv 192 no document 578rijndael-cbc 128/192/256 draft-ietf-ipsec-ciph-aes-cbc-00 579.Ed 580.Pp 581Followings are the list of compression algorithms that can be used as 582.Ar calgo 583in 584.Fl C Ar calgo 585of 586.Ar protocol 587parameter: 588.Pp 589.Bd -literal -offset indent 590algorithm comment 591deflate rfc2394 592lzs rfc2395 593.Ed 594.\" 595.Sh EXAMPLES 596.Bd -literal -offset 597add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 598 -E des-cbc "ESP SA!!" ; 599 600add 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 601 -A hmac-sha1 "AH SA configuration!" ; 602 603add 10.0.11.41 10.0.11.33 esp 0x10001 604 -E des-cbc "ESP with" 605 -A hmac-md5 "authentication!!" ; 606 607get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; 608 609flush ; 610 611dump esp ; 612 613spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any 614 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; 615 616.Ed 617.\" 618.Sh RETURN VALUES 619The command exits with 0 on success, and non-zero on errors. 620.\" 621.Sh SEE ALSO 622.Xr ipsec_set_policy 3 , 623.Xr racoon 8 , 624.Xr sysctl 8 625.\" 626.Sh HISTORY 627The 628.Nm 629utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. 630The command was completely re-designed in June 1998. 631.\" 632.\" .Sh BUGS 633