.\" $OpenBSD: ipsecadm.8,v 1.67 2004/09/26 07:16:54 jaredy Exp $
.\"
.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Niels Provos.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
.\"
.\" Manual page, using -mandoc macros
.\"
.Dd August 26, 1997
.Dt IPSECADM 8
.Os
.Sh NAME
.Nm ipsecadm
.Nd interface to set up IPsec
.Sh SYNOPSIS
.Nm ipsecadm
.Ar command Op Ar modifier ...
.Sh NOTE
To use
.Nm ,
.Xr ipsec 4
must be enabled by having one or more of the following
.Xr sysctl 3
variables set:
.Pp
.Bl -tag -offset 4n -width net.inet.ipcomp.enable -compact
.It Va net.inet.esp.enable
Enable the ESP IPsec protocol
.It Va net.inet.ah.enable
Enable the AH IPsec protocol
.It Va net.inet.ipcomp.enable
Enable the IPComp protocol
.El
.Pp
Both the ESP and AH protocols are enabled by default.
To keep local modifications of these variables across reboots, see
.Xr sysctl.conf 5 .
.Sh DESCRIPTION
The
.Nm
utility sets up security associations in the kernel
to be used with
.Xr ipsec 4 .
It can be used to specify the encryption and authentication
algorithms and key material for the network layer security
provided by IPsec.
The possible commands are:
.Bl -tag -width new_esp
.It Cm new esp
Set up a Security Association (SA) which uses the new ESP transforms.
An SA consists of the destination address,
a Security Parameter Index (SPI) and a security protocol.
Encryption and authentication algorithms can be applied.
This is the default mode.
Allowed
modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl enc ,
.Fl srcid_type ,
.Fl srcid ,
.Fl dstid_type ,
.Fl dstid ,
.Fl auth ,
.Fl authkey ,
.Fl authkeyfile ,
.Fl forcetunnel ,
.Fl udpencap ,
.Fl key ,
and
.Fl keyfile .
.It Cm old esp
Set up an SA which uses the old ESP transforms.
Only encryption algorithms can be applied.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl enc ,
.Fl srcid_type ,
.Fl srcid ,
.Fl dstid_type ,
.Fl dstid ,
.Fl halfiv ,
.Fl forcetunnel ,
.Fl key ,
and
.Fl keyfile .
.It Cm new ah
Set up an SA which uses the new AH transforms.
Authentication will be done with Hashed Message Authentication Code
(HMAC) using the specified hash algorithm.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl srcid_type ,
.Fl srcid ,
.Fl dstid_type ,
.Fl dstid ,
.Fl forcetunnel ,
.Fl auth ,
.Fl key ,
and
.Fl keyfile .
.It Cm old ah
Set up an SA which uses the old AH transforms.
Simple keyed hashes will be used for authentication.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl srcid_type ,
.Fl srcid ,
.Fl dstid_type ,
.Fl dstid ,
.Fl forcetunnel ,
.Fl auth ,
.Fl key ,
and
.Fl keyfile .
.It Cm group
Group two SAs together, such that whenever the first one is applied, the
second one will be applied as well (SA bundle).
Arbitrarily long SA bundles can thus be created.
Note that the last SA in the bundle is the one that is applied last.
Thus, if an ESP and an AH SA are bundled together (in that order), then
the resulting packet will have an AH header, followed by an ESP header,
followed by the encrypted payload.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
.Fl proto ,
.Fl dst2 ,
.Fl spi2 ,
and
.Fl proto2 .
.It Cm ip4
Set up an SA which uses the IP-in-IP encapsulation protocol.
This mode
offers no security services by itself but can be used to route other
(experimental or otherwise) protocols over an IP network.
The SPI value
is not used for anything other than referencing the information and
does not appear on the wire.
Unlike other setups, like new ESP, there
is no necessary setup in the receiving side.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
and
.Fl spi .
.It Cm delspi
Delete the specified SA.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
and
.Fl proto .
.It Cm flow
Create a flow determining what security parameters a packet should
have (input or output).
Allowed modifiers are:
.Fl src ,
.Fl dst ,
.Fl proto ,
.Fl addr ,
.Fl transport ,
.Fl sport ,
.Fl dport ,
.Fl delete ,
.Fl in ,
.Fl out ,
.Fl srcid ,
.Fl dstid ,
.Fl srcid_type ,
.Fl dstid_type ,
.Fl acquire ,
.Fl require ,
.Fl dontacq ,
.Fl use ,
.Fl bypass ,
.Fl permit
and
.Fl deny .
.Pp
The
.Xr netstat 1
command shows all specified flows.
.Pp
Flows are directional, and the
.Fl in
and
.Fl out
modifiers are used to specify the direction.
By default, flows are assumed to apply to outgoing packets.
The kernel will attempt to find an appropriate
Security Association from those already present (an SA that matches
the destination address, if set, and the security protocol).
If the destination address is set to all zeroes (0.0.0.0) or left
unspecified, the destination address from the packet will be used
to locate an SA (the source address is used for incoming flows).
For incoming flows, the destination address (if specified) should
point to the expected source of the SA (the remote SA peer).
.Pp
If no such SA exists, key management daemons will be used to generate
them if
.Fl acquire
or
.Fl require
were used.
If
.Fl acquire
was used, traffic will be allowed out (or in) and IPsec will be used
when the relevant SAs have been established.
If
.Fl require
was used, traffic will not be allowed in or out until it is protected
by IPsec.
If
.Fl dontacq
was used, traffic will not be allowed in or out until it is protected
by IPsec, but key management will not be asked to provide such an SA.
The
.Fl proto
argument (by default set to
.Cm esp )
can be used to determine what type of SA should be established.
.Pp
A
.Em bypass
or
.Em permit
flow (created with
.Fl bypass
or
.Fl permit )
is used to specify a flow for which IPsec processing will be
bypassed, i.e., packets will/need not be processed by any SAs.
For bypass or permit
flows, additional modifiers are restricted to:
.Fl addr ,
.Fl transport ,
.Fl sport ,
.Fl dport ,
.Fl in ,
.Fl out ,
and
.Fl delete .
A
.Em deny
flow is used to specify classes of packets that must be dropped
(either on output or input) without further processing.
.Fl deny
takes the same additional modifiers as
.Fl bypass .
.It Cm flush
Flush SAs from kernel.
This includes flushing any flows and
routing entries associated with the SAs.
Allowed modifiers are:
.Fl ah ,
.Fl esp ,
.Fl oldah ,
.Fl oldesp ,
.Fl ip4 ,
.Fl ipcomp ,
and
.Fl tcpmd5 .
Default action is to flush all types of security associations
from the kernel.
.It Cm show
Show SAs from kernel.
Allowed modifiers are:
.Fl ah ,
.Fl esp ,
.Fl oldah ,
.Fl oldesp ,
.Fl ip4 ,
.Fl ipcomp ,
and
.Fl tcpmd5 .
Default action is to show all types of security associations
from the kernel.
.It Cm monitor
Continuously display all
.Dv PF_KEY
messages exchanged with
the kernel.
.It Cm ipcomp
Set up an IP Compression Association (IPCA) which will use the IPComp
transforms.
Just like an SA, an IPCA consists of the destination
address, a Compression Parameter Index (CPI) and a protocol (which is
fixed to IPComp).
Compression algorithms are applied.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl cpi ,
.Fl comp ,
and
.Fl forcetunnel .
To create an IPsec SA using compression, an IPCA and an SA must first
be created.
After this, an IPCA/SA bundle must be created using the
.Cm group
command.
The IPCA must be applied first.
.It Cm tcpmd5
Set up a key for use by the RFC 2385 TCP MD5 option.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl spi ,
.Fl key ,
and
.Fl keyfile .
.El
.Pp
If no command is given,
.Nm
defaults to new ESP mode.
.Pp
The modifiers have the following meanings:
.Bl -tag -width 7n
.It Fl src Ar address
The source IP address for the SA.
This is necessary for incoming
SAs to avoid source address spoofing between mutually
suspicious hosts that have established SAs with us.
For outgoing SAs,
this field is used to fill in the source address when doing tunneling.
.It Fl dst Ar address
The destination IP address for the SA.
.It Fl dst2 Ar address
The second IP address used by
.Cm group .
.It Fl proxy Ar address
This IP address, if provided, is checked against the inner IP address when
doing tunneling to a firewall, to prevent source spoofing attacks.
It is
strongly recommended that this option is provided when applicable.
It is
applicable in a scenario when host A is using IPsec to communicate with
firewall B, and through that to host C.
In that case, the proxy address for
the incoming SA should be C.
This option is not necessary for outgoing SAs.
.It Fl spi Ar index
The Security Parameter Index (SPI), given as a hexadecimal number.
.It Fl spi2 Ar index
The second SPI used by
.Cm group .
.It Fl cpi Ar index
The Compression Parameter Index (CPI), given as a 16-bit hexadecimal number.
.It Fl tunnel
.Sy This modifier has been deprecated.
The arguments are ignored, and it otherwise has the same effect as the
.Fl forcetunnel
option.
.It Fl newpadding
.Sy This modifier has been deprecated.
.It Fl forcetunnel
Force IP-inside-IP encapsulation before ESP or AH processing is performed for
outgoing packets.
The source/destination addresses of the outgoing IP packet
will be those provided in the
.Fl src
and
.Fl dst
options.
Notice that the IPsec stack will perform IP-inside-IP encapsulation
when deemed necessary, even if this flag has not been set.
.It Fl udpencap Ar port
Enable ESP-inside-UDP encapsulation.
The UDP destination port must be specified on the command line.
This port will be used for sending encapsulated UDP packets.
.It Fl enc Ar algorithm
The encryption algorithm to be used with the SA.
Possible values are:
.Bl -tag -width skipjack
.It Cm des
This is available for both old and new ESP.
Notice that hardware crackers for DES can be (and have been) built for
US$250,000 (in 1998).
Use DES for encryption of critical information at your own risk.
Use of 3DES or AES is recommended instead.
DES support is kept for interoperability
(with old implementations) purposes only.
See
.Xr des_cipher 3 .
.It Cm 3des
This is available for both old and new ESP.
It is considered more secure than straight DES, since it uses larger
keys.
.It Cm aes
Rijndael encryption is available only in new ESP.
.It Cm blf
Blowfish encryption is available only in new ESP.
See
.Xr blf_key 3 .
.It Cm cast
CAST encryption is available only in new ESP.
.It Cm skipjack
SKIPJACK encryption is available only in new ESP.
This algorithm was designed by the NSA and is faster than 3DES.
However, since it was designed by the NSA,
it is a poor choice.
.El
.Pp
.It Fl auth Ar algorithm
The authentication algorithm to be used with the SA.
Possible values are:
.Cm md5
and
.Cm sha1
for both old and new AH and also new ESP.
.Cm rmd160 ,
.Cm sha2-256 ,
.Cm sha2-384 ,
and
.Cm sha2-512
are also available
for both new AH and ESP.
.It Fl comp Ar algorithm
The compression algorithm to be used with the IPCA.
Possible values are:
.Cm deflate
and
.Cm lzs .
Note that
.Cm lzs
is only available with
.Xr hifn 4
because of the patent held by Hifn, Inc.
.It Fl key Ar key
The secret symmetric key used for encryption and authentication.
The sizes for
.Cm des
and
.Cm 3des
are fixed to 8 and 24 bits, respectively.
For other ciphers like
.Cm cast ,
.Cm aes ,
or
.Cm blf ,
the key length can vary, depending on the algorithm.
The
.Ar key
should be given in hexadecimal digits.
The
.Ar key
should be chosen at random (ideally, using some true-random source like
coin flipping).
It is very important that the key is not guessable.
One practical way of generating 160-bit (20-byte) keys is as follows:
.Bd -literal -offset indent
$ openssl rand 20 | hexdump -e '20/1 "%02x"'
.Ed
.It Fl keyfile Ar file
Read the key from a file.
May be used instead of the
.Fl key
flag, and has the same syntax considerations.
.It Fl authkey Ar key
The secret key material used for authentication
if additional authentication in new ESP mode is required.
For old or new AH, the key material for authentication is passed with the
.Fl key
option.
The
.Ar key
should be given in hexadecimal digits.
The
.Ar key
should be chosen at random (ideally, using some true-random source like
coin flipping).
It is very important that the key is not guessable.
One practical way of generating 160-bit (20-byte) keys is as follows:
.Bd -literal -offset indent
$ openssl rand 20 | hexdump -e '20/1 "%02x"'
.Ed
.It Fl authkeyfile Ar file
Read the additional authentication key from a file.
May be used instead of the
.Fl authkey
flag, and has the same syntax considerations.
.It Fl iv
.Sy This modifier has been deprecated.
The argument is ignored.
When applicable, it has the same behaviour as the
.Fl halfiv
option.
.It Fl halfiv
This option causes use of a 4-byte initialization vector (IV) in old ESP
(as opposed to 8 bytes).
It may only be used with old ESP.
.It Fl proto Ar protocol
The security protocol needed by
.Cm delspi
or
.Cm flow ,
to uniquely specify the SA.
The default value is 50 which means
.Dv IPPROTO_ESP .
Other accepted values are 51
.Dv ( IPPROTO_AH )
and 4
.Dv ( IPPROTO_IP ) .
One can also specify the symbolic names
.Dq esp ,
.Dq ah ,
and
.Dq ip4 ,
case insensitive.
.It Fl proto2 Ar protocol
The second security protocol used by
.Cm group .
It defaults to
.Dv IPPROTO_AH ,
otherwise takes the same values as
.Fl proto .
.It Fl addr Ar srcnet mask dstnet mask
.It Xo
.Fl addr
.Ar srcnet Ns / Ns Ar prefixlen
.Ar dstnet Ns / Ns Ar prefixlen
.Xc
The first form is the source address, source network mask, destination
address, and destination network mask.
The second form is the source and destination addresses and netmasks
in CIDR notation.
Either form can be specified against which packets need to match
in order to use the specified Security Association.
All addresses must be of the same address family
(IPv4 or IPv6).
.It Fl transport Ar protocol
The protocol number which packets need to match to use the specified
Security Association.
By default, the protocol number is not used for matching.
Instead of a number, a valid protocol name that appears in
.Xr protocols 5
can be used.
.It Fl sport Ar port
The source port which packets have to match for the flow.
By default, the source port is not used for matching.
Instead of a number, a valid service name that appears in
.Xr services 5
can be used.
.It Fl dport Ar port
The destination port which packets have to match for the flow.
By default, the destination port is not used for matching.
Instead of a number, a valid service name that appears in
.Xr services 5
can be used.
.It Fl srcid Ar id
For
.Cm flow ,
used to specify what local identity key management
should use when negotiating the SAs.
If left unspecified, the source address of the flow is used
(see the discussion on
.Cm flow
above, with regard to source address).
.It Fl dstid Ar id
For
.Cm flow ,
used to specify what the remote identity key management
should expect.
If left unspecified, the destination address of the flow is used
(see the discussion on
.Cm flow
above, with regard to destination address).
.It Fl srcid_type Ar type
For
.Cm flow ,
used to specify the type of identity given by
.Fl srcid .
Valid values are
.Cm prefix ,
.Cm fqdn ,
and
.Cm ufqdn .
.Pp
The
.Cm prefix
type implies an IPv4 or IPv6 address followed by a forward slash
character and a decimal number indicating the number of important bits
in the address (equivalent to a netmask, in IPv4 terms).
Key management then has to pick a local identity that falls within the
address space indicated.
.Pp
The
.Cm fqdn
and
.Cm ufqdn
types are DNS-style host names and mailbox-format user
addresses, respectively, and are especially useful for mobile user
scenarios.
Note that no validity checking on the identities is done.
.It Fl dstid_type Ar type
See
.Fl srcid_type .
.It Fl delete
Instead of creating a flow, an existing flow is deleted.
.It Fl bypass
For
.Cm flow ,
create or delete a
.Em bypass
flow.
Packets matching this flow will not be processed by IPsec.
.It Fl permit
Same as
.Fl bypass .
.It Fl deny
For
.Cm flow ,
create or delete a
.Em deny
flow.
Packets matching this flow will be dropped.
.It Fl use
For
.Cm flow ,
specify that packets matching this flow should try to use IPsec if
possible.
.It Fl acquire
For
.Cm flow ,
specify that packets matching this flow should try to use IPsec and
establish SAs dynamically if possible, but permit unencrypted
traffic.
.It Fl require
For
.Cm flow ,
specify that packets matching this flow must use IPsec, and establish
SAs dynamically as needed.
If no SAs are established, traffic is not allowed through.
.It Fl dontacq
For
.Cm flow ,
specify that packets matching this flow must use IPsec.
If such SAs are not present, simply drop the packets.
Such a policy may be used to demand peers establish SAs before they
can communicate, without going through the burden of
initiating the SA ourselves (thus allowing for some denial of service
attacks).
This flow type is particularly suitable for security gateways.
.It Fl in
For
.Cm flow ,
specify that it should be used to match incoming packets only.
.It Fl out
For
.Cm flow ,
specify that it should be used to match outgoing packets only.
.It Fl ah
For
.Cm flush ,
only flush SAs of type AH.
.It Fl esp
For
.Cm flush ,
only flush SAs of type ESP.
.It Fl oldah
For
.Cm flush ,
only flush SAs of type old AH.
.It Fl oldesp
For
.Cm flush ,
only flush SAs of type old ESP.
.It Fl ip4
For
.Cm flush ,
only flush SAs of type IPv4.
.It Fl ipcomp
For
.Cm flush ,
only flush SAs of type IPComp.
.It Fl tcpmd5
For
.Cm flush ,
only flush SAs using the TCP MD5 option.
.El
.Sh EXAMPLES
Set up an SA which uses new ESP with 3DES encryption and HMAC-SHA1
authentication:
.Bd -literal -offset 3n
# ipsecadm new esp -enc 3des -auth sha1 -spi 100a \e
	-dst 169.20.12.2 -src 169.20.12.3 \e
	-key 638063806380638063806380638063806380638063806380 \e
	-authkey 1234123412341234123412341234123412341234
