The isakmpd daemon establishes security
associations for encrypted and/or authenticated network traffic. At this
moment, and probably forever, this means
ipsec(4) traffic.
Traditionally, isakmpd was configured using
the
isakmpd.conf(5)
file format. A newer, much simpler format is now available:
ipsec.conf(5).

isakmpd implements the IKEv1 protocol which
is defined in the standards ISAKMP/Oakley (RFC 2408), IKE (RFC 2409), and the
Internet DOI (RFC 2407). The newer IKEv2 protocol, as defined in RFC 5996, is
not supported by isakmpd but by
iked(8). It follows
then that references to IKE in this document pertain to IKEv1 only, and not
IKEv2.

The way isakmpd goes about its work is by
maintaining an internal configuration as well as a policy database which
describes what kinds of SAs to negotiate, and by listening for different
events that trigger these negotiations. The events that control
isakmpd consist of negotiation initiations
from a remote party, user input via a FIFO or by signals, upcalls from the
kernel via a PF_KEY socket, and lastly by
scheduled events triggered by timers running out.

Most uses of isakmpd will be to implement so
called "virtual private networks" (VPNs). The ability to provide
redundancy is made available through
carp(4) and
sasyncd(8). For
other uses, some more knowledge of IKEv1 as a protocol is required. The RFCs
mentioned below are a possible starting point.

On startup isakmpd forks into two processes
for privilege separation. The unprivileged child jails itself with
chroot(8) to
/var/empty. The privileged process
communicates with the child, reads configuration files and PKI information,
and binds to privileged ports on its behalf. See the
CAVEATS section below.

If given, the -c option specifies an
alternate configuration file instead of
/etc/isakmpd/isakmpd.conf. As this file
may contain sensitive information, it must be readable only by the user
running the daemon. isakmpd will reread
the configuration file when sent a
SIGHUP signal.

Debugging class. It's possible to specify this argument many times. It
takes a parameter of the form
class=level,
where both class and
level are numbers.
class denotes a debugging class, and
level the level you want that debugging
class to limit debug printouts at (i.e. all debug printouts above the
level specified will not output anything). If
class is set to ‘A’, then
all debugging classes are set to the specified level.

By default the PID of the daemon process will be written to
/var/run/isakmpd.pid. This path can be
overridden by specifying another one as the argument to the
-i option. Note that only paths
beginning with /var/run are
allowed.

When this option is given, isakmpd does
not read the policy configuration file and no
keynote(4)
policy check is accomplished. This option can be used when policies for
flows and SA establishment are arranged by other programs like
ipsecctl(8) or
bgpd(8).

Enable IKE packet capture. When this option is given,
isakmpd will write an unencrypted copy
of the negotiation packets it is sending and receiving to the file
/var/run/isakmpd.pcap, which can later
be read by
tcpdump(8) and
other utilities using
pcap(3).

When you signal isakmpd a
SIGUSR1, it will report its internal
state to a report file, normally
/var/run/isakmpd.report, but this can
be changed by feeding the file name as an argument to the
-R flag. Note that only paths beginning
with /var/run are allowed.

This option is used for setups using
sasyncd(8) and
carp(4) to provide
redundancy. isakmpd starts in passive
mode and will not initiate any connections or process any incoming traffic
until sasyncd has determined that the host is the carp master.
Additionally, isakmpd will not delete
SAs on shutdown by sending delete messages to all peers.

Update the running isakmpd
configuration atomically. ‘set’ sets a configuration value
consisting of a section, tag, and value triplet. ‘set’ will
fail if the configuration already contains a section with the named tag;
use the ‘force’ option to change this behaviour.
‘add’ appends a configuration value to the named
configuration list tag, unless the value is already in the list.
‘rm’ removes a tag in a section. ‘rms’ removes
an entire section. ‘rmv’ removes an entry from a list, thus
reversing an ‘add’ operation.

NOTE: Sending isakmpd a
SIGHUP or an "R" through the
FIFO will void any updates done to the configuration.

Set debug class class to level
level. If
class is specified as ‘A’,
the level applies to all debug classes. D
T toggles all debug classes to level zero. Another
D T command will toggle them back to
the earlier levels.

Enable or disable cleartext IKE packet capture. When enabling, optionally
specify which file isakmpd should
capture the packets to (the default is
/var/run/isakmpd.pcap). Note that only
paths beginning with /var/run are
allowed.

Tear down the named connection, if active. For
name, the tag specified in
isakmpd.conf(5)
or the IP address of the remote host can be used. The optional parameter
phase specifies whether to delete a phase
1 or phase 2 SA. The value ‘main’ indicates a phase 1
connection; the value ‘quick’ a phase 2 connection. If no
phase is specified, ‘quick’ will be assumed.

In order to use public key based authentication, there has to be an
infrastructure managing the key signing. Either there is an already existing
PKI isakmpd should take part in, or there
will be a need to set one up. The procedures for using a pre-existing PKI
varies depending on the actual Certificate Authority (CA) used, and is
therefore not covered here, other than mentioning that
openssl(1) needs to
be used to create a Certificate Signing Request (CSR) that the CA understands.

A number of methods exist to allow authentication:

Passphrase:

This method does not use keys at all, but relies on a shared
passphrase.

When configuring isakmpd for key- and
certificate-based authentication, the “Transforms” tag in
isakmpd.conf(5)
should include “RSA_SIG”. For example, the transform
“3DES-SHA-RSA_SIG” means: 3DES encryption, SHA hash,
authentication using RSA signatures.

