From 9b5932fc47f3a7c965da9d2e15425aabc7f7dd26 Mon Sep 17 00:00:00 2001 From: shin Date: Thu, 6 Jan 2000 12:40:54 +0000 Subject: libipsec and IPsec related apps. (and some KAME related man pages) Reviewed by: freebsd-arch, cvs-committers Obtained from: KAME project --- usr.sbin/setkey/setkey.8 | 550 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 usr.sbin/setkey/setkey.8 (limited to 'usr.sbin/setkey/setkey.8') diff --git a/usr.sbin/setkey/setkey.8 b/usr.sbin/setkey/setkey.8 new file mode 100644 index 0000000..1f6f33c --- /dev/null +++ b/usr.sbin/setkey/setkey.8 @@ -0,0 +1,550 @@ +.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: setkey.8,v 1.14 1999/10/27 17:08:58 sakane Exp $ +.\" $FreeBSD$ +.\" +.Dd May 17, 1998 +.Dt SETKEY 8 +.Os KAME +.\" +.Sh NAME +.Nm setkey +.Nd manually manipulate the SA/SP database. +.\" +.Sh SYNOPSIS +.Nm setkey +.Op Fl dv +.Fl c +.Nm setkey +.Op Fl dv +.Fl f Ar filename +.Nm setkey +.Op Fl adPlv +.Fl D +.Nm setkey +.Op Fl dPv +.Fl F +.Nm setkey +.Op Fl h +.Fl x +.\" +.Sh DESCRIPTION +.Nm +updates, or lists the content of, Security Association Database (SAD) entries +in the kernel as well as Security Policy Database (SPD) entries. +.Pp +.Nm +takes a series of operation from standard input +.Po +if invoked with +.Fl c +.Pc +or file named +.Ar filename +.Po +if invoked with +.Fl f Ar filename +.Pc . +.Bl -tag -width Ds +.It Fl D +Dump the SAD entries. +If with +.Fl P , +the SPD entries are dumped. +.It Fl F +Flush the SAD. +If with +.Fl P , +the SPD are flushed. +.It Fl a +.Nm +usually do not display dead SAD entries on +.Fl D . +With +.Fl a , +dead SAD entries will be displayed as well. +Dead SAD entries are kept in the kernel, +when they are referenced from any of SPD entries in the kernel. +.It Fl d +Enable debugging messages. +.It Fl x +Loop forever and dump all the messages transmitted to +.Dv PF_KEY +socket. +.It Fl h +Add hexadecimal dump on +.Fl x +mode. The order is significant. +.It Fl l +Loop forever with short output on +.Fl D . +.It Fl v +Be verbose. +.Dv PF_KEY +socket +.Po +including messages sent from other processes +.Pc . +.El +.Pp +Operation has the following grammar. Note that lines, that start with a +hashmark ('#') are treated as comment lines. +Description of meta-arguments follows. +.Bl -tag -width Ds +.It Xo +.Li add +.Ar src Ar dst Ar protocol Ar spi +.Op Ar extensions +.Ar algorithm... +.Li ; +.Xc +Add a SAD entry. +.\" +.It Xo +.Li get +.Ar src Ar dst Ar protocol Ar spi +.Op Ar mode +.Li ; +.Xc +Show a SAD entry. +.\" +.It Xo +.Li delete +.Ar src Ar dst Ar protocol Ar spi +.Op Ar mode +.Li ; +.Xc +Remove a SAD entry. +.\" +.It Xo +.Li flush +.Op Ar protocol +.Li ; +.Xc +Clear all SAD entries that matches the options. +.\" +.It Xo +.Li dump +.Op Ar protocol +.Li ; +.Xc +Dumps all SAD entries that matches the options. +.\" +.It Xo +.Li spdadd +.Ar src_range Ar dst_range Ar upperspec Ar policy +.Li ; +.Xc +Add a SPD entry. +.\" +.It Xo +.Li spddelete +.Ar src_range Ar dst_range Ar upperspec +.Li ; +.Xc +Delete a SPD entry. +.\" +.It Xo +.Li spdflush +.Li ; +.Xc +Clear all SPD entries. +.\" +.It Xo +.Li spddump +.Li ; +.Xc +Dumps all SAD entries. +.El +.\" +.Pp +Meta-arguments are as follows: +.Bl -tag -compact -width Ds +.It Ar src +.It Ar dst +Source/destination of the secure communication is specified as +IPv4/v6 address. +.Nm +does not consult hostname-to-address for arguments +.Ar src +and +.Ar dst . +They must be in numeric form. +.\" +.Pp +.It Ar protocol +.Ar protocol +is one of following: +.Bl -tag -width Fl -compact +.It Li esp +ESP based on rfc2405 +.It Li esp-old +ESP based on rfc1827 +.It Li ah +AH based on rfc2402 +.It Li ah-old +AH based on rfc1826 +.It Li ipcomp +IPCOMP +.El +.\" +.Pp +.It Ar spi +Security Parameter Index (SPI) for the SA and SPD. +It must be decimal number or hexadecimal number +.Po +with +.Li 0x +attached +.Pc . +.\" +.Pp +.It Ar extensions +takes some of the following: +.Bl -tag -width Fl -compact +.It Fl m Ar mode +Specify an security protocol mode for use. By default, +.Li any . +.Ar mode +is one of following: +.Li transport , tunnel +or +.Li any . +.It Fl r Ar size +Specify window size of bytes for replay prevention. +.Ar size +must be decimal number in 32-bit word. If +.Ar size +is zero or not specified, replay check don't take place. +.It Fl f Ar pad_option +.Ar pad_option +is one of following: +.Li zero-pad , random-pad +or +.Li seq-pad +.It Fl f Li cyclic-seq +Allow cyclic sequence number. +.It Fl lh Ar time +.It Fl ls Ar time +Specify hard/soft lifetime. +.El +.\" +.Pp +.It Ar algorithm +.Bl -tag -width Fl -compact +.It Fl E Ar ealgo Ar key +Specify encryption algorithm. +.It Fl A Ar ealgo Ar key +Specify authentication algorithm. +If +.Fl A +is used for esp, it will be treated as ESP payload authentication algorithm. +.It Fl C Ar calgo Op Fl R +Specify compression algorithm. +If +.Fl R +is specified with +.Li ipcomp +line, the kernel will use well-known IPComp CPI +.Pq compression parameter index +on IPComp CPI field on packets, and +.Ar spi +field will be ignored. +.Ar spi +field is only for kernel internal use in this case. +.\"Therefore, compression protocol number will appear on IPComp CPI field. +If +.Fl R +is not used, +the value on +.Ar spi +field will appear on IPComp CPI field on outgoing packets. +.Ar spi +field needs to be smaller than +.Li 0x10000 +in this case. +.El +.Pp +.Li esp +SAs accept +.Fl E +and +.Fl A . +.Li esp-old +SAs accept +.Fl E +only. +.Li ah +and +.Li ah-old +SAs accept +.Fl A +only. +.Li ipcomp +SAs accept +.Fl C +only. +.Pp +.Ar key +must be double-quoted character string or a series of hexadecimal digits. +.Pp +Possible values for +.Ar ealgo , +.Ar aalgo +and +.Ar calgo +are specified in separate section. +.\" +.It Ar src_range +.It Ar dst_range +These are selection of the secure communication is specified as +IPv4/v6 address or IPv4/v6 address range, and it may accompany +TCP/UDP port specification. +This takes the following form: +.Bd -literal -offset +.Ar address +.Ar address/prefixlen +.Ar address[port] +.Ar address/prefixlen[port] +.Ed +.Pp +.Ar prefixlen +and +.Ar port +must be decimal number. +The square bracket around +.Ar port +is really necessary. +They are not manpage metacharacters. +.Pp +.Nm +does not consult hostname-to-address for arguments +.Ar src +and +.Ar dst . +They must be in numeric form. +.\" +.It Ar upperspec +Upper-layer protocol to be used. +Currently +.Li tcp , +.Li udp +and +.Li any +can be specified. +.Li any +stands for +.Dq any protocol . +.Pp +NOTE: +.Ar upperspec +does not work against forwarding case at this moment, +as it requires extra reassembly at forwarding node +.Pq not implemented as this moment . +.\" +.It Ar policy +.Ar policy +is the one of following: +.Bd -literal -offset +.Xo +.Fl P +.Ar direction +.Li discard +.Xc +.Xo +.Fl P +.Ar direction +.Li none +.Xc +.Xo +.Fl P +.Ar direction +.Li ipsec +.Ar protocol/mode/src-dst/level +.Xc +.Ed +.Pp +You must specify the direction of its policy as +.Ar direction . +Either +.Li out +or +.Li in +are used. +.Li discard +means the packet matching indexes will be discarded. +.Li none +means that IPsec operation will not take place onto the packet. +.Li ipsec +means that IPsec operation will take place onto the packet. +Either +.Li ah , +.Li esp +or +.Li ipcomp +is to be set as +.Ar protocol . +.Ar mode +is either +.Li transport +or +.Li tunnel . +You must specify the end-points addresses of the SA as +.Ar src +and +.Ar dst +with +.Sq - +between these addresses which is used to specify the SA to use. +.Ar level +is to be one of the following: +.Li default , use +or +.Li require . +.Li default +means kernel consults to the system wide default against protocol you +specified, e.g. +.Li esp_trans_deflev +sysctl variable, when kernel processes the packet. +.Li use +means that kernel use a SA if it's available, +otherwise kernel keeps normal operation. +.Li require +means SA is required whenever kernel deals with the packet. +Note that +.Dq Li discard +and +.Dq Li none +are not in the syntax described in +.Xr ipsec_set_policy 3 . +There are little differences in the syntax. +See +.Xr ipsec_set_policy 3 +for detail. +.Pp +.El +.Pp +.\" +.Sh ALGORITHMS +The following list shows the supported algorithms. +.Sy protocol +and +.Sy algorithm +are almost orthogonal. +Following are the list of authentication algorithms that can be used as +.Ar aalgo +in +.Fl A Ar aalgo +of +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm keylen (bits) comment +hmac-md5 128 ah: rfc2403 + 128 ah-old: rfc2085 +hmac-sha1 160 ah: rfc2404 + 160 ah-old: 128bit ICV (no document) +keyed-md5 128 ah: 96bit ICV (no document) + 128 ah-old: rfc1828 +keyed-sha1 160 ah: 96bit ICV (no document) + 160 ah-old: 128bit ICV (no document) +null 0 to 2048 for debugging +.Ed +.Pp +Following are the list of encryption algorithms that can be used as +.Ar ealgo +in +.Fl E Ar ealgo +of +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm keylen (bits) comment +des-cbc 64 esp-old: rfc1829, esp: rfc2405 +3des-cbc 192 rfc2451 +simple 0 to 2048 rfc2410 +blowfish-cbc 40 to 448 rfc2451 +cast128-cbc 40 to 128 rfc2451 +rc5-cbc 40 to 2040 rfc2451 +des-deriv 64 ipsec-ciph-des-derived-01 (expired) +3des-deriv 192 no document +.Ed +.Pp +Following are the list of compression algorithms that can be used as +.Ar calgo +in +.Fl C Ar calgo +of +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm comment +deflate rfc2394 +lzs rfc2395 +.Ed +.\" +.Sh EXAMPLES +.Bd -literal -offset +add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 + -E des-cbc "ESP SA!!" + +add 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 + -A hmac-sha1 "AH SA configuration!" ; + +add 10.0.11.41 10.0.11.33 esp 0x10001 + -E des-cbc "ESP with" + -A hmac-md5 "authentication!!" ; + +get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; + +flush ; + +dump esp ; + +spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any + -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; + +.Ed +.\" +.Sh RETURN VALUES +The command exits with 0 on success, and non-zero on errors. +.\" +.Sh SEE ALSO +.Xr ipsec_set_policy 3 , +.Xr sysctl 8 +.\" +.Sh HISTORY +The +.Nm +command first appeared in WIDE Hydrangea IPv6 protocol stack kit. +The command was completely re-designed in June 1998. +.\" +.\" .Sh BUGS -- cgit v1.1