.Ed
.Pp
Set up an SA for authentication with old AH only:
.Bd -literal -offset 3n
# ipsecadm old ah -auth md5 -spi 10f2 \e
	-dst 169.20.12.2 -src 169.20.12.3 \e
	-key 12341234deadbeef
.Ed
.Pp
Set up a flow requiring use of AH:
.Bd -literal -offset 3n
# ipsecadm flow -dst 169.20.12.2 -proto ah \e
	-addr 10.1.1.0/24 10.0.0.0/24 -out -require
.Ed
.Pp
Set up an inbound SA:
.Bd -literal -offset 3n
# ipsecadm new esp -enc blf -auth md5 -spi 1002 \e
	-dst 169.20.12.3 -src 169.20.12.2 \e
	-key abadbeef15deadbeefabadbeef15deadbeefabadbeef15deadbeef \e
	-authkey 12349876432167890192837465098273
.Ed
.Pp
Set up an ingress flow for the inbound SA:
.Bd -literal -offset 3n
# ipsecadm flow -addr 10.0.0.0/8 10.1.1.0/24 \e
	-dst 169.20.12.2 -proto esp -in -require
.Ed
.Pp
Set up a bypass flow:
.Bd -literal -offset 3n
# ipsecadm flow -bypass -out -addr 10.1.1.0/24 10.1.1.0/24
.Ed
.Pp
Set up a key for the TCP MD5 option:
.Bd -literal -offset 3n
# ipsecadm tcpmd5 -src ::1 -dst ::1 -spi 0100 -key deadbeef
.Ed
.Pp
Delete all ESP SAs and their flows and routing information:
.Bd -literal -offset 3n
# ipsecadm flush -esp
.Ed
.Sh SEE ALSO
.Xr netstat 1 ,
.Xr enc 4 ,
.Xr ipsec 4 ,
.Xr protocols 5 ,
.Xr services 5 ,
.Xr sysctl.conf 5 ,
.Xr isakmpd 8 ,
.Xr vpn 8