IPSECADM(8) OpenBSD System Manager's Manual IPSECADM(8)
NAME
ipsecadm - interface to set up IPsec
SYNOPSIS
ipsecadm command [modifier ...]
NOTE
To use ipsecadm, ipsec(4) must be enabled by having one or more of the
following sysctl(3) variables set:
net.inet.esp.enable Enable the ESP IPsec protocol
net.inet.ah.enable Enable the AH IPsec protocol
net.inet.ipcomp.enable Enable the IPComp protocol
Both the ESP and AH protocols are enabled by default. To keep local mod-
ifications of these variables across reboots, see sysctl.conf(5).
DESCRIPTION
The ipsecadm utility sets up security associations in the kernel to be
used with ipsec(4). It can be used to specify the encryption and authen-
tication algorithms and key material for the network layer security pro-
vided by IPsec. The possible commands are:
new esp Set up a Security Association (SA) which uses the new ESP trans-
forms (RFC 2406). An SA consists of the destination address, a
Security Parameter Index (SPI) and a security protocol. Encryp-
tion and authentication algorithms can be applied. This is the
default mode. Allowed modifiers are: -dst, -src, -proxy, -spi,
-enc, -srcid_type, -srcid, -dstid_type, -dstid, -auth, -authkey,
-authkeyfile, -forcetunnel, -udpencap, -key, and -keyfile.
old esp Set up an SA which uses the old ESP transforms (RFC 1827). Only
encryption algorithms can be applied. Allowed modifiers are:
-dst, -src, -proxy, -spi, -enc, -srcid_type, -srcid,
-dstid_type, -dstid, -halfiv, -forcetunnel, -key, and -keyfile.
new ah Set up an SA which uses the new AH transforms (RFC 2402). Au-
thentication will be done with Hashed Message Authentication
Code (HMAC) using the specified hash algorithm. Allowed modi-
fiers are: -dst, -src, -proxy, -spi, -srcid_type, -srcid,
-dstid_type, -dstid, -forcetunnel, -auth, -key, and -keyfile.
old ah Set up an SA which uses the old AH transforms (RFC 1826). Sim-
ple keyed hashes will be used for authentication. Allowed modi-
fiers are: -dst, -src, -proxy, -spi, -srcid_type, -srcid,
-dstid_type, -dstid, -forcetunnel, -auth, -key, and -keyfile.
group Group two SAs together, such that whenever the first one is ap-
plied, the second one will be applied as well (SA bundle). Ar-
bitrarily 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: -dst, -spi, -proto, -dst2, -spi2, and -proto2.
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 ref-
erencing the information and does not appear on the wire. Un-
like other setups, like new ESP, there is no necessary setup in
the receiving side. Allowed modifiers are: -dst, -src, and
-spi.
delspi Delete the specified SA. Allowed modifiers are: -dst, -spi, and
-proto.
flow Create a flow determining what security parameters a packet
should have (input or output). Allowed modifiers are: -src,
-dst, -proto, -addr, -transport, -sport, -dport, -delete, -in,
-out, -srcid, -dstid, -srcid_type, -dstid_type, -acquire,
-require, -dontacq, -use, -bypass, -permit and -deny.
The netstat(1) command shows all specified flows.
Flows are directional, and the -in and -out modifiers are used
to specify the direction. By default, flows are assumed to ap-
ply to outgoing packets. The kernel will attempt to find an ap-
propriate 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 ad-
dress (if specified) should point to the expected source of the
SA (the remote SA peer).
If no such SA exists, key management daemons will be used to
generate them if -acquire or -require were used. If -acquire
was used, traffic will be allowed out (or in) and IPsec will be
used when the relevant SAs have been established. If -require
was used, traffic will not be allowed in or out until it is pro-
tected by IPsec. If -dontacq was used, traffic will not be al-
lowed in or out until it is protected by IPsec, but key manage-
ment will not be asked to provide such an SA. The -proto argu-
ment (by default set to esp) can be used to determine what type
of SA should be established.
A bypass or permit flow (created with -bypass or -permit) is
used to specify a flow for which IPsec processing will be by-
passed, i.e., packets will/need not be processed by any SAs.
For bypass or permit flows, additional modifiers are restricted
to: -addr, -transport, -sport, -dport, -in, -out, and -delete.
A deny flow is used to specify classes of packets that must be
dropped (either on output or input) without further processing.
-deny takes the same additional modifiers as -bypass.
flush Flush SAs from kernel. This includes flushing any flows and
routing entries associated with the SAs. Allowed modifiers are:
-ah, -esp, -oldah, -oldesp, -ip4, -ipcomp, and -tcpmd5. Default
action is to flush all types of security associations from the
kernel.
show Show SAs from kernel. Allowed modifiers are: -ah, -esp, -oldah,
-oldesp, -ip4, -ipcomp, and -tcpmd5. Default action is to show
all types of security associations from the kernel.
monitor Continuously display all PF_KEY messages exchanged with the ker-
nel.
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: -dst, -src, -cpi, -comp, and
-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 group command. The IPCA must be ap-
plied first. See ipcomp(4) for further information on the IP-
Comp protocol.
tcpmd5 Set up a key for use by the RFC 2385 TCP MD5 option. Allowed
modifiers are: -dst, -src, -spi, -key, and -keyfile.
If no command is given, ipsecadm defaults to new ESP mode.
The modifiers have the following meanings:
-src address
The source IP address for the SA. This is necessary for incom-
ing SAs to avoid source address spoofing between mutually suspi-
cious hosts that have established SAs with us. For outgoing
SAs, this field is used to fill in the source address when doing
tunneling.
-dst address
The destination IP address for the SA.
-dst2 address
The second IP address used by group.
-proxy 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 out-
going SAs.
-spi index
The Security Parameter Index (SPI), given as a hexadecimal num-
ber.
-spi2 index
The second SPI used by group.
-cpi index
The Compression Parameter Index (CPI), given as a 16-bit hex-
adecimal number.
-tunnel This modifier has been deprecated. The arguments are ignored,
and it otherwise has the same effect as the -forcetunnel option.
-newpadding
This modifier has been deprecated.
-forcetunnel
Force IP-inside-IP encapsulation before ESP or AH processing is
performed for outgoing packets. The source/destination address-
es of the outgoing IP packet will be those provided in the -src
and -dst options. Notice that the IPsec stack will perform IP-
inside-IP encapsulation when deemed necessary, even if this flag
has not been set.
-udpencap 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.
-enc algorithm
The encryption algorithm to be used with the SA. Possible val-
ues are:
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 encryp-
tion 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 des_cipher(3).
3des This is available for both old and new ESP. It is
considered more secure than straight DES, since it us-
es larger keys.
aes AES/Rijndael CBC encryption is available only in new
ESP.
aesctr AES/Rijndael CTR (RFC 3686) encryption is available
only in new ESP.
blf Blowfish encryption is available only in new ESP. See
blf_key(3).
cast CAST encryption is available only in new ESP.
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.
null The NULL encryption algorithm is available for new
ESP. It should be used in combination with an authen-
tication algorithm to provide authentication and in-
tegrity without confidentiality.
-auth algorithm
The authentication algorithm to be used with the SA. Possible
values are: md5 and sha1 for both old and new AH and also new
ESP. rmd160, sha2-256, sha2-384, and sha2-512 are also avail-
able for both new AH and ESP.
-comp algorithm
The compression algorithm to be used with the IPCA. Possible
values are: deflate and lzs. Note that lzs is only available
with hifn(4) because of the patent held by Hifn, Inc.
-key key
The secret symmetric key used for encryption and authentication.
The sizes for des and 3des are fixed to 8 and 24 bytes, respec-
tively. For other ciphers like cast, aes, or blf, the key
length can vary, depending on the algorithm. The key should be
given in hexadecimal digits. The 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:
$ openssl rand 20 | hexdump -e '20/1 "%02x"'
-keyfile file
Read the key from a file. May be used instead of the -key flag,
and has the same syntax considerations.
-authkey 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 -key op-
tion. The key should be given in hexadecimal digits. The 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:
$ openssl rand 20 | hexdump -e '20/1 "%02x"'
-authkeyfile file
Read the additional authentication key from a file. May be used
instead of the -authkey flag, and has the same syntax considera-
tions.
-iv This modifier has been deprecated. The argument is ignored.
When applicable, it has the same behaviour as the -halfiv op-
tion.
-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.
-proto protocol
The security protocol needed by delspi or flow, to uniquely
specify the SA. The default value is 50 which means
IPPROTO_ESP. Other accepted values are 51 (IPPROTO_AH) and 4
(IPPROTO_IP). One can also specify the symbolic names ``esp'',
``ah'', and ``ip4'', case insensitive.
-proto2 protocol
The second security protocol used by group. It defaults to
IPPROTO_AH, otherwise takes the same values as -proto.
-addr srcnet mask dstnet mask
-addr srcnet/prefixlen dstnet/prefixlen
The first form is the source address, source network mask, des-
tination address, and destination network mask. The second form
is the source and destination addresses and netmasks in CIDR no-
tation. 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).
-transport protocol
The protocol number which packets need to match to use the spec-
ified Security Association. By default, the protocol number is
not used for matching. Instead of a number, a valid protocol
name that appears in protocols(5) can be used.
-sport 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 services(5) can be
used.
-dport port
The destination port which packets have to match for the flow.
By default, the destination port is not used for matching. In-
stead of a number, a valid service name that appears in
services(5) can be used.
-srcid id
For 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 flow
above, with regard to source address).
-dstid id
For flow, used to specify what the remote identity key manage-
ment should expect. If left unspecified, the destination ad-
dress of the flow is used (see the discussion on flow above,
with regard to destination address).
-srcid_type type
For flow, used to specify the type of identity given by -srcid.
Valid values are prefix, fqdn, and ufqdn.
The prefix type implies an IPv4 or IPv6 address followed by a
forward slash character and a decimal number indicating the num-
ber of important bits in the address (equivalent to a netmask,
in IPv4 terms). Key management then has to pick a local identi-
ty that falls within the address space indicated.
The fqdn and 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.
-dstid_type type
See -srcid_type.
-delete Instead of creating a flow, an existing flow is deleted.
-bypass For flow, create or delete a bypass flow. Packets matching this
flow will not be processed by IPsec.
-permit Same as -bypass.
-deny For flow, create or delete a deny flow. Packets matching this
flow will be dropped.
-use For flow, specify that packets matching this flow should try to
use IPsec if possible.
-acquire
For flow, specify that packets matching this flow should try to
use IPsec and establish SAs dynamically if possible, but permit
unencrypted traffic.
-require
For 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.
-dontacq
For 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 initi-
ating the SA ourselves (thus allowing for some denial of service
attacks). This flow type is particularly suitable for security
gateways.
-in For flow, specify that it should be used to match incoming pack-
ets only.
-out For flow, specify that it should be used to match outgoing pack-
ets only.
-ah For flush, only flush SAs of type AH.
-esp For flush, only flush SAs of type ESP.
-oldah For flush, only flush SAs of type old AH.
-oldesp For flush, only flush SAs of type old ESP.
-ip4 For flush, only flush SAs of type IPv4.
-ipcomp For flush, only flush SAs of type IPComp.
-tcpmd5 For flush, only flush SAs using the TCP MD5 option.
EXAMPLES
Set up an SA which uses new ESP with 3DES encryption and HMAC-SHA1 au-
thentication:
# ipsecadm new esp -enc 3des -auth sha1 -spi 100a \
-dst 169.20.12.2 -src 169.20.12.3 \
-key 638063806380638063806380638063806380638063806380 \
-authkey 1234123412341234123412341234123412341234
Set up an SA for authentication with old AH only:
# ipsecadm old ah -auth md5 -spi 10f2 \
-dst 169.20.12.2 -src 169.20.12.3 \
-key 12341234deadbeef
Set up a flow requiring use of AH:
# ipsecadm flow -dst 169.20.12.2 -proto ah \
-addr 10.1.1.0/24 10.0.0.0/24 -out -require
Set up an inbound SA:
# ipsecadm new esp -enc blf -auth md5 -spi 1002 \
-dst 169.20.12.3 -src 169.20.12.2 \
-key abadbeef15deadbeefabadbeef15deadbeefabadbeef15deadbeef \
-authkey 12349876432167890192837465098273
Set up an ingress flow for the inbound SA:
# ipsecadm flow -addr 10.0.0.0/8 10.1.1.0/24 \
-dst 169.20.12.2 -proto esp -in -require
Set up a bypass flow:
# ipsecadm flow -bypass -out -addr 10.1.1.0/24 10.1.1.0/24
Set up a key for the TCP MD5 option:
# ipsecadm tcpmd5 -src ::1 -dst ::1 -spi 0100 -key deadbeef
Delete all ESP SAs and their flows and routing information:
# ipsecadm flush -esp
SEE ALSO
netstat(1), enc(4), ipcomp(4), ipsec(4), protocols(5), services(5),
sysctl.conf(5), isakmpd(8), vpn(8)
OpenBSD 3.9 August 26, 1997 7