It is possible to store trusted public keys to make them directly usable by
isakmpd, bypassing the need to use
certificates. The keys should be saved in PEM format (see
openssl(1)) and
named and stored after this easy formula:

For IPv4 identities:

/etc/isakmpd/pubkeys/ipv4/A.B.C.D

For IPv6 identities:

/etc/isakmpd/pubkeys/ipv6/abcd:abcd::ab:bc

For FQDN identities:

/etc/isakmpd/pubkeys/fqdn/foo.bar.org

For UFQDN identities:

/etc/isakmpd/pubkeys/ufqdn/user@foo.bar.org

Depending on the ID-type field of
isakmpd.conf(5),
keys may be named after their IPv4 address (IPV4_ADDR or IPV4_ADDR_SUBNET),
IPv6 address (IPV6_ADDR or IPV6_ADDR_SUBNET), fully qualified domain name
(FDQN), user fully qualified domain name (USER_FQDN), or key ID (KEY_ID).

For example, isakmpd can authenticate using
the pre-generated keys if the local public key, by default
/etc/isakmpd/local.pub, is copied to the
remote gateway as
/etc/isakmpd/pubkeys/ipv4/local.gateway.ip.address
and the remote gateway's public key is copied to the local gateway as
/etc/isakmpd/pubkeys/ipv4/remote.gateway.ip.address.
Of course, new keys may also be generated (the user is not required to use the
pre-generated keys). In this example,
ID-type would also have to be set to
IPV4_ADDR or IPV4_ADDR_SUBNET in
isakmpd.conf(5).

X.509 is a framework for public key certificates. Certificates can be generated
using openssl(1)
and provide a means for PKI authentication. In the following example, a CA is
created along with host certificates to be signed by the CA.

Create your own Certificate Authority (CA).

First, create a private key for the CA, and a Certificate Signing Request
(CSR) to enable the CA to sign its own key:

openssl req will prompt for information
that will be incorporated into the certificate request. The information
entered comprises a Distinguished Name (DN). There are quite a few fields,
but some can be left blank. For some fields there will be a default value;
if ‘.’ is entered, the field will be left blank.

After the CSR has been generated, it is used to create and sign a
certificate for the CA:

Create Certificate Signing Requests (CSRs) for IKE peers. The CSRs are
signed with a pre-generated private key.

This step, as well as the next one, needs to be done for every peer.
Furthermore the last step will need to be done once for each ID you want
the peer to have. The 10.0.0.1 below symbolizes that ID, in this case an
IPv4 ID, and should be changed for each invocation. You will be asked for
a DN for each run. Encoding the ID in the common name is recommended, as
it should be unique.

Now take these certificate signing requests to your CA and process them as
below. A subjectAltName extension field
should be added to the certificate. Replace 10.0.0.1 with the IP address
which isakmpd will use as the
certificate identity.

Copy /etc/ssl/x509v3.cnf to a temporary
file and edit it to replace
$ENV::CERTIP with 10.0.0.1, then run:

If CERTFQDN is being used, make sure that the
subjectAltName field of the certificate
is specified using srcid in
ipsec.conf(5).
A similar setup will be required if
isakmpd.conf(5)
is being used instead.

Put the certificate (the file ending in .crt) in
/etc/isakmpd/certs/ on your local
system. Also carry over the CA cert
/etc/ssl/ca.crt and put it in
/etc/isakmpd/ca/.

To revoke certificates, create a Certificate Revocation List (CRL) file and
install it in the /etc/isakmpd/crls/
directory. See
openssl(1) and the
‘crl’ subcommand for more info.

The directory where IKE certificates are kept, both the local
certificate(s) and those of the peers, if a choice to have them kept
permanently has been made.

/etc/isakmpd/crls/

The directory where CRLs are kept.

/etc/isakmpd/isakmpd.conf

The configuration file. As this file can contain sensitive information it
must not be readable by anyone but the user running
isakmpd.

/etc/isakmpd/isakmpd.policy

The keynote policy configuration file. The same mode requirements as
isakmpd.conf.

/etc/isakmpd/keynote/

The directory where KeyNote credentials are kept.

/etc/isakmpd/private/

The directory where local private keys used for public key authentication
are kept. By default, the system startup script
rc(8) generates a
key-pair when starting, if one does not already exist. The entire keypair
is in local.key, and a copy of the
public key suitable for transferring to other hosts is extracted into
/etc/isakmpd/local.pub. There has to be
a certificate for local.key in the
certificate directory,
/etc/isakmpd/certs/.
local.key has the same mode
requirements as isakmpd.conf.

/etc/isakmpd/pubkeys/

The directory in which trusted public keys are kept. The keys must be
named in the fashion described above.

/var/run/isakmpd.fifo

The FIFO used to manually control
isakmpd.

/var/run/isakmpd.pcap

The default IKE packet capture file.

/var/run/isakmpd.pid

The PID of the current daemon.

/var/run/isakmpd.report

The report file written when SIGUSR1 is
received.

/var/run/isakmpd.result

The report file written when the ‘S’ or ‘C
get’ command is issued in the command FIFO.

When storing a trusted public key for an IPv6 identity, the
most efficient form of address representation,
i.e. "::" instead of ":0:0:0:", must be used or the
matching will fail. isakmpd uses the output
from
getnameinfo(3)
for the address-to-name translation. The privileged process only allows
binding to the default port 500 or unprivileged ports (>1024). It is not
possible to change the interfaces isakmpd
listens on without a restart.

For redundant setups,
sasyncd(8) must be
manually restarted every time isakmpd is
restarted.