diff options
Diffstat (limited to 'keyexchange/isakmpd-20041012/isakmpd.8')
| -rw-r--r-- | keyexchange/isakmpd-20041012/isakmpd.8 | 603 |
1 files changed, 603 insertions, 0 deletions
diff --git a/keyexchange/isakmpd-20041012/isakmpd.8 b/keyexchange/isakmpd-20041012/isakmpd.8 new file mode 100644 index 0000000..e7f6987 --- /dev/null +++ b/keyexchange/isakmpd-20041012/isakmpd.8 @@ -0,0 +1,603 @@ +.\" $OpenBSD: isakmpd.8,v 1.65 2004/07/08 10:37:12 jmc Exp $ +.\" $EOM: isakmpd.8,v 1.23 2000/05/02 00:30:23 niklas Exp $ +.\" +.\" Copyright (c) 1998, 1999, 2000, 2001 Niklas Hallqvist. +.\" All rights reserved. +.\" Copyright (c) 1999 Angelos D. Keromytis. All rights reserved. +.\" Copyright (c) 2001, 2002 Håkan Olsson. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" This code was written under funding by Ericsson Radio Systems. +.\" +.\" Manual page, using -mandoc macros +.\" +.Dd August 07, 2002 +.Dt ISAKMPD 8 +.Os +.Sh NAME +.Nm isakmpd +.Nd ISAKMP/Oakley a.k.a. IKE key management daemon +.Sh SYNOPSIS +.Nm isakmpd +.Bk -words +.Op Fl 4 +.Op Fl 6 +.Op Fl c Ar config-file +.Op Fl a +.Op Fl d +.Op Fl D Ar class=level +.Op Fl f Ar fifo +.Op Fl i Ar pid-file +.Op Fl n +.Op Fl p Ar listen-port +.Op Fl P Ar local-port +.Op Fl K +.Op Fl L +.Op Fl l Ar packetlog-file +.Op Fl r Ar seed +.Op Fl R Ar report-file +.Op Fl v +.Ek +.Sh DESCRIPTION +The +.Nm +daemon establishes security associations for encrypted +and/or authenticated network traffic. +At this moment, and probably forever, this means +.Xr ipsec 4 +traffic. +.Pp +The way +.Nm +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 +.Nm +consist of negotiation initiations from a remote party, user input via +a FIFO or by signals, upcalls from the kernel via a +.Dv PF_KEY +socket, and lastly by scheduled events triggered by timers running out. +.Pp +Most uses of +.Nm +will be to implement so called "virtual private +networks" or VPNs for short. +The +.Xr vpn 8 +manual page describes how to set up +.Nm +for a simple VPN. +For other uses, some more knowledge of IKE as a protocol is required. +One source of information are the RFCs mentioned below. +.Pp +On startup +.Nm +forks into two processes for privilege separation. +The unprivileged child jails itself with +.Xr chroot 8 +to +.Pa /var/empty . +The privileged process communicates with the child, reads configuration files +and PKI information and binds to privileged ports on its behalf. +See +.Sx CAVEATS +section below. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 4 | Fl 6 +These options control what address family +.Pf ( Dv AF_INET +and/or +.Dv AF_INET6 ) +.Nm +will use. +The default is to use both IPv4 and IPv6. +.It Fl a +If given, +.Nm +does not set up flows automatically. +This is useful when flows are configured with +.Xr ipsecadm 4 +or by other programs like +.Xr bgpd 8 . +Thus +.Nm +only takes care of the SA establishment. +.It Fl c Ar config-file +If given, the +.Fl c +option specifies an alternate configuration file instead of +.Pa /etc/isakmpd/isakmpd.conf . +As this file may contain sensitive information, it must be readable +only by the user running the daemon. +.Nm +will reread the configuration file when sent a +.Dv SIGHUP +signal. +.It Fl d +The +.Fl d +option is used to make the daemon run in the foreground, logging to stderr. +.It Xo Fl D +.Ar class Ns = Ns Ar level +.Xc +Debugging class. +It's possible to specify this argument many times. +It takes a parameter of the form +.Ar class Ns = Ns Ar level , +where both +.Ar class +and +.Ar level +are numbers. +.Ar class +denotes a debugging class, and +.Ar 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 +.Ar class +is set to +.Sq A , +then all debugging classes are set to the specified level. +.Pp +Valid values for +.Ar class +are as follows: +.Pp +.Bl -tag -width 2n -compact -offset indent +.It 0 +Misc +.It 1 +Transport +.It 2 +Message +.It 3 +Crypto +.It 4 +Timer +.It 5 +Sysdep +.It 6 +SA +.It 7 +Exchange +.It 8 +Negotiation +.It 9 +Policy +.It 10 +FIFO user interface +.It A +All +.El +.Pp +Currently used values for +.Ar level +are 0 to 99. +.It Fl f Ar fifo +The +.Fl f +option specifies the +.Tn FIFO +(a.k.a. named pipe) where the daemon listens for +user requests. +If the path given is a dash +.Pq Sq \&- , +.Nm +will listen to stdin instead. +.It Fl i Ar pid-file +By default the PID of the daemon process will be written to +.Pa /var/run/isakmpd.pid . +This path can be overridden by specifying another one as the argument to the +.Fl i +option. +.It Fl n +When the +.Fl 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. +.It Fl p Ar listen-port +The +.Fl p +option specifies the listen port the daemon will bind to. +.It Fl P Ar local-port +On the other hand, the port specified to capital +.Fl P +will be what the daemon binds its local end to when acting as +initiator. +.It Fl K +When this option is given, +.Nm +does not read the policy configuration file and no +.Xr keynote 4 +policy check is accomplished. +This option can be used when policies for flows and SA establishment are +arranged by other programs like +.Xr ipsecadm 8 +or +.Xr bgpd 8 . +.It Fl L +Enable IKE packet capture. +When this option is given, +.Nm +will capture to file an unencrypted copy of the negotiation packets it +is sending and receiving. +This file can later be read by +.Xr tcpdump 8 +and other utilities using +.Xr pcap 3 . +.It Fl l Ar packetlog-file +As option +.Fl L +above, but capture to a specified file. +.It Fl r Ar seed +If given, a deterministic random number sequence will be used internally. +This is useful for setting up regression tests. +.It Fl R Ar report-file +When you signal +.Nm +a +.Dv SIGUSR1 , +it will report its internal state to a report file, normally +.Pa /var/run/isakmpd.report , +but this can be changed by feeding +the file name as an argument to the +.Fl R +flag. +.It Fl v +Enables verbose logging. +Normally, +.Nm +is silent and outputs only messages when a warning or an error occurs. +With verbose logging +.Nm +reports successful completion of phase 1 (Main and Aggressive) and phase 2 +(Quick) exchanges (Information and Transaction exchanges do not generate any +additional status information). +.El +.Ss Setting up an IKE public key infrastructure (a.k.a. PKI) +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 +.Nm +should take part in, or there will be a need to set one up. +In the former case, what is needed to be done varies depending on the +actual Certificate Authority used, and is therefore not covered here, +other than mentioning that +.Xr openssl 1 +needs to be used to create a certificate signing request that the +CA understands. +The latter case, however, is described here: +.Bl -enum +.It +Create your own CA as root. +.Bd -literal +# openssl genrsa -out /etc/ssl/private/ca.key 1024 +# openssl req -new -key /etc/ssl/private/ca.key \e + -out /etc/ssl/private/ca.csr +.Ed +.Pp +You are then asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name (DN). +There are quite a few fields but you can leave some blank. +For some fields there will be a default value; if you enter +.Sq \&. , +the field will be left blank. +.Bd -literal +# openssl x509 -req -days 365 -in /etc/ssl/private/ca.csr \e + -signkey /etc/ssl/private/ca.key \e + -extfile /etc/ssl/x509v3.cnf -extensions x509v3_CA \e + -out /etc/ssl/ca.crt +.Ed +.Pp +.It +Create keys and certificates for your IKE peers. +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. +.Bd -literal +# openssl genrsa -out /etc/isakmpd/private/local.key 1024 +# openssl req -new -key /etc/isakmpd/private/local.key \e + -out /etc/isakmpd/private/10.0.0.1.csr +.Ed +.Pp +Now take these certificate signing requests to your CA and process +them like below. +You have to add a subjectAltName extension field +to the certificate in order to make it usable by +.Nm isakmpd . +There are two possible ways to add the extensions to the certificate. +Either you have to run +.Xr certpatch 8 +or you have to make use of an OpenSSL configuration file, for example +.Pa /etc/ssl/x509v3.cnf . +Replace 10.0.0.1 with the IP-address which +.Nm +will use as the certificate identity. +.Pp +To use +.Xr certpatch 8 , +do the following +.Bd -literal +# openssl x509 -req -days 365 -in 10.0.0.1.csr -CA /etc/ssl/ca.crt \e + -CAkey /etc/ssl/private/ca.key -CAcreateserial \e + -out 10.0.0.1.crt +# certpatch -i 10.0.0.1 -k /etc/ssl/private/ca.key \e + 10.0.0.1.crt 10.0.0.1.crt +.Ed +.Pp +Otherwise do +.Bd -literal +# setenv CERTIP 10.0.0.1 +# openssl x509 -req -days 365 -in 10.0.0.1.csr -CA /etc/ssl/ca.crt \e + -CAkey /etc/ssl/private/ca.key -CAcreateserial \e + -extfile /etc/ssl/x509v3.cnf -extensions x509v3_IPAddr \e + -out 10.0.0.1.crt +.Ed +.Pp +For a FQDN certificate, do +.Bd -literal +# setenv CERTFQDN somehost.somedomain +# openssl x509 -req -days 365 -in somehost.somedomain.csr \e + -CA /etc/ssl/ca.crt -CAkey /etc/ssl/private/ca.key \e + -CAcreateserial \e + -extfile /etc/ssl/x509v3.cnf -extensions x509v3_FQDN \e + -out somehost.somedomain.crt +.Ed +.Pp +or with +.Xr certpatch 8 +.Bd -literal +# certpatch -t fqdn -i somehost.somedomain \e + -k /etc/ssl/private/ca.key \e + somehost.somedomain.crt somehost.somedomain.crt +.Ed +.Pp +(This assumes the previous steps were used to create a request for +somehost.somedomain instead of 10.0.0.1) +.Pp +Put the certificate (the file ending in .crt) in +.Pa /etc/isakmpd/certs/ +on your local system. +Also carry over the CA cert +.Pa /etc/ssl/ca.crt +and put it in +.Pa /etc/isakmpd/ca/ . +.El +.Pp +To revoke certificates, create a Certificate Revocation List (CRL) file +and install it in the +.Pa /etc/isakmpd/crls/ +directory. +See +.Xr openssl 1 +and the +.Sq crl +subcommand for more info. +.Pp +It is also possible to store trusted public keys to make them directly +usable by +.Nm isakmpd . +The keys should be saved in PEM format (see +.Xr openssl 1 ) +and named and stored after this easy formula: +.Bl -tag -width for_ufqdn_identities +.It For IPv4 identities +/etc/isakmpd/pubkeys/ipv4/A.B.C.D +.It For IPv6 identities +/etc/isakmpd/pubkeys/ipv6/abcd:abcd::ab:bc +.It For FQDN identities +/etc/isakmpd/pubkeys/fqdn/foo.bar.org +.It For UFQDN identities +/etc/isakmpd/pubkeys/ufqdn/user@foo.bar.org +.El +.Ss The FIFO user interface +When +.Nm +starts, it creates a FIFO (named pipe) where it listens for user +requests. +All commands start with a single letter, followed by command-specific options. +Available commands are: +.Bl -tag -width Ds -compact +.Pp +.It Ic "c <name>" +Start the named connection, if stopped or inactive. +.Pp +.It Ic "C set [section]:tag=value" +.It Ic "C set [section]:tag=value force" +.It Ic "C add [section]:tag=value" +.It Ic "C rm [section]:tag" +.It Ic "C rms [section]" +Update the running +.Nm +configuration atomically. +.Sq set +sets a configuration value consisting of a section, tag and value triplet. +.Sq set +will fail if the configuration already contains a section with the named tag; +use the +.Sq force +option to change this behaviour. +.Sq add +appends a configuration value to the named configuration list tag. +.Sq rm +removes a tag in a section. +.Sq rms +removes an entire section. +.Pp +NOTE: Sending isakmpd a SIGHUP or an "R" through the FIFO will +void any updates done to the configuration. +.Pp +.It Ic "C get [section]:tag" +Get the configuration value of the specified section and tag. +The result is stored in +.Pa /var/run/isakmpd.result . +.Pp +.It Ic "d <cookies> <msgid>" +Delete the specified SA from the system. +Specify <msgid> as "-" to match a Phase 1 SA. +.Pp +.It Ic "D <class> <level>" +.It Ic "D A <level>" +.It Ic "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 debug classes to level zero. +Another "D T" command will toggle them back to the earlier levels. +.Pp +.It Ic "p on[=<path>]" +.It Ic "p off" +Enable or disable cleartext IKE packet capture. +When enabling, optionally specify which file +.Nm +should capture the packets to. +.Pp +.It Ic "Q" +Cleanly shutdown the daemon, as when sent a +.Dv SIGTERM +signal. +.Pp +.It Ic "r" +Report +.Nm +internal state to a file. +See +.Fl R +option. +Same as when sent a +.Dv SIGUSR1 +signal. +.Pp +.It Ic "R" +Reinitialize +.Nm isakmpd , +as when sent a +.Dv SIGHUP +signal. +.Pp +.It Ic "S" +Report information on all known SAs to the +.Pa /var/run/isakmpd.result +file. +.Pp +.It Ic "t <name>" +Tear down the named connection, if active. +.Pp +.It Ic "T" +Tear down all active connections. +.El +.Sh FILES +.Bl -tag -width /etc/isakmpd/private/local. +.It Pa /etc/isakmpd/ca/ +The directory where CA certificates can be found. +.It Pa /etc/isakmpd/certs/ +The directory where IKE certificates can be found, both the local +certificate(s) and those of the peers, if a choice to have them kept +permanently has been made. +.It Pa /etc/isakmpd/crls/ +The directory where CRLs can be found. +.It Pa /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 +.Nm isakmpd . +.It Pa /etc/isakmpd/isakmpd.policy +The keynote policy configuration file. +The same mode requirements as +.Nm isakmpd.conf . +.It Pa /etc/isakmpd/private/local.key +A local private key for certificate based authentication. +There has to be a certificate for this key in the certificate directory +mentioned above. +The same mode requirements as +.Nm isakmpd.conf . +.It Pa /etc/isakmpd/pubkeys/ +Directory in which trusted public keys can be kept. +The keys must be named in the fashion described above. +.It Pa /var/run/isakmpd.pid +The PID of the current daemon. +.It Pa /var/run/isakmpd.fifo +The FIFO used to manually control +.Nm isakmpd . +.It Pa /var/run/isakmpd.pcap +The default IKE packet capture file. +.It Pa /var/run/isakmpd.report +The report file written when +.Dv SIGUSR1 +is received. +.It Pa /var/run/isakmpd.result +The report file written when the +.Sq S +or +.Sq "C get" +command is issued in the command FIFO. +.It Pa /usr/share/ipsec/isakmpd/ +A directory containing some sample +.Nm +and keynote policy configuration files. +.El +.Sh SEE ALSO +.Xr openssl 1 , +.Xr getnameinfo 3 , +.Xr pcap 3 , +.Xr ipsec 4 , +.Xr isakmpd.conf 5 , +.Xr isakmpd.policy 5 , +.Xr ssl 8 , +.Xr tcpdump 8 , +.Xr vpn 8 +.Sh HISTORY +The ISAKMP/Oakley key management protocol is described in the RFCs +.%T RFC 2407 , +.%T RFC 2408 +and +.%T RFC 2409 . +This implementation was done 1998 by Niklas Hallqvist and Niels Provos, +sponsored by Ericsson Radio Systems. +.Sh CAVEATS +When storing a trusted public key for an IPv6 identity, the +.Em most efficient +form of address representation, i.e "::" instead of ":0:0:0:", +must be used or the matching will fail. +.Nm +uses the output from +.Xr 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 +.Nm +listens on without a restart. +.Sh BUGS +The +.Fl P +flag does not do what we document, rather it does nothing. |