ISAKMPD(8)              OpenBSD System Manager's Manual             ISAKMPD(8)

NAME
     isakmpd - ISAKMP/Oakley a.k.a. IKE key management daemon

SYNOPSIS
     isakmpd [-46adKLnSTv] [-c config-file] [-D class=level] [-f fifo]
             [-i pid-file] [-l packetlog-file] [-N udpencap-port]
             [-p listen-port] [-R report-file]

DESCRIPTION
     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).

     The way isakmpd goes about its work is by maintaining an internal config-
     uration as well as a policy database which describes what kinds of SAs to
     negotiate, and by listening for different events that trigger these nego-
     tiations.  The events that control isakmpd consist of negotiation initia-
     tions 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 trig-
     gered by timers running out.

     Most uses of isakmpd will be to implement so called "virtual private net-
     works" (VPNs).  The ability to provide redundancy is made available
     through carp(4) and sasyncd(8).  For other uses, some more knowledge of
     IKE 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.

     The options are as follows:

     -4 | -6
             These options control what address family (AF_INET and/or
             AF_INET6) isakmpd will use.  The default is to use both IPv4 and
             IPv6.

     -a      If given, isakmpd does not set up flows automatically.  Instead
             manual flows may be configured using ipsec.conf(5) or by programs
             such as bgpd(8).  Thus isakmpd only takes care of SA establish-
             ment.

     -c config-file
             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 run-
             ning the daemon.  isakmpd will reread the configuration file when
             sent a SIGHUP signal.

             Note that this option applies only to configuration files in the
             isakmpd.conf(5) format, not those in the ipsec.conf(5) format.

     -D class=level
             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 de-
             bugging classes are set to the specified level.

             Valid values for class are as follows:

                   0   Misc
                   1   Transport
                   2   Message
                   3   Crypto
                   4   Timer
                   5   Sysdep
                   6   SA
                   7   Exchange
                   8   Negotiation
                   9   Policy
                   10  FIFO user interface
                   A   All

             Currently used values for level are 0 to 99.

     -d      The -d option is used to make the daemon run in the foreground,
             logging to stderr.

     -f fifo
             The -f option specifies the FIFO (a.k.a. named pipe) where the
             daemon listens for user requests.  If the path given is a dash
             (`-'), isakmpd will listen to stdin instead.

     -i pid-file
             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.

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

     -L      Enable IKE packet capture.  When this option is given, isakmpd
             will capture to file an unencrypted copy of the negotiation pack-
             ets it is sending and receiving.  This file can later be read by
             tcpdump(8) and other utilities using pcap(3).

     -l packetlog-file
             As option -L above, but capture to a specified file.  Note that
             only paths beginning with /var/run are allowed.

     -N udpencap-port
             The -N option specifies the listen port for encapsulated UDP that
             the daemon will bind to.

     -n      When the -n option is given, the kernel will not take part in the
             negotiations.  This is a non-destructive mode, so to speak, in
             that it won't alter any SAs in the IPsec stack.

     -p listen-port
             The -p option specifies the listen port the daemon will bind to.

     -R report-file
             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.

     -S      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.  Addi-
             tionally, isakmpd will not delete SAs on shutdown by sending
             delete messages to all peers.

     -T      When this option is given, NAT-Traversal will be disabled and
             isakmpd will not advertise support for NAT-Traversal to its
             peers.

     -v      Enables verbose logging.  Normally, isakmpd is silent and outputs
             only messages when a warning or an error occurs.  With verbose
             logging isakmpd reports successful completion of phase 1 (Main
             and Aggressive) and phase 2 (Quick) exchanges (Information and
             Transaction exchanges do not generate any additional status in-
             formation).

THE FIFO USER INTERFACE
     When isakmpd starts, it creates a FIFO (named pipe) where it listens for
     user requests.  All commands start with a single letter, followed by com-
     mand-specific options.  Available commands are:

     C add [section]:tag=value
     C rmv [section]:tag=value
     C rm [section]:tag
     C rms [section]
     C set [section]:tag=value
     C set [section]:tag=value force
             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 con-
             figuration list tag, unless the value is already in the list.
             `rm' removes a tag in a section.  `rms' removes an entire sec-
             tion.  `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.

     C get [section]:tag
             Get the configuration value of the specified section and tag.
             The result is stored in /var/run/isakmpd.result.

     c <name>
             Start the named connection, if stopped or inactive.

     D <class> <level>
     D A <level>
     D T     Set debug class <class> to level <level>.  If <class> is speci-
             fied 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.

     d <cookies> <msgid>
             Delete the specified SA from the system.  Specify <msgid> as `-'
             to match a Phase 1 SA.

     M active
     M passive
             Set isakmpd to active or passive mode.  In passive mode no pack-
             ets are sent to peers.

     p on[=<path>]
     p off   Enable or disable cleartext IKE packet capture.  When enabling,
             optionally specify which file isakmpd should capture the packets
             to.

     Q       Cleanly shutdown the daemon, as when sent a SIGTERM signal.

     R       Reinitialize isakmpd, as when sent a SIGHUP signal.

     r       Report isakmpd internal state to a file.  See the -R option.
             Same as when sent a SIGUSR1 signal.

     S       Report information on all known SAs to the
             /var/run/isakmpd.result file.

     T       Tear down all active quick mode connections.

     t [<phase>] <name>
             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.

SETTING UP AN IKE PUBLIC KEY INFRASTRUCTURE (PKI)
     In order to use public key based authentication, there has to be an in-
     frastructure managing the key signing.  Either there is an already exist-
     ing 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.

           Host Keys:
           Public keys are used to authenticate.  See PUBLIC KEY
           AUTHENTICATION below.

           X509 Certificates:
           X509 Certificates are used to authenticate.  See X509
           AUTHENTICATION below.

           Keynote Certificates:
           Keynote Certificates are used to authenticate.  See KEYNOTE
           AUTHENTICATION below.

     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.

PUBLIC KEY AUTHENTICATION
     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 af-
     ter 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 re-
     mote 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).

