674 lines
14 KiB
Groff
674 lines
14 KiB
Groff
.\" $NetBSD: setkey.8,v 1.24 2003/09/08 06:18:49 itojun Exp $
|
|
.\" $KAME: setkey.8,v 1.90 2003/09/08 06:10:43 itojun Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.Dd September 7, 2003
|
|
.Dt SETKEY 8
|
|
.Os
|
|
.\"
|
|
.Sh NAME
|
|
.Nm setkey
|
|
.Nd manually manipulate the IPsec SA/SP database
|
|
.\"
|
|
.Sh SYNOPSIS
|
|
.Nm setkey
|
|
.Op Fl v
|
|
.Ar file...
|
|
.Nm setkey
|
|
.Op Fl v
|
|
.Fl c
|
|
.Nm setkey
|
|
.Op Fl v
|
|
.Fl f Ar filename
|
|
.Nm setkey
|
|
.Op Fl aPlv
|
|
.Fl D
|
|
.Nm setkey
|
|
.Op Fl Pv
|
|
.Fl F
|
|
.Nm setkey
|
|
.Op Fl h
|
|
.Fl x
|
|
.\"
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
adds, updates, dumps, or flushes
|
|
Security Association Database (SAD) entries
|
|
as well as Security Policy Database (SPD) entries in the kernel.
|
|
.Pp
|
|
.Nm
|
|
takes a series of operations from the standard input
|
|
.Po
|
|
if invoked with
|
|
.Fl c
|
|
.Pc
|
|
or the file named
|
|
.Ar filename
|
|
.Po
|
|
if invoked with
|
|
.Fl f Ar filename
|
|
.Pc .
|
|
.Bl -tag -width Ds
|
|
.It (no flag)
|
|
Dump the SAD entries or SPD entries contained in the specified
|
|
.Ar file .
|
|
.It Fl D
|
|
Dump the SAD entries.
|
|
If with
|
|
.Fl P ,
|
|
the SPD entries are dumped.
|
|
.It Fl F
|
|
Flush the SAD entries.
|
|
If with
|
|
.Fl P ,
|
|
the SPD entries are flushed.
|
|
.It Fl a
|
|
.Nm
|
|
usually does not display dead SAD entries with
|
|
.Fl D .
|
|
If with
|
|
.Fl a ,
|
|
the dead SAD entries will be displayed as well.
|
|
A dead SAD entry means that
|
|
it has been expired but remains in the system
|
|
because it is referenced by some SPD entries.
|
|
.It Fl h
|
|
Add hexadecimal dump on
|
|
.Fl x
|
|
mode.
|
|
.It Fl l
|
|
Loop forever with short output on
|
|
.Fl D .
|
|
.It Fl v
|
|
Be verbose.
|
|
The program will dump messages exchanged on
|
|
.Dv PF_KEY
|
|
socket, including messages sent from other processes to the kernel.
|
|
.It Fl x
|
|
Loop forever and dump all the messages transmitted to
|
|
.Dv PF_KEY
|
|
socket.
|
|
.Fl xx
|
|
makes each timestamps unformatted.
|
|
.El
|
|
.Ss Configuration syntax
|
|
With
|
|
.Fl c
|
|
or
|
|
.Fl f
|
|
on the command line,
|
|
.Nm
|
|
accepts the following configuration syntax.
|
|
Lines starting with hash signs ('#') are treated as comment lines.
|
|
.Bl -tag -width Ds
|
|
.It Xo
|
|
.Li add
|
|
.Op Fl 46n
|
|
.Ar src Ar dst Ar protocol Ar spi
|
|
.Op Ar extensions
|
|
.Ar algorithm ...
|
|
.Li ;
|
|
.Xc
|
|
Add an SAD entry.
|
|
.Li add
|
|
can fail with multiple reasons,
|
|
including when the key length does not match the specified algorithm.
|
|
.\"
|
|
.It Xo
|
|
.Li get
|
|
.Op Fl 46n
|
|
.Ar src Ar dst Ar protocol Ar spi
|
|
.Li ;
|
|
.Xc
|
|
Show an SAD entry.
|
|
.\"
|
|
.It Xo
|
|
.Li delete
|
|
.Op Fl 46n
|
|
.Ar src Ar dst Ar protocol Ar spi
|
|
.Li ;
|
|
.Xc
|
|
Remove an SAD entry.
|
|
.\"
|
|
.It Xo
|
|
.Li deleteall
|
|
.Op Fl 46n
|
|
.Ar src Ar dst Ar protocol
|
|
.Li ;
|
|
.Xc
|
|
Remove all SAD entries that match the specification.
|
|
.\"
|
|
.It Xo
|
|
.Li flush
|
|
.Op Ar protocol
|
|
.Li ;
|
|
.Xc
|
|
Clear all SAD entries matched by the options.
|
|
.Fl F
|
|
on the command line achieves the same functionality.
|
|
.\"
|
|
.It Xo
|
|
.Li dump
|
|
.Op Ar protocol
|
|
.Li ;
|
|
.Xc
|
|
Dumps all SAD entries matched by the options.
|
|
.Fl D
|
|
on the command line achieves the same functionality.
|
|
.\"
|
|
.It Xo
|
|
.Li spdadd
|
|
.Op Fl 46n
|
|
.Ar src_range Ar dst_range Ar upperspec Ar policy
|
|
.Li ;
|
|
.Xc
|
|
Add an SPD entry.
|
|
.\"
|
|
.It Xo
|
|
.Li spddelete
|
|
.Op Fl 46n
|
|
.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
|
|
.Li ;
|
|
.Xc
|
|
Delete an SPD entry.
|
|
.\"
|
|
.It Xo
|
|
.Li spdflush
|
|
.Li ;
|
|
.Xc
|
|
Clear all SPD entries.
|
|
.Fl FP
|
|
on the command line achieves the same functionality.
|
|
.\"
|
|
.It Xo
|
|
.Li spddump
|
|
.Li ;
|
|
.Xc
|
|
Dumps all SPD entries.
|
|
.Fl DP
|
|
on the command line achieves the same functionality.
|
|
.El
|
|
.\"
|
|
.Pp
|
|
Meta-arguments are as follows:
|
|
.Pp
|
|
.Bl -tag -compact -width Ds
|
|
.It Ar src
|
|
.It Ar dst
|
|
Source/destination of the secure communication is specified as
|
|
IPv4/v6 address.
|
|
.Nm
|
|
can resolve a FQDN into numeric addresses.
|
|
If the FQDN resolves into multiple addresses,
|
|
.Nm
|
|
will install multiple SAD/SPD entries into the kernel
|
|
by trying all possible combinations.
|
|
.Fl 4 ,
|
|
.Fl 6
|
|
and
|
|
.Fl n
|
|
restricts the address resolution of FQDN in certain ways.
|
|
.Fl 4
|
|
and
|
|
.Fl 6
|
|
restrict results into IPv4/v6 addresses only, respectively.
|
|
.Fl n
|
|
avoids FQDN resolution and requires addresses to be numeric addresses.
|
|
.\"
|
|
.Pp
|
|
.It Ar protocol
|
|
.Ar protocol
|
|
is one of following:
|
|
.Bl -tag -width Fl -compact
|
|
.It Li esp
|
|
ESP based on rfc2406
|
|
.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
|
|
.Pq SPI
|
|
for the SAD and the SPD.
|
|
.Ar spi
|
|
must be a decimal number, or a hexadecimal number with
|
|
.Dq Li 0x
|
|
prefix.
|
|
SPI values between 0 and 255 are reserved for future use by IANA
|
|
and they cannot be used.
|
|
.\"
|
|
.Pp
|
|
.It Ar extensions
|
|
take some of the following:
|
|
.Bl -tag -width Fl -compact
|
|
.\"
|
|
.It Fl m Ar mode
|
|
Specify a security protocol mode for use.
|
|
.Ar mode
|
|
is one of following:
|
|
.Li transport , tunnel
|
|
or
|
|
.Li any .
|
|
The default value is
|
|
.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 u Ar id
|
|
Specify the identifier of the policy entry in SPD.
|
|
See
|
|
.Ar policy .
|
|
.\"
|
|
.It Fl f Ar pad_option
|
|
defines the content of the ESP padding.
|
|
.Ar pad_option
|
|
is one of following:
|
|
.Bl -tag -width random-pad -compact
|
|
.It Li zero-pad
|
|
All of the padding are zero.
|
|
.It Li random-pad
|
|
A series of randomized values are set.
|
|
.It Li seq-pad
|
|
A series of sequential increasing numbers started from 1 are set.
|
|
.El
|
|
.\"
|
|
.It Fl f Li nocyclic-seq
|
|
Don't allow cyclic sequence number.
|
|
.\"
|
|
.It Fl lh Ar time
|
|
.It Fl ls Ar time
|
|
Specify hard/soft life time duration of the SA.
|
|
.El
|
|
.\"
|
|
.Pp
|
|
.It Ar algorithm
|
|
.Bl -tag -width Fl -compact
|
|
.It Fl E Ar ealgo Ar key
|
|
Specify a encryption algorithm
|
|
.Ar ealgo
|
|
for ESP.
|
|
.It Xo
|
|
.Fl E Ar ealgo Ar key
|
|
.Fl A Ar aalgo Ar key
|
|
.Xc
|
|
Specify a encryption algorithm
|
|
.Ar ealgo ,
|
|
as well as a payload authentication algorithm
|
|
.Ar aalgo ,
|
|
for ESP.
|
|
.It Fl A Ar aalgo Ar key
|
|
Specify an authentication algorithm for AH.
|
|
.It Fl C Ar calgo Op Fl R
|
|
Specify a compression algorithm for IPComp.
|
|
If
|
|
.Fl R
|
|
is specified,
|
|
.Ar spi
|
|
field value will be used as the IPComp CPI
|
|
.Pq compression parameter index
|
|
on wire as is.
|
|
If
|
|
.Fl R
|
|
is not specified,
|
|
the kernel will use well-known CPI on wire, and
|
|
.Ar spi
|
|
field will be used only as an index for kernel internal usage.
|
|
.El
|
|
.Pp
|
|
.Ar key
|
|
must be double-quoted character string, or a series of hexadecimal digits
|
|
preceded by
|
|
.Dq Li 0x .
|
|
.Pp
|
|
Possible values for
|
|
.Ar ealgo ,
|
|
.Ar aalgo
|
|
and
|
|
.Ar calgo
|
|
are specified in separate section.
|
|
.\"
|
|
.Pp
|
|
.It Ar src_range
|
|
.It Ar dst_range
|
|
These are selections of the secure communication 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.
|
|
For FQDN resolution, the rules applicable to
|
|
.Ar src
|
|
and
|
|
.Ar dst
|
|
apply here as well.
|
|
.\"
|
|
.Pp
|
|
.It Ar upperspec
|
|
Upper-layer protocol to be used.
|
|
You can use one of words in
|
|
.Pa /etc/protocols
|
|
as
|
|
.Ar upperspec .
|
|
Or
|
|
.Li icmp6 ,
|
|
.Li ip4 ,
|
|
and
|
|
.Li any
|
|
can be specified.
|
|
.Li any
|
|
stands for
|
|
.Dq any protocol .
|
|
Also you can use the protocol number.
|
|
.Pp
|
|
NOTE:
|
|
.Ar upperspec
|
|
does not work against forwarding case at this moment,
|
|
as it requires extra reassembly at forwarding node
|
|
.Pq not implemented at this moment .
|
|
We have many protocols in
|
|
.Pa /etc/protocols ,
|
|
but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.
|
|
You have to consider and be careful to use them.
|
|
.\"
|
|
.Pp
|
|
.It Ar policy
|
|
.Ar policy
|
|
is the one of the following three formats:
|
|
.Bd -literal -offset indent
|
|
.It Fl P Ar direction Li discard
|
|
.It Fl P Ar direction Li none
|
|
.It Xo Fl P Ar direction Li ipsec
|
|
.Ar protocol/mode/src-dst/level Op ...
|
|
.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.
|
|
The part of
|
|
.Ar protocol/mode/src-dst/level
|
|
specifies the rule how to process 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 .
|
|
If
|
|
.Ar mode
|
|
is
|
|
.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.
|
|
If
|
|
.Ar mode
|
|
is
|
|
.Li transport ,
|
|
both
|
|
.Ar src
|
|
and
|
|
.Ar dst
|
|
can be omitted.
|
|
.Ar level
|
|
is to be one of the following:
|
|
.Li default , use , require
|
|
or
|
|
.Li unique .
|
|
If the SA is not available in every level, the kernel will request
|
|
getting SA to the key exchange daemon.
|
|
.Li default
|
|
means the kernel consults to the system wide default against protocol you
|
|
specified, e.g.
|
|
.Li esp_trans_deflev
|
|
sysctl variable, when the kernel processes the packet.
|
|
.Li use
|
|
means that the kernel use a SA if it's available,
|
|
otherwise the kernel keeps normal operation.
|
|
.Li require
|
|
means SA is required whenever the kernel sends a packet matched
|
|
with the policy.
|
|
.Li unique
|
|
is the same to require,
|
|
in addition, it allows the policy to bind with the unique out-bound SA.
|
|
You just specify the policy level
|
|
.Li unique ,
|
|
.Xr racoon 8
|
|
will configure the SA for the policy.
|
|
If you configure the SA by manual keying for that policy,
|
|
you can put the decimal number as the policy identifier after
|
|
.Li unique
|
|
separated by colon
|
|
.Sq \&:
|
|
like the following;
|
|
.Li unique:number .
|
|
in order to bind this policy to the SA.
|
|
.Li number
|
|
must be between 1 and 32767.
|
|
It corresponds to
|
|
.Ar extensions Fl u
|
|
of the manual SA configuration.
|
|
When you want to use SA bundle, you can define multiple rules.
|
|
For example, if an IP header was followed by AH header followed by ESP header
|
|
followed by an upper layer protocol header, the rule
|
|
would be:
|
|
.Dl esp/transport//require ah/transport//require ;
|
|
The rule order is very important.
|
|
.Pp
|
|
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
|
|
.\"
|
|
.Ss Algorithms
|
|
The following list shows the supported algorithms.
|
|
.Sy protocol
|
|
and
|
|
.Sy algorithm
|
|
are almost orthogonal.
|
|
Followings 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)
|
|
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
|
|
hmac-sha2-256 256 ah: 96bit ICV
|
|
(draft-ietf-ipsec-ciph-sha-256-00)
|
|
256 ah-old: 128bit ICV (no document)
|
|
hmac-sha2-384 384 ah: 96bit ICV (no document)
|
|
384 ah-old: 128bit ICV (no document)
|
|
hmac-sha2-512 512 ah: 96bit ICV (no document)
|
|
512 ah-old: 128bit ICV (no document)
|
|
hmac-ripemd160 160 ah: 96bit ICV (RFC2857)
|
|
ah-old: 128bit ICV (no document)
|
|
aes-xcbc-mac 128 ah: 96bit ICV
|
|
(draft-ietf-ipsec-ciph-aes-xcbc-mac-04)
|
|
128 ah-old: 128bit ICV (no document)
|
|
.Ed
|
|
.Pp
|
|
Followings 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)
|
|
des-cbc 64 esp-old: rfc1829, esp: rfc2405
|
|
3des-cbc 192 rfc2451
|
|
null 0 to 2048 rfc2410
|
|
blowfish-cbc 40 to 448 rfc2451
|
|
cast128-cbc 40 to 128 rfc2451
|
|
des-deriv 64 ipsec-ciph-des-derived-01
|
|
3des-deriv 192 no document
|
|
rijndael-cbc 128/192/256 draft-ietf-ipsec-ciph-aes-cbc-01
|
|
aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03
|
|
.Ed
|
|
.Pp
|
|
Note that the first 128 bits of a key for
|
|
.Li aes-ctr
|
|
will be used as AES key, and remaining 32 bits will be used as nonce.
|
|
.Pp
|
|
Followings 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
|
|
deflate rfc2394
|
|
.Ed
|
|
.\"
|
|
.Sh EXIT STATUS
|
|
The command exits with 0 on success, and non-zero on errors.
|
|
.\"
|
|
.Sh EXAMPLES
|
|
.Bd -literal -offset
|
|
add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
|
|
-E des-cbc 0x3ffe05014819ffff ;
|
|
|
|
add -6 myhost.example.com yourhost.example.com ah 123456
|
|
-A hmac-sha1 "AH SA configuration!" ;
|
|
|
|
add 10.0.11.41 10.0.11.33 esp 0x10001
|
|
-E des-cbc 0x3ffe05014819ffff
|
|
-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 SEE ALSO
|
|
.Xr ipsec_set_policy 3 ,
|
|
.Xr racoon 8 ,
|
|
.Xr sysctl 8
|
|
.Rs
|
|
.%T "Changed manual key configuration for IPsec"
|
|
.%O "http://www.kame.net/newsletter/19991007/"
|
|
.%D "October 1999"
|
|
.Re
|
|
.\"
|
|
.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
|
|
.Nm
|
|
should report and handle syntax errors better.
|
|
.Pp
|
|
For IPsec gateway configuration,
|
|
.Ar src_range
|
|
and
|
|
.Ar dst_range
|
|
with TCP/UDP port number do not work, as the gateway does not reassemble
|
|
packets
|
|
.Pq cannot inspect upper-layer headers .
|