NAME

isakmpd.conf - configuration file for isakmpd

DESCRIPTION

isakmpd.conf is the configuration file for the isakmpd daemon managing
security association and key management for the IPsec layer of the
kernel’s networking stack.
The file is of a well known type of format called .INI style, named after
the suffix used by an overrated windowing environment for its
configuration files. This format consists of sections, each beginning
with a line looking like:
[Section name]
Between the brackets is the name of the section following this section
header. Inside a section many tag/value pairs can be stored, each one
looking like:
Tag=Value
If the value needs more space than fits on a single line it’s possible to
continue it on the next by ending the first with a backslash character
immediately before the newline character. This method can extend a value
for an arbitrary number of lines.
Comments can be put anywhere in the file by using a hash mark (‘#’). The
comment extends to the end of the current line.
Often the right-hand side values consist of other section names. This
results in a tree structure. Some values are treated as a list of
several scalar values. Such lists always use a comma character as the
separator. Some values are formatted like this: X,Y:Z, which is an
offer/accept syntax, where X is a value we offer and Y:Z is a range of
accepted values, inclusive.
To activate changes to isakmpd.conf without restarting isakmpd, send a
SIGHUP signal to the daemon process.
Auto-generatedpartsoftheconfiguration
Some predefined section names are recognized by the daemon, avoiding the
need to fully specify the Main Mode transforms and Quick Mode suites,
protocols, and transforms.
For Main Mode:
{DES,BLF,3DES,CAST,AES}-{MD5,SHA}[-GRP{1,2,5,14}][-{DSS,RSA_SIG}]
For Quick Mode:
QM-{proto}[-TRP]-{cipher}[-{hash}][-PFS[-{group}]]-SUITE
where
{proto} is either ESP or AH
{cipher} is either DES, 3DES, CAST, BLF or AES
{hash} is either MD5, SHA, RIPEMD, SHA2-{256,384,512}
{group} is either GRP1, GRP2, GRP5 or GRP14
For example, 3DES-SHA means: 3DES encryption, SHA hash, and authorization
by pre-shared keys. Similarly, QM-ESP-3DES-SHA-PFS-SUITE means: ESP
protocol, 3DES encryption, SHA hash, and use Perfect Forward Secrecy.
Unless explicitly stated with -GRP1, 2, 5 or 14 transforms and PFS suites
use DH group 2. There are currently no predefined ESP+AH Quick Mode
suites.
The predefinitions include some default values for the special sections
"General", "Keynote", "X509-certificates", and "Default-
phase-1-configuration". These default values are presented in the
example below.
All autogenerated values can be overridden by manual entries by using the
same section and tag names in the configuration file. In particular, the
default phase 1 (Main or Aggressive Mode) and phase 2 (Quick Mode)
lifetimes can be overridden by these tags under the "General" section;
[General]
Default-phase-1-lifetime= 3600,60:86400
Default-phase-2-lifetime= 1200,60:86400
The Main Mode lifetime currently defaults to one hour (minimum 60
seconds, maximum 1 day). The Quick Mode lifetime defaults to 20 minutes
(minimum 60 seconds, maximum 1 day).
Also, the default phase 1 ID can be set by creating a <Phase1-ID>
section, as shown below, and adding this tag under the "General" section;
[General]
Default-phase-1-ID= Phase1-ID-name
[Phase1-ID-name]
ID-type= USER_FQDN
Name= foo@bar.comRootsGeneral Generic global configuration parameters
Default-phase-1-ID
Optional default phase 1 ID name.
Default-phase-1-lifetime
The default lifetime for autogenerated
transforms (phase 1). If unspecified, the
value 3600,60:86400 is used as the default.
Default-phase-2-lifetime
The default lifetime for autogenerated suites
(phase 2). If unspecified, the value
1200,60:86400 is used as the default.
Default-phase-2-suites
A list of phase 2 suites that will be used
when establishing dynamic SAs. If left
unspecified, QM-ESP-3DES-SHA-PFS-SUITE is
used as the default.
Acquire-Only If this tag is defined, isakmpd will not set
up flows automatically. This is useful when
flows are configured with ipsecadm(4) or by
other programs like bgpd(8). Thus isakmpd
only takes care of the SA establishment.
Check-interval
The interval between watchdog checks of
connections we want up at all times.
DPD-check-interval
The interval between RFC 3706 (Dead Peer
Detection) messages. The default value is 0
(zero), which means DPD is disabled.
Exchange-max-time
How many seconds should an exchange maximally
take to set up before we give up.
Listen-on A list of IP-addresses OK to listen on. This
list is used as a filter for the set of
addresses the interfaces configured provides.
This means that we won’t see if an address
given here does not exist on this host, and
thus no error is given for that case.
Loglevel A list of the form class=level, where both
class and level are numbers. This is similar
to the -D command line switch of isakmpd.
See isakmpd(8) for details.
Logverbose If this tag is defined, whatever the value
is, verbose logging is enabled. This is
similar to the -v command line switch of
isakmpd. See isakmpd(8) for details.
NAT-T-Keepalive
The number of seconds between NAT-T keepalive
messages, sent by the peer behind NAT to keep
the mapping active. Defaults to 20.
Policy-file The name of the file that contains keynote(4)
policies. The default is
"/etc/isakmpd/isakmpd.policy".
Pubkey-directory
The directory in which isakmpd.conf looks for
explicitly trusted public keys. The default
is "/etc/isakmpd/pubkeys". Read isakmpd(8)
for the required naming convention of the
files in here.
Renegotiate-on-HUP
If this tag is defined, whatever the value
is, isakmpd will renegotiate all current
phase 2 SAs when the daemon receives a SIGHUP
signal, or an ‘R’ is sent to the FIFO
interface (see isakmpd(8)).
Retransmits How many times should a message be
retransmitted before giving up.
Shared-SADB If this tag is defined, whatever the value
is, some semantics of isakmpd.conf are
changed so that multiple instances can run on
top of one SADB and set up SAs with each
other. Specifically this means replay
protection will not be asked for, and errors
that can occur when updating an SA with its
parameters a 2nd time will be ignored.
Use-Keynote This tag controls the use of keynote(4)
policy checking. The default value is "yes",
which enables the policy checking. When set
to any other value, policies will not be
checked. This is useful when policies for
flows and SA establishment are arranged by
other programs like ipsecadm(8) or bgpd(8).
Phase1 ISAKMP SA negotiation parameter root
<IP-address> A name of the ISAKMP peer at the given IP-
address.
Default A name of the default ISAKMP peer. Incoming
phase 1 connections from other IP-addresses
will use this peer name.
This name is used as the section name for
further information to be found. Look at
<ISAKMP-peer> below.
Phase2 IPsec SA negotiation parameter root
Connections A list of directed IPsec "connection" names
that should be brought up automatically,
either on first use if the system supports
it, or at startup of the daemon. These names
are section names where further information
can be found. Look at <IPsec-connection>
below. Normally any connections mentioned
here are treated as part of the "Passive-
connection" list we present below, however
there is a flag: "Active-only" that disables
this behaviour. This too is mentioned in the
<IPsec-connection> section, in the "Flags"
tag.
Passive-connections
A list of IPsec "connection" names we
recognize and accept initiations for. These
names are section names where further
information can be found. Look at <IPsec-
connection> below. Currently only the Local-
ID and Remote-ID tags are looked at in those
sections, as they are matched against the IDs
given by the initiator.
KeyNoteCredential-directory
A directory containing directories named
after IDs (IP addresses, “user@domain”, or
hostnames) that contain files named
“credentials” and “private_key”.
The credentials file contains keynote(4)
credentials that are sent to a remote IKE
daemon when we use the associated ID, or
credentials that we may want to consider when
doing an exchange with a remote IKE daemon
that uses that ID. Note that, in the former
case, the last credential in the file MUST
contain our public key in its Licensees
field. More than one credentials may exist
in the file. They are separated by
whitelines (the format is essentially the
same as that of the policy file). The
credentials are of the same format as the
policies described in isakmpd.policy(5). The
only difference is that the Authorizer field
contains a public key, and the assertion is
signed. Signed assertions can be generated
using the keynote(1) utility.
The private_key file contains the private RSA
key we use for authentication. If the
directory (and the files) exist, they take
precedence over X509-based authentication.
X509-CertificatesAccept-self-signed
If this tag is defined, whatever the value
is, certificates that do not originate from a
trusted CA but are self-signed will be
accepted.
Ca-directory A directory containing PEM certificates of
certification authorities that we trust to
sign other certificates. Note that for a CA
to be really trusted, it needs to be somehow
referred to by policy, in isakmpd.policy(5).
The certificates in this directory are used
for the actual X.509 authentication and for
cross-referencing policies that refer to
Distinguished Names (DNs). Keeping a
separate directory (as opposed to integrating
policies and X.509 CA certificates) allows
for maintenance of a list of "well known" CAs
without actually having to trust all (or any)
of them.
Cert-directory
A directory containing PEM certificates that
we trust to be valid. These certificates are
used in preference to those passed in
messages and are required to have a
subjectAltName extension containing the
certificate holder identity; usually IP
address, FQDN, or User FQDN, as provided by
certpatch(8).
Private-key The private key matching the public key of
our certificate (which should be in the
"Cert-directory", and have an appropriate
subjectAltName field).
Referred-tosections<ISAKMP-peer> Parameters for negotiation with an ISAKMP peer
Phase The constant 1, as ISAKMP-peers and IPsec-
connections really are handled by the same
code inside isakmpd.
Transport The name of the transport protocol, defaults
to UDP.
Port In case of UDP, the UDP port number to send
to. This is optional, the default value is
500 which is the IANA-registered number for
ISAKMP.
Local-address
The Local IP-address to use, if we are multi-
homed, or have aliases.
Address If existent, the IP-address of the peer.
Configuration
The name of the ISAKMP-configuration section
to use. Look at <ISAKMP-configuration>
below. If unspecified, defaults to "Default-
phase-1-configuration".
Authentication
If existent, authentication data for this
specific peer. In the case of preshared key,
this is the key value itself.
ID If existent, the name of the section that
describes the local client ID that we should
present to our peer. If not present, it
defaults to the address of the local
interface we are sending packets over to the
remote daemon. Look at <Phase1-ID> below.
Remote-ID If existent, the name of the section that
describes the remote client ID we expect the
remote daemon to send us. If not present, it
defaults to the address of the remote daemon.
Look at <Phase1-ID> below.
Flags A comma-separated list of flags controlling
the further handling of the ISAKMP SA.
Currently there are no specific ISAKMP SA
flags defined.
<Phase1-ID>ID-type The ID type as given by the RFC
specifications. For phase 1 this is
currently IPV4_ADDR, IPV4_ADDR_SUBNET,
IPV6_ADDR, IPV6_ADDR_SUBNET, FQDN, USER_FQDN
or KEY_ID.
Address If the ID-type is IPV4_ADDR or IPV6_ADDR,
this tag should exist and be an IP-address.
Network If the ID-type is IPV4_ADDR_SUBNET or
IPV6_ADDR_SUBNET this tag should exist and be
a network address.
Netmask If the ID-type is IPV4_ADDR_SUBNET or
IPV6_ADDR_SUBNET this tag should exist and be
a network subnet mask.
Name If the ID-type is FQDN, USER_FQDN or KEY_ID,
this tag should exist and contain a domain
name, user@domain, or other identifying
string respectively.
In the case of KEY_ID, note that the IKE
protocol allows any octet sequence to be sent
or received under this payload, potentially
including non-printable ones. isakmpd(8) can
only transmit printable KEY_ID payloads, but
can receive and process arbitrary KEY_ID
payloads. This effectively means that non-
printable KEY_ID remote identities cannot be
verified through this means, although it is
still possible to do so through
isakmpd.policy(5).
<ISAKMP-configuration>DOI The domain of interpretation as given by the
RFCs. Normally IPSEC. If unspecified,
defaults to IPSEC.
EXCHANGE_TYPE
The exchange type as given by the RFCs. For
main mode this is ID_PROT and for aggressive
mode it is AGGRESSIVE.
Transforms A list of proposed transforms to use for
protecting the ISAKMP traffic. These are
actually names for sections further
describing the transforms. Look at <ISAKMP-
transform> below.
<ISAKMP-transform>ENCRYPTION_ALGORITHM
The encryption algorithm as the RFCs name it,
or ANY to denote that any encryption
algorithm proposed will be accepted.
KEY_LENGTH For encryption algorithms with variable key
length, this is where the offered/accepted
keylengths are described. The value is of
the offer-accept kind described above.
HASH_ALGORITHM
The hash algorithm as the RFCs name it, or
ANY.
AUTHENTICATION_METHOD
The authentication method as the RFCs name
it, or ANY.
GROUP_DESCRIPTION
The group used for Diffie-Hellman
exponentiations, or ANY. The names are
symbolic, like MODP_768, MODP_1024, EC_155
and EC_185.
PRF The algorithm to use for the keyed pseudo-
random function (used for key derivation and
authentication in phase 1), or ANY.
Life A list of lifetime descriptions, or ANY. In
the former case, each element is in itself a
name of the section that defines the
lifetime. Look at <Lifetime> below. If it
is set to ANY, then any type of proposed
lifetime type and value will be accepted.
<Lifetime>LIFE_TYPE SECONDS or KILOBYTES depending on the type of
the duration. Notice that this field may NOT
be set to ANY.
LIFE_DURATION
An offer/accept kind of value, see above.
Can also be set to ANY.
<IPsec-connection>Phase The constant 2, as ISAKMP-peers and IPsec-
connections really are handled by the same
code inside isakmpd.
ISAKMP-peer The name of the ISAKMP-peer which to talk to
in order to set up this connection. The
value is the name of an <ISAKMP-peer>
section. See above.
Configuration
The name of the IPsec-configuration section
to use. Look at <IPsec-configuration> below.
Local-ID If existent, the name of the section that
describes the optional local client ID that
we should present to our peer. It is also
used when we act as responders to find out
what <IPsec-connection> we are dealing with.
Look at <IPsec-ID> below.
Remote-ID If existent, the name of the section that
describes the optional remote client ID that
we should present to our peer. It is also
used when we act as responders to find out
what <IPsec-connection> we are dealing with.
Look at <IPsec-ID> below.
Flags A comma-separated list of flags controlling
the further handling of the IPsec SA.
Currently only one flag is defined:
Active-only If this flag is given and this
<IPsec-connection> is part of
the phase 2 connections we
automatically keep up, it will
not automatically be used for
accepting connections from the
peer.
<IPsec-configuration>DOI The domain of interpretation as given by the
RFCs. Normally IPSEC. If unspecified,
defaults to IPSEC.
EXCHANGE_TYPE
The exchange type as given by the RFCs. For
quick mode this is QUICK_MODE.
Suites A list of protection suites (bundles of
protocols) usable for protecting the IP
traffic. Each of the list elements is a name
of an <IPsec-suite> section. See below.
<IPsec-suite>Protocols A list of the protocols included in this
protection suite. Each of the list elements
is a name of an <IPsec-protocol> section.
See below.
<IPsec-protocol>PROTOCOL_ID The protocol as given by the RFCs.
Acceptable values today are IPSEC_AH and
IPSEC_ESP.
Transforms A list of transforms usable for implementing
the protocol. Each of the list elements is a
name of an <IPsec-transform> section. See
below.
ReplayWindow The size of the window used for replay
protection. This is normally left alone.
Look at the ESP and AH RFCs for a better
description.
<IPsec-transform>TRANSFORM_ID The transform ID as given by the RFCs.
ENCAPSULATION_MODE
The encapsulation mode as given by the RFCs.
This means TRANSPORT or TUNNEL.
AUTHENTICATION_ALGORITHM
The optional authentication algorithm in the
case of this being an ESP transform.
GROUP_DESCRIPTION
An optional (provides PFS if present) Diffie-
Hellman group description. The values are
the same as GROUP_DESCRIPTION’s in <ISAKMP-
transform> sections shown above.
Life List of lifetimes, each element is a
<Lifetime> section name.
<IPsec-ID>ID-type The ID type as given by the RFCs. For IPsec
this is currently IPV4_ADDR, IPV6_ADDR,
IPV4_ADDR_SUBNET or IPV6_ADDR_SUBNET.
Address If the ID-type is IPV4_ADDR or IPV6_ADDR this
tag should exist and be an IP-address.
Network If the ID-type is IPV4_ADDR_SUBNET or
IPV6_ADDR_SUBNET this tag should exist and be
a network address.
Netmask If the ID-type is IPV4_ADDR_SUBNET or
IPV6_ADDR_SUBNET this tag should exist and be
a network subnet mask.
Protocol If the ID-type is IPV4_ADDR,
IPV4_ADDR_SUBNET, IPV6_ADDR or
IPV6_ADDR_SUBNET this tag indicates what
transport protocol should be transmitted over
the SA. If left unspecified, all transport
protocols between the two address (ranges)
will be sent (or permitted) over that SA.
Port If the ID-type is IPV4_ADDR,
IPV4_ADDR_SUBNET, IPV6_ADDR or
IPV6_ADDR_SUBNET this tag indicates what
source or destination port is allowed to be
transported over the SA (depending on whether
this is a local or remote ID). If left
unspecified, all ports of the given transport
protocol will be transmitted (or permitted)
over the SA. The Protocol tag must be
specified in conjunction with this tag.
Othersections<IKECFG-ID> Parameters to use with IKE mode-config. One ID per peer.
An IKECFG-ID is written as [<ID-type>/<name>]. The
following ID types are supported:
IPv4 [ipv4/A.B.C.D]
IPv6 [ipv6/abcd:abcd::ab:cd]
FQDN [fqdn/foo.bar.org]
UFQDN [ufqdn/user@foo.bar.org]
ASN1_DN [asn1_dn//C=aa/O=cc/...] (Note the double
slashes as the DN itself starts with a ‘/’.)
Each section specifies what configuration values to return
to the peer requesting IKE mode-config. Currently
supported values are:
Address The peer’s network address.
Netmask The peer’s netmask.
Nameserver The IP address of a DNS nameserver.
WINS-server The IP address of a WINS server.
<Initiator-ID>
During phase 1 negotiation isakmpd looks for a pre-shared
key in the <ISAKMP-peer> section. If no Authentication
data is specified in that section, and isakmpd is not the
initiator, it looks for Authentication data in a section
named after the initiator’s phase 1 ID. This allows mobile
users with dynamic IP addresses to have different shared
secrets.
This only works for aggressive mode because in main mode
the remote initiator ID would not yet be known.
The name of the <Initiator-ID> section depends on the ID
type sent by the initiator. Currently this can be:
IPv4 [A.B.C.D]
IPv6 [abcd:abcd::ab:cd]
FQDN [foo.bar.org]
UFQDN [user@foo.bar.org]

SEEALSO

BUGS

The RFCs do not permit differing DH groups in the same proposal for
aggressive and quick mode exchanges. Mixing both PFS and non-PFS suites
in a quick mode proposal is not possible, as PFS implies using a DH
group.