X509 AUTHENTICATION
     X509 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.

     1.   Create your own Certificate Authority (CA).

          Create a self-signed root certificate.  The CA certificate is named
          ca.crt, and its private key ca.key:

                # openssl req -x509 -days 365 -newkey rsa:1024 \
                        -keyout /etc/ssl/private/ca.key \
                        -out /etc/ssl/ca.crt

          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.

     2.   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.

                # openssl req -new -key /etc/isakmpd/private/local.key \
                        -out /etc/isakmpd/private/10.0.0.1.csr

          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.

                # env CERTIP=10.0.0.1 openssl x509 -req \
                        -days 365 -in 10.0.0.1.csr \
                        -CA /etc/ssl/ca.crt -CAkey /etc/ssl/private/ca.key \
                        -CAcreateserial -extfile /etc/ssl/x509v3.cnf \
                        -extensions x509v3_IPAddr -out 10.0.0.1.crt

          For a FQDN certificate, do:

                # env CERTFQDN=somehost.somedomain openssl x509 -req \
                        -days 365 -in somehost.somedomain.csr \
                        -CA /etc/ssl/ca.crt -CAkey /etc/ssl/private/ca.key \
                        -CAcreateserial -extfile /etc/ssl/x509v3.cnf \
                        -extensions x509v3_FQDN -out somehost.somedomain.crt

          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 in-
          stead.

          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.

KEYNOTE AUTHENTICATION
     Keynote is a trust-management framework.  Keys can be generated using
     keynote(1) and provide an alternative means for isakmpd to authenticate.
     See keynote(4) for further information.

FILES
     /etc/isakmpd/ca/
             The directory where CA certificates are kept.

     /etc/isakmpd/certs/
             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 in-
             formation it must not be readable by anyone but the user running
             isakmpd.

     /etc/isakmpd/isakmpd.policy
             The keynote policy configuration file.  The same mode require-
             ments 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 au-
             thentication 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.

SEE ALSO
     openssl(1), getnameinfo(3), pcap(3), ipsec(4), ipsec.conf(5),
     isakmpd.conf(5), isakmpd.policy(5), sasyncd(8), ssl(8), tcpdump(8)

HISTORY
     The ISAKMP/Oakley key management protocol is described in RFC 2407, RFC
     2408, and RFC 2409.  NAT-Traversal is described in RFC 3947.  This imple-
     mentation was done 1998 by Niklas Hallqvist and Niels Provos, sponsored
     by Ericsson Radio Systems.

CAVEATS
     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 pro-
     cess 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.

OpenBSD 4.7                     January 3, 2010                              7
