GeezerVison is showing man.openbsd.org — ipsec.conf(5) - OpenBSD manual pages
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.
Arguments 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
A macro is defined with a command of the form
name=value. The macro
name can contain letters, digits, and underscores and
cannot be a reserved word (for example, flow,
from, or esp). Within
unquoted arguments, the string $name is later expanded
to value.
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]- mode specifies the IKEv1 mode to use: one of
passive, active, or
dynamic. When passive is
specified, isakmpd(8) will not immediately start negotiation of this tunnel,
but wait for an incoming request from the remote peer. When
active or dynamic is
specified, negotiation will be started at once. The
dynamic mode will additionally enable Dead Peer
Detection (DPD) and use the local hostname as the identity of the local
peer, if not specified by the
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
protocol- The optional
proto 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]- This rule applies for packets with source address
src and destination address
dst. The keyword any will
match any address (i.e. 0.0.0.0/0). If the src
argument specifies a fictional source ID, the srcnat
parameter can be used to specify the actual source address. This can be
used in outgoing NAT/BINAT scenarios as described below in
OUTGOING
NETWORK ADDRESS TRANSLATION. Host addresses are parsed as type
“IPV4_ADDR”; adding the suffix /32 will change the type to
“IPV4_ADDR_SUBNET”, which can improve interoperability with
some IKEv1 implementations.
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
remote- The
local 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.
- mode
auth
algorithm enc
algorithm group
group lifetime
time
- These parameters define the mode and cryptographic transforms to be used
for the phase 1 negotiation. During phase 1 the machines authenticate and
set up an encrypted channel.
The 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
time- These parameters define the cryptographic transforms to be used for the
phase 2 negotiation. During phase 2 the actual IPsec negotiations happen.
Possible 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 ([email protected]),
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
string- Use a pre-shared key string for authentication. If
this option is not specified, public key authentication is used (see
isakmpd(8)).
tag
string- Add a pf(4) tag
to all packets of phase 2 SAs created for this connection. This will allow
matching packets for this connection by defining rules in
pf.conf(5) using the
tagged keyword.
The following variables can be used in tags to include
information from the remote peer on runtime:
- $id
- The remote phase 1 ID. It will be expanded to
id-type/id-value, e.g.
fqdn/foo.bar.org.
- $domain
- Extract the domain from IDs of type FQDN or UFQDN.
For example, if the ID is
fqdn/foo.bar.org or
ufqdn/[email protected], “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:
- external interface
- Interface for ISAKMP traffic and encapsulated IPsec traffic.
- proto udp port 500
- ISAKMP traffic on the external interface.
- proto udp port 4500
- ISAKMP NAT-Traversal traffic on the external interface.
- proto ah | esp
- Encapsulated IPsec traffic on the external interface.
- enc0
- Interface for outgoing traffic before it's been encapsulated, and incoming
traffic after it's been decapsulated. State on this interface should be
interface bound; see enc(4) for further information.
- proto ipencap
- [tunnel mode only] IP-in-IP traffic flowing between gateways on the enc0
interface.
- tagged ipsec-example.org
- Match traffic of phase 2 SAs using the
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:
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:
The following authentication types are permitted with the
auth keyword:
The following cipher types are permitted with the
enc keyword:
The following cipher types provide only authentication, not
encryption:
Transforms followed by [IKE only] can only be used with the
ike keyword; transforms with [phase 2 only] can only
be used with the quick keyword.
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, AES-GMAC and ChaCha20-Poly1305, however in the latter case the
keysize is 256 bits.
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:
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- ESP can provide the following properties: authentication, integrity,
replay protection, and confidentiality of the data. If no flow type is
specified, this is the default.
flow
ah- AH provides authentication, integrity, and replay protection, but not
confidentiality.
flow
ipip- IPIP does not provide authentication, integrity, replay protection, or
confidentiality. However, it does allow tunnelling of IP traffic over IP,
without setting up gif(4) interfaces.
The commands are as follows:
in
or out- This rule applies to incoming or outgoing packets. If neither
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
protocol- The optional
proto 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]- This rule applies for packets with source address
src and destination address
dst. The keyword any will
match any address (i.e. 0.0.0.0/0). 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- The
local parameter specifies the address or FQDN
of the local endpoint of this flow and can be usually left out.
peer
remote- The
peer 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
modifier- This optional parameter sets up special flows using modifiers. By default,
ipsecctl(8) will automatically set up normal flows with the
corresponding type. modifier may be one of the
following:
- acquire
- Use IPsec and establish SAs dynamically. Unencrypted traffic is
permitted until it is protected by IPsec.
- bypass
- Matching packets are not processed by IPsec.
- deny
- Matching packets are dropped.
- dontacq
- Use IPsec. If no SAs are available, does not trigger
isakmpd(8).
- require
- Use IPsec and establish SAs dynamically. Unencrypted traffic is not
permitted until it is protected by IPsec.
- use
- Use IPsec. Unencrypted traffic is permitted. Does not trigger
isakmpd(8).
In 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:
esp- Enter an ESP SA.
ah- Enter an AH SA.
ipcomp- Enter an IPCOMP SA.
ipip- Enter an IPIP pseudo SA.
tcpmd5- Enter a TCP MD5 SA.
The commands are as follows:
- mode
- For ESP and AH the encapsulation mode can be specified. Possible modes are
tunnel and transport. When
left out, tunnel is chosen. For details on modes see
ipsec(4).
from
src to
dst- This SA is for a flow between the peers
src and dst.
spi
number- The SPI identifies a specific SA. number is a 32-bit
value and needs to be unique.
udpencap
[port dport]- For NAT-Traversal encapsulate the IPsec traffic in UDP. The port number of
the peer can be set to dport.
auth
algorithm- For ESP and AH an authentication algorithm can be specified. Possible
values are described above in
CRYPTO TRANSFORMS.
If no algorithm is specified,
ipsecctl(8) will choose hmac-sha2-256 by
default.
enc
algorithm- For ESP an encryption algorithm can be specified. Possible values are
described above in CRYPTO
TRANSFORMS.
If no algorithm is specified,
ipsecctl(8) will choose aes by default.
authkey
keyspec- keyspec defines the authentication key to be used.
It is either a hexadecimal string or a path to a file containing the key.
The filename may be given as either an absolute path to the file or a
relative pathname, and is specified as follows:
enckey
keyspec- The encryption key is defined similarly to
authkey.
bundle
identifier- Several SAs can be attached to a single flow. The cryptographic transforms
are applied in order. The type of the first SA has to match the type of
the flow. All SAs with identical src,
dst, and identifier are
grouped together.
tcpmd5
from src
to dst
spi number
authkey keyspec- TCP MD5 signatures are generally used between BGP daemons, such as
bgpd(8).
Since bgpd(8) itself already provides this functionality, this option is
generally not needed. More information on TCP MD5 signatures can be found
in tcp(4),
bgpd.conf(5), and RFC 2385.
This 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.
- /etc/ipsec.conf
-
- /etc/examples/ipsec.conf
-
The ipsec.conf file format first appeared
in OpenBSD 3.8.
|