ipsecadm - interface to set up IPsec
ipsecadm [command] modifiers ...
To use ipsecadm, IPsec 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 modifications
of these variables across reboots, see
sysctl.conf(5).
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 authentication
algorithms and key material for the network layer
security provided
by IPsec. The possible commands are:
new esp Set up a Security Association (SA) which uses the
new esp transforms.
A 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: -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.
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. Authentication
will be done with HMAC using the specified hash algorithm. Allowed
modifiers 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.
Simple keyed
hashes will be used for authentication. Allowed
modifiers 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 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: -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 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: -dst,
-src, and
-spi.
delspi The specified SA will be deleted. 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 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). 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 protected by IPsec. If -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 -proto
argument (by default set to esp) will be used to
determine what
type of SA should be established. A bypass or
permit flow 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:
-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 kernel.
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 keyword. The IPCA
must be applied
first.
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 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.
-dst The destination IP address for the SA.
-dst2
The second IP address used by group.
-proxy
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.
-spi The Security Parameter Index (SPI), given as a
hexadecimal
number.
-spi2
The second SPI used by group.
-cpi The Compression Parameter Index (CPI), given as
a 16 bit hexadecimal
number.
-tunnel
This option has been deprecated. The arguments
are ignored,
and it otherwise has the same effect as the
forcetunnel option.
-newpadding
This option has been deprecated.
-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 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
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 The encryption algorithm to be used with the SA.
Possible
values 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
encryption of critical information at
your own
risk. We suggest using 3DES or AES
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
uses larger keys.
aes Rijndael 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.
-auth
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. Also rmd160, sha2-256, sha2-384,
sha2-512 for both
new ah and esp.
-comp
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 The secret symmetric key used for encryption and
authentication.
The size for des and 3des is fixed to 8
and 24 respectively.
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
Read the key from a file. May be used instead
of the -key
flag, and has the same syntax considerations.
-authkey
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
option. 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
Read the authkey from a file. May be used instead of the
-authkey flag, and has the same syntax considerations.
-iv This option has been deprecated. The argument
is ignored.
When applicable, it has the same behaviour as
the halfiv option.
-halfiv
This option causes use of a 4 byte IV in old ESP
(as opposed
to 8 bytes). It may only be used with old ESP.
-proto
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
The second security protocol used by group. It
defaults to
IPPROTO_AH, otherwise takes the same values as
-proto.
-addr
The source address, source network mask, destination address
and destination network mask against which packets need to
match to use the specified Security Association.
Alternatively,
addresses and masks can be specified as
``source/prefixlen destination/prefixlen''. All
addresses
must be of the same address family (IPv4 or
IPv6).
-transport
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 protocols(5) can
be used.
-sport
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
The destination 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.
-srcid
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
For flow, used to specify what the remote identity key management
should expect is. If left unspecified,
the destination
address of the flow is used (see the discussion on flow
above, with regard to destination address).
-srcid_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
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.
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
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 with us, 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.
-in For flow, specify that it should be used to
match incoming
packets only.
-out For flow, specify that it should be used to
match outgoing
packets 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 ip4.
Set up an SA which uses new esp with 3des encryption and
HMAC-SHA1 authentication:
# 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
netstat(1), enc(4), ipsec(4), protocols(5), services(5),
sysctl.conf(5),
isakmpd(8), vpn(8)
OpenBSD 3.6 August 26, 1997
[ Back ] |
