.\"	$KAME: setkey.8,v 1.89 2003/09/07 22:17:41 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.

.\"

.\" $FreeBSD: src/usr.sbin/setkey/setkey.8,v 1.34 2005/02/09 18:04:42 ru Exp $

.\"

.Dd November 20, 2000

.Dt SETKEY 8

.Os

.\"

.Sh NAME

.Nm setkey

.Nd "manually manipulate the IPsec SA/SP database"

.\"

.Sh SYNOPSIS

.Nm

.Op Fl v

.Fl c

.Nm

.Op Fl v

.Fl f Ar filename

.Nm

.Op Fl aPlv

.Fl D

.Nm

.Op Fl Pv

.Fl F

.Nm

.Op Fl h

.Fl x

.\"

.Sh DESCRIPTION

The

.Nm

utility adds, updates, dumps, or flushes

Security Association Database (SAD) entries

as well as Security Policy Database (SPD) entries in the kernel.

.Pp

The

.Nm

utility takes a series of operations from the standard input

(if invoked with

.Fl c )

or the file named

.Ar filename

(if invoked with

.Fl f Ar filename ) .

.Bl -tag -width indent

.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

The

.Nm

utility

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

.Pq Ql #

are treated as comment lines.

.Bl -tag -width indent

.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 indent

.It Ar src

.It Ar dst

Source/destination of the secure communication is specified as

IPv4/v6 address.

The

.Nm

utility

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

.It Li tcp

TCP-MD5 based on rfc2385

.El

.\"

.Pp

.It Ar spi

Security Parameter Index

(SPI)

for the SAD and the SPD.

.Ar spi

must be a decimal number, or a hexadecimal number with

.Ql 0x

prefix.

SPI values between 0 and 255 are reserved for future use by IANA

and they cannot be used.

TCP-MD5 associations must use 0x1000 and therefore only have per-host

granularity at this time.

.\"

.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 does not 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

Do not 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 an 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

(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

.Ql 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 -unfilled

.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.

Use one of the 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, use the protocol number.

Specify a type and/or a code of ICMPv6 when

upper-layer protocol is ICMPv6.

The specification can be placed after

.Li icmp6 .

A type is separated with a code by single comma.

A code must be specified anytime.

When a zero is specified, the kernel deals with it as a wildcard.

Note that the kernel cannot distinguish a wildcard from that a type

of ICMPv6 is zero.

For example, the following means the policy does not require IPsec

for any inbound Neighbor Solicitation:

.Pp

.Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"

.Pp

NOTE:

.Ar upperspec

does not work against forwarding case at this moment,

as it requires extra reassembly at forwarding node

(not implemented at this moment).

There are many protocols in

.Pa /etc/protocols ,

but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.

be cautious when using the protocols.

.\"

.Pp

.It Ar policy

.Ar policy

is the one of the following three formats:

.Bd -ragged -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

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 ,

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 the specified protocol 

, for example,

.Li esp_trans_deflev

sysctl variable, when the kernel processes the packet.

.Li use

means that the kernel use a SA if it is 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.

Specify the policy level 

.Li unique ,

.Xr racoon 8

will configure the SA for the policy.

If the SA is configured by manual keying for that policy,

put the decimal number as the policy identifier after

.Li unique

separated by colon