Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ISAKMPD(8)		FreeBSD	System Manager's Manual		    ISAKMPD(8)

NAME
     isakmpd --	ISAKMP/Oakley a.k.a. IKEv1 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 (SAs)	for encrypted
     and/or authenticated network traffic.  At this moment, and	probably for-
     ever, 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 sup-
     ported 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 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
     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.

     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 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_open_offline(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 [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	specified as
	     `A', the level applies to all debug classes.  D T toggles all de-
	     bug 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	(the default is	/var/run/isakmpd.pcap).	 Note that only	paths
	     beginning with /var/run are allowed.

     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 syslog(3).  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.

	   X.509 Certificates:
	   X.509 Certificates are used to authenticate.	 See X.509
	   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).

X.509 AUTHENTICATION
     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.

     1.	  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 genrsa -out /etc/ssl/private/ca.key 2048
		# openssl req -new -key	/etc/ssl/private/ca.key	\
			-out /etc/ssl/private/ca.csr

	  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:

		# openssl x509 -req -days 365 -in /etc/ssl/private/ca.csr \
			-signkey /etc/ssl/private/ca.key \
			-extfile /etc/ssl/x509v3.cnf -extensions x509v3_CA \
			-out /etc/ssl/ca.crt

     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.  A
	  fully	qualified domain name (FQDN) may be used instead of an IPv4
	  ID.  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 configuration file is used to add a	subjectAltName
	  extension field matching the ID used by isakmpd to the certificate.

	  If using an IPv4 ID, copy /etc/ssl/x509v3.cnf	to a temporary file
	  and edit it to replace $ENV::CERTIP with the IP address (10.0.0.1 in
	  this example), then generate a signed	certificate:

		# sed 's,\$ENV::CERTIP,10.0.0.1,' \
			< /etc/ssl/x509v3.cnf >	~/tmp_x509v3.cnf
		# openssl x509 -req \
			-days 365 -in 10.0.0.1.csr \
			-CA /etc/ssl/ca.crt -CAkey /etc/ssl/private/ca.key \
			-CAcreateserial	-extfile ~/tmp_x509v3.cnf \
			-extensions x509v3_IPAddr -out 10.0.0.1.crt

	  For an FQDN certificate, replace $ENV::CERTFQDN with the hostname
	  and generate a signed	certificate:

		# sed 's,\$ENV::CERTFQDN,somehost.somedomain,' \
			< /etc/ssl/x509v3.cnf >	~/tmp_x509v3.cnf
		# openssl x509 -req \
			-days 365 -in somehost.somedomain.csr \
			-CA /etc/ssl/ca.crt -CAkey /etc/ssl/private/ca.key \
			-CAcreateserial	-extfile ~/tmp_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_open_offline(3), ipsec(4),
     ipsec.conf(5), isakmpd.conf(5), isakmpd.policy(5),	iked(8), sasyncd(8),
     ssl(8), tcpdump(8)

STANDARDS
     D.	Piper, The Internet IP Security	Domain of Interpretation for ISAKMP,
     RFC 2407, November	1998.

     D.	Maughan, M. Schertler, M. Schneider, and J. Turner, Internet Security
     Association and Key Management Protocol (ISAKMP), RFC 2408, November
     1998.

     D.	Harkins	and D. Carrel, The Internet Key	Exchange (IKE),	RFC 2409,
     November 1998.

     T.	Kivinen, B. Swander, A.	Huttunen, and V. Volpe,	Negotiation of NAT-
     Traversal in the IKE, RFC 3947, January 2005.

HISTORY
     This implementation of the	ISAKMP/Oakley key management protocol was done
     in	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
     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 with carp(4) and sasyncd(8), sasyncd(8) must be man-
     ually restarted every time	isakmpd	is restarted, and isakmpd.conf(5) must
     explicitly	configure isakmpd to listen on the virtual IP address of each
     carp(4) interface.

FreeBSD	13.0			August 30, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | THE FIFO USER INTERFACE | SETTING UP AN IKE PUBLIC KEY INFRASTRUCTURE (PKI) | PUBLIC KEY AUTHENTICATION | X.509 AUTHENTICATION | KEYNOTE AUTHENTICATION | FILES | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=isakmpd&sektion=8&manpath=OpenBSD+6.9>

home | help