IPSEC.CONF(5) | File Formats Manual | IPSEC.CONF(5) |
ipsec.conf
— IPsec
configuration file
The ipsec.conf
file specifies rules and
definitions for IPsec, which provides security services for IP datagrams.
IPsec itself is a pair of protocols: Encapsulating Security Payload (ESP),
which provides integrity and confidentiality; and Authentication Header
(AH), which provides integrity. The IPsec protocol itself is described in
ipsec(4).
In its most basic form, a flow is established between hosts and/or networks, and then Security Associations (SAs) are established, which detail how the desired protection will be achieved. IPsec uses flows to determine whether to apply security services to an IP packet or not.
Generally speaking an automated keying daemon, such as
isakmpd(8), is used to set
up flows and establish SAs, by specifying an ‘ike’ line in
ipsec.conf
(see
AUTOMATIC KEYING, below). An
authentication method, such as public key authentication, will also have to
be set up: see the PKI section of
isakmpd(8) for information
on the types of authentication available, and the procedures for setting
them up.
The keying daemon,
isakmpd(8), can be enabled
to run at boot time via “rcctl enable isakmpd”. Note that to
avoid keynote(4) policy
checking, it will probably need to be run with at least the
-K
option via the “rcctl set isakmpd flags
-K” command which sets
isakmpd_flags="-K"
in
rc.conf.local(8). The
ipsec.conf
configuration itself is loaded at boot
time if IPsec is enabled by using “rcctl enable ipsec”, which
sets
ipsec=YES
in
rc.conf.local(8). A
utility called ipsecctl(8)
is also available to load ipsec.conf
configurations,
and can additionally be used to view and modify IPsec flows.
An alternative method of setting up SAs is also possible using manual keying. Manual keying is not recommended, but can be convenient for quick setups and testing. Those procedures are documented within this page.
The current line can be extended over multiple lines using a backslash (‘\’). Comments can be put anywhere in the file using a hash mark (‘#’), and extend to the end of the current line. Care should be taken when commenting out multi-line text: the comment is effective until the end of the entire block.
Argument names not beginning with a letter, digit, or underscore must be quoted.
Addresses can be specified in CIDR notation (matching netblocks), as symbolic host names, interface names, or interface group names.
Certain parameters can be expressed as lists, in which case ipsecctl(8) generates all the necessary combinations. For example:
ike esp from {192.168.1.1, 192.168.1.2} to \ {10.0.0.17, 10.0.0.18} peer 192.168.10.1
Will expand to:
ike esp from 192.168.1.1 to 10.0.0.17 peer 192.168.10.1 ike esp from 192.168.1.1 to 10.0.0.18 peer 192.168.10.1 ike esp from 192.168.1.2 to 10.0.0.17 peer 192.168.10.1 ike esp from 192.168.1.2 to 10.0.0.18 peer 192.168.10.1
Macros can be defined that will later be expanded in context.
Macro names must start with a letter, digit, or underscore, and may contain
any of those characters. Macro names may not be reserved words (for example
flow
, from
,
esp
). Macros are not expanded inside quotes.
For example:
remote_gw = "192.168.3.12" flow esp from 192.168.7.0/24 to 192.168.8.0/24 peer $remote_gw
Additional configuration files can be included with the
include
keyword, for example:
include "/etc/macros.conf"
In this scenario, ipsec.conf
is used to
set up flows and SAs automatically using
isakmpd(8) with the
ISAKMP/Oakley a.k.a. IKEv1 protocol. To configure automatic keying using the
IKEv2 protocol, see
iked.conf(5) instead. Some
examples of setting up automatic keying:
# Set up a VPN: # First between the gateway machines 192.168.3.1 and 192.168.3.2 # Second between the networks 10.1.1.0/24 and 10.1.2.0/24 ike esp from 192.168.3.1 to 192.168.3.2 ike esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2
The commands are as follows:
ike
[mode] [encap]
[tmode]srcid
parameter. dynamic mode should be used for hosts
with dynamic IP addresses like road warriors or dialup hosts. If omitted,
active mode will be used.
encap specifies the encapsulation protocol to be used. Possible protocols are esp and ah; the default is esp.
tmode describes the encapsulation mode to be used. Possible modes are tunnel and transport; the default is tunnel.
proto
protocolproto
parameter restricts the flow to
a specific IP protocol. Common protocols are
icmp(4),
tcp(4), and
udp(4). For a list of all the
protocol name to number mappings used by
ipsecctl(8), see the file
/etc/protocols.from
src [port
sport] [(srcnat)]
to
dst
[port
dport]The optional port
modifiers restrict
the flows to the specified ports. They are only valid in conjunction
with the tcp(4) and
udp(4) protocols. Ports can
be specified by number or by name. For a list of all port name to number
mappings used by
ipsecctl(8), see the
file /etc/services.
local
localip peer
remotelocal
parameter specifies the address or FQDN
of the local endpoint. Unless we are multi-homed or have aliases, this
parameter is generally not needed. This parameter does not affect the set
of IP addresses isakmpd(8)
will listen on and send packets from. The
Listen-on
directive in
isakmpd.conf(5)
should additionally be used to ensure that the local endpoint will send
IKE messages with an appropriate source IP address.
The peer
parameter specifies the
address or FQDN of the remote endpoint. For host-to-host connections
where dst is identical to
remote, this option is generally not needed as it
will be set to dst automatically. If it is not
specified or if the keyword any is given, the
default peer is used.
auth
algorithm enc
algorithm group
group lifetime
timeThe mode can be either main, which
specifies main mode, or aggressive, which
specifies aggressive mode. Possible values for
auth
, enc
, and
group
are described below in
CRYPTO TRANSFORMS.
The lifetime
parameter specifies the
phase 1 lifetime in seconds. Two unit specifiers are recognized
(ignoring case): ‘m
’ and
‘h
’ for minutes and hours,
respectively.
If omitted, ipsecctl(8) will use the default values main, hmac-sha1, aes, modp3072, and 3600.
quick
auth
algorithm enc
algorithm group
group lifetime
timePossible values for auth
,
enc
, and group
are
described below in CRYPTO
TRANSFORMS. Perfect Forward Secrecy (PFS) is enabled unless
group
none is
specified.
The lifetime
parameter specifies the
phase 2 lifetime in seconds. Two unit specifiers are recognized
(ignoring case): ‘m
’ and
‘h
’ for minutes and hours,
respectively.
If omitted, ipsecctl(8) will use the default values hmac-sha2-256 and aes; PFS will only be used if the remote side requests it. The default phase 2 lifetime value is 1200.
srcid
string dstid
stringsrcid
defines an ID of type “USER_FQDN” or “FQDN”
that will be used by
isakmpd(8) as the identity
of the local peer. If the argument is an email address (bob@example.com),
ipsecctl(8) will use
USER_FQDN as the ID type. Anything else is considered to be an FQDN. If
srcid
is omitted, the default is to use the IP
address of the connecting machine.
dstid
is similar to
srcid
, but instead specifies the ID to be used
by the remote peer.
psk
stringtag
stringtagged
keyword.
The following variables can be used in tags to include information from the remote peer on runtime:
For example, if the ID is fqdn/foo.bar.org or ufqdn/user@bar.org, “ipsec-$domain” expands to “ipsec-bar.org”. The variable expansion for the tag directive occurs only at runtime (not when the file is parsed) and must be quoted, or it will be interpreted as a macro.
IPsec traffic appears unencrypted on the enc(4) interface and can be filtered accordingly using the OpenBSD packet filter, pf(4). The grammar for the packet filter is described in pf.conf(5).
The following components are relevant to filtering IPsec traffic:
tag
keyword.If the filtering rules specify to block everything by default, the following rule would ensure that IPsec traffic never hits the packet filtering engine, and is therefore passed:
set skip on enc0
In the following example, all traffic is blocked by default. IPsec-related traffic from gateways {192.168.3.1, 192.168.3.2} and networks {10.0.1.0/24, 10.0.2.0/24} is permitted.
block on sk0 block on enc0 pass in on sk0 proto udp from 192.168.3.2 to 192.168.3.1 \ port {500, 4500} pass out on sk0 proto udp from 192.168.3.1 to 192.168.3.2 \ port {500, 4500} pass in on sk0 proto esp from 192.168.3.2 to 192.168.3.1 pass out on sk0 proto esp from 192.168.3.1 to 192.168.3.2 pass in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1 \ keep state (if-bound) pass out on enc0 proto ipencap from 192.168.3.1 to 192.168.3.2 \ keep state (if-bound) pass in on enc0 from 10.0.2.0/24 to 10.0.1.0/24 \ keep state (if-bound) pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24 \ keep state (if-bound)
pf(4) has the ability to filter IPsec-related packets based on an arbitrary tag specified within a ruleset. The tag is used as an internal marker which can be used to identify the packets later on. This could be helpful, for example, in scenarios where users are connecting in from differing IP addresses, or to support queue-based bandwidth control, since the enc0 interface does not support it.
The following pf.conf(5) fragment uses queues for all IPsec traffic with special handling for developers and employees:
queue std on sk0 bandwidth 100M queue deflt parent std bandwidth 10M default queue developers parent std bandwidth 75M queue employees parent std bandwidth 5M queue ipsec parent std bandwidth 10M pass out on sk0 proto esp set queue ipsec pass out on sk0 tagged ipsec-developers.bar.org set queue developers pass out on sk0 tagged ipsec-employees.bar.org set queue employees
The tags will be assigned by the following
ipsec.conf
example:
ike esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 \ tag "ipsec-$domain"
In some network topologies it is desirable to perform NAT on traffic leaving through the VPN tunnel. In order to achieve that, the src argument is used to negotiate the desired network ID with the peer and the srcnat parameter defines the true local subnet, so that a correct SA can be installed on the local side.
For example, if the local subnet is 192.168.1.0/24 and all the traffic for a specific VPN peer should appear as coming from 10.10.10.1, the following configuration is used:
ike esp from 10.10.10.1 (192.168.1.0/24) to 192.168.2.0/24 \ peer 10.10.20.1
Naturally, a relevant NAT rule is required in pf.conf(5). For the example above, this would be:
match out on enc0 from 192.168.1.0/24 to 192.168.2.0/24 \ nat-to 10.10.10.1
From the peer's point of view, the local end of the VPN tunnel is declared to be 10.10.10.1 and all the traffic arrives with that source address.
It is very important that keys are not guessable. One practical way of generating keys is to use openssl(1). The following generates a 160-bit (20-byte) key:
$ openssl rand -hex 20
The following authentication types are permitted with the
auth
keyword:
Authentication | Key Length | |
hmac-md5 |
128 bits | |
hmac-ripemd160 |
160 bits | [phase 2 only] |
hmac-sha1 |
160 bits | |
hmac-sha2-256 |
256 bits | |
hmac-sha2-384 |
384 bits | |
hmac-sha2-512 |
512 bits |
The following cipher types are permitted with the
enc
keyword:
Cipher | Key Length | |
3des |
168 bits | |
aes |
128 bits | |
aes-128 |
128 bits | |
aes-192 |
192 bits | |
aes-256 |
256 bits | |
aesctr |
160 bits | [phase 2 only, IKE only] |
aes-128-ctr |
160 bits | [phase 2 only, IKE only] |
aes-192-ctr |
224 bits | [phase 2 only, IKE only] |
aes-256-ctr |
288 bits | [phase 2 only, IKE only] |
aes-128-gcm |
160 bits | [phase 2 only, IKE only] |
aes-192-gcm |
224 bits | [phase 2 only, IKE only] |
aes-256-gcm |
288 bits | [phase 2 only, IKE only] |
aes-128-gmac |
160 bits | [phase 2 only, IKE only] |
aes-192-gmac |
224 bits | [phase 2 only, IKE only] |
aes-256-gmac |
288 bits | [phase 2 only, IKE only] |
blowfish |
160 bits | |
cast |
128 bits | |
null |
(none) | [phase 2 only] |
3DES requires 24 bytes to form its 168-bit key. This is because the most significant bit of each byte is used for parity.
The keysize of AES-CTR can be 128, 192, or 256 bits. However as well as the key, a 32-bit nonce has to be supplied. Thus 160, 224, or 288 bits of key material, respectively, have to be supplied. The same applies to AES-GCM and AES-GMAC.
Using AES-GMAC or NULL with ESP will only provide authentication. This is useful in setups where AH cannot be used, e.g. when NAT is involved.
The following group types are permitted with the
group
keyword:
Group | Size | |
modp768 |
768 | [DH group 1] |
modp1024 |
1024 | [DH group 2] |
modp1536 |
1536 | [DH group 5] |
modp2048 |
2048 | [DH group 14] |
modp3072 |
3072 | [DH group 15] |
modp4096 |
4096 | [DH group 16] |
modp6144 |
6144 | [DH group 17] |
modp8192 |
8192 | [DH group 18] |
ecp256 |
256 | [DH group 19] |
ecp384 |
384 | [DH group 20] |
ecp521 |
512 | [DH group 21] |
ecp192 |
192 | [DH group 25] |
ecp224 |
224 | [DH group 26] |
bp224 |
224 | [DH group 27] |
bp256 |
256 | [DH group 28] |
bp384 |
384 | [DH group 29] |
bp512 |
512 | [DH group 30] |
none |
0 | [phase 2 only] |
In this scenario, ipsec.conf
is used to
set up flows manually. IPsec uses flows to determine whether to apply
security services to an IP packet or not. Some examples of setting up
flows:
# Set up two flows: # First between the machines 192.168.3.14 and 192.168.3.100 # Second between the networks 192.168.7.0/24 and 192.168.8.0/24 flow esp from 192.168.3.14 to 192.168.3.100 flow esp from 192.168.7.0/24 to 192.168.8.0/24 peer 192.168.3.12
The following types of flow are available:
flow
esp
flow
ah
flow
ipip
The commands are as follows:
in
or out
in
nor out
are specified,
ipsecctl(8) will assume
the direction out
for this rule and will construct
a proper in
rule. Thus packets in both directions
will be matched.proto
protocolproto
parameter restricts the flow to
a specific IP protocol. Common protocols are
icmp(4),
tcp(4), and
udp(4). For a list of all the
protocol name to number mappings used by
ipsecctl(8), see the file
/etc/protocols.from
src [port
sport] to
dst [port
dport]port
modifiers restrict the flows to the specified
ports. They are only valid in conjunction with the
tcp(4) and
udp(4) protocols. Ports can be
specified by number or by name. For a list of all port name to number
mappings used by
ipsecctl(8), see the file
/etc/services.local
localiplocal
parameter specifies the address or FQDN
of the local endpoint of this flow and can be usually left out.peer
remotepeer
parameter specifies the address or FQDN
of the remote endpoint of this flow. For host-to-host connections where
dst is identical to remote,
the peer
specification can be left out as it will
be set to dst automatically. Only if the keyword
any is given is a flow without peer created.type
modifierIn this scenario, ipsec.conf
is used to
set up SAs manually. The security parameters for a flow are stored in the
Security Association Database (SADB). An example of setting up an SA:
# Set up an IPsec SA for flows between 192.168.3.14 and 192.168.3.12 esp from 192.168.3.14 to 192.168.3.12 spi 0xdeadbeef:0xbeefdead \ authkey file "auth14:auth12" enckey file "enc14:enc12"
Parameters specify the peers, Security Parameter Index (SPI), cryptographic transforms, and key material to be used. The following rules enter SAs in the SADB:
The commands are as follows:
from
src to
dstspi
numberudpencap
[port
dport]auth
algorithmIf no algorithm is specified, ipsecctl(8) will choose hmac-sha2-256 by default.
enc
algorithmIf no algorithm is specified, ipsecctl(8) will choose aes by default.
authkey
keyspecauthkey file "filename"
enckey
keyspecauthkey
.bundle
identifiertcpmd5
from
src
to
dst
spi
number
authkey
keyspecThis rule applies for packets with source address
src and destination address
dst. The parameter spi
is
a 32-bit value defining the Security Parameter Index (SPI) for this SA.
The encryption key is defined similarly to
authkey
.
Since an SA is directional, a second SA is normally configured in
the reverse direction. This is done by adding a second, colon-separated,
value to spi
, authkey
, and
enckey
.
openssl(1), enc(4), ipcomp(4), ipsec(4), tcp(4), pf.conf(5), ipsecctl(8), isakmpd(8)
The ipsec.conf
file format first appeared
in OpenBSD 3.8.
February 16, 2020 | OpenBSD-6.9 |