libipsec and IPsec related apps. (and some KAME related man pages)

Reviewed by: freebsd-arch, cvs-committers
Obtained from: KAME project

1 files changed, 550 insertions, 0 deletions

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