'\" t .\" Title: IPSEC.SECRETS .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 10/06/2010 .\" Manual: [FIXME: manual] .\" Source: [FIXME: source] .\" Language: English .\" .TH "IPSEC\&.SECRETS" "5" "10/06/2010" "[FIXME: source]" "[FIXME: manual]" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" ipsec.secrets \- secrets for IKE/IPsec authentication .SH "DESCRIPTION" .PP The file ipsec\&.secrets contains a list of secrets, aka preshared secrets, RSA signatures, or pointers to X\&.509 Digital Certificates\&. These secrets are used by \fBipsec_pluto\fR(8) , the Openswan Internet Key Exchange daemon, to authenticate other hosts\&. Currently there are five kinds of secrets: preshared secrets, RSA private keys, passphrases for X\&.509 certificates and if compiled with \fBUSE_XAUTH=true\fR there is support for XAUTH static passwords\&. Smartcard support has been moved to the NSS framework\&. .PP It is vital that these secrets be protected\&. The file should be owned by root, and permissions should be set to block all access by others\&. (eg: chmod 600) .PP The file is a sequence of entries and include directives\&. Here is an example \- each entry or directive must start at the left margin, but if it continues beyond a single line, each continuation line must be indented\&. .sp .if n \{\ .RS 4 .\} .nf # sample /etc/ipsec\&.secrets file for 10\&.1\&.0\&.1 10\&.1\&.0\&.1 10\&.2\&.0\&.1: PSK "secret shared by two hosts" # sample roadwarrior %any gateway\&.corp\&.com: PSK "shared secret with many roadwarriors" # sample server for roadwarriors myip %any : PSK "shared secret with many roadwarriors" # an entry may be split across lines, # but indentation matters www\&.xs4all\&.nl @www\&.kremvax\&.ru \ \&\ \&\ \&\ \&10\&.6\&.0\&.1 10\&.7\&.0\&.1 1\&.8\&.0\&.1: PSK "secret shared by 5 systems" # an RSA private key\&. # note that the lines are too wide for a # man page, so \&.\&.\&. has been substituted for # the truncated part @my\&.com: rsa { \ \&\ \&\ \&\ \&Modulus:\ \&0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt\&.\&.\&. \ \&\ \&\ \&\ \&PublicExponent:\ \&0sAw== \ \&\ \&\ \&\ \&PrivateExponent:\ \&0shlGbVR1m8Z+7rhzSyenCaBN\&.\&.\&. \ \&\ \&\ \&\ \&Prime1:\ \&0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l\&.\&.\&. \ \&\ \&\ \&\ \&Prime2:\ \&0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0\&.\&.\&. \ \&\ \&\ \&\ \&Exponent1:\ \&0soaXj85ihM5M2inVf/NfHmtLutVz4r\&.\&.\&. \ \&\ \&\ \&\ \&Exponent2:\ \&0sjdAL9VFizF+BKU4ohguJFzOd55OG6\&.\&.\&. \ \&\ \&\ \&\ \&Coefficient:\ \&0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ\&.\&.\&. \ \&\ \&\ \&\ \&} # An X\&.509 pem encoded private key file with (optional) passphrase : RSA vpnserverKey\&.pem "" # An X\&.509 pem encoded private key file locked with a passphrase # Note: the %prompt keyword means someone has to actually enter the passphrase # at load time \- usually via \fBipsec_whack\fR(8) : RSA vpnserverKey\&.pem %prompt # XAUTH password, used with leftxauthusername=username @username : XAUTH "password" include ipsec\&.*\&.secrets # get secrets from other files .fi .if n \{\ .RE .\} .sp Each entry in the file is a list of indices, followed by a secret\&. The two parts are separated by a colon (\fB:\fR) that is followed by whitespace or a newline\&. For compatibility with the previous form of this file, if the key part is just a double\-quoted string the colon may be left out\&. If filenames are not absolute paths, they are relative to the \fBipsec\&.d/private/\fR directory\&. .PP An index is an IP address, or a Fully Qualified Domain Name, user@FQDN, \fB%any\fR or \fB%any6\fR (other kinds may come)\&. An IP address may be written in the familiar dotted quad form or as a domain name to be looked up when the file is loaded (or in any of the forms supported by the Openswan \fBipsec_ttoaddr\fR(3) routine)\&. In many cases it is a bad idea to use domain names because the name server may not be running or may be insecure\&. To denote a Fully Qualified Domain Name (as opposed to an IP address denoted by its domain name), precede the name with an at sign (\fB@\fR)\&. .PP Matching IDs with indices is fairly straightforward: they have to be equal\&. In the case of a \(lqRoad Warrior\(rq connection, if an equal match is not found for the Peer\'s ID, and it is in the form of an IP address, an index of \fB%any\fR will match the peer\'s IP address if IPV4 and \fB%any6\fR will match a the peer\'s IP address if IPV6\&. Currently, the obsolete notation 0\&.0\&.0\&.0 may be used in place of \fB%any\fR, but please stop doing this, as it will likely stop working around Openswan v3\&.0\&. .PP This file is only read at startup time\&. If any changes are made to this file, the pluto daemon should be told to re\-read this file using the command \fBipsec secrets\fR or \fBipsec auto \-\-rereadsecrets\fR\&. If there are any keyfiles protected by a passphrase using \fB%prompt\fR, you will be prompted again to enter these passphrases\&. To skip the prompting, just hit return to skip unlocking that particular private key\&. Note that currently there is no way to add a specific new entry \- it\'s all or nothing\&. .PP Smartcard support has been moved from Openswan to NSS\&. Please see the NSS documentation on how to configure smartcards\&. .PP An additional complexity arises in the case of authentication by preshared secret: the responder will need to look up the secret before the Peer\'s ID payload has been decoded, so the ID used will be the IP address\&. .PP To authenticate a connection between two hosts, the entry that most specifically matches the host and peer IDs is used\&. An entry with no index will match any host and peer\&. More specifically, an entry with one index will match a host and peer if the index matches the host\'s ID (the peer isn\'t considered)\&. Still more specifically, an entry with multiple indices will match a host and peer if the host ID and peer ID each match one of the indices\&. If the key is for an asymmetric authentication technique (i\&.e\&. a public key system such as RSA), an entry with multiple indices will match a host and peer even if only the host ID matches an index (it is presumed that the multiple indices are all identities of the host)\&. It is acceptable for two entries to be the best match as long as they agree about the secret or private key\&. .PP Authentication by preshared secret requires that both systems find the identical secret (the secret is not actually transmitted by the IKE protocol)\&. If both the host and peer appear in the index list, the same entry will be suitable for both systems so verbatim copying between systems can be used\&. This naturally extends to larger groups sharing the same secret\&. Thus multiple\-index entries are best for PSK authentication\&. .PP Authentication by RSA Signatures requires that each host have its own private key\&. A host could reasonably use a different private keys for different interfaces and for different peers\&. But it would not be normal to share entries between systems\&. Thus no\-index and one\-index forms of entry often make sense for RSA Signature authentication\&. .PP The key part of an entry may start with a token indicating the kind of key\&. \(lqRSA\(rq signifies RSA private key and \(lqPSK\(rq signifies PreShared Key (case is ignored)\&. For compatibility with previous forms of this file, PSK is the default\&. .PP The token \(lqXAUTH\(rq indicates a eXtended Authentication password\&. There should be one indice, and it should be in the @FQDN format\&. The file will be searched with the XAUTH username, which is usually provided in the configuration file\&. XAUTH is otherwise identical to PSK in syntax\&. .PP If the RSA points to a filename, this is assumed to be a PEM (or DER?) encoded X\&.509 private key\&. The private key may be protected by a 3DES encryption\&. 1DES encrypted key files will be rejected\&. If the private key is protected by a passphrase and this passphrase is not specified in \fBipsec\&.secrets\fR, the connection cannot be automatically started using \fBauto=start\fR, but instead must be brought up using \fBipsec auto \-\-up connname\fR, upon which the user will be prompted for the passphrase to unlock the private key belonging to the X\&.509 certificate\&. PKCS#12 files, which include the private key file, cannot be specified in \fBipsec\&.secrets\fR\&. Private keys can be extracted from PKCS#12 files using the following command: \fBopenssl pkcs12 \-nocerts \-in clientCert\&.p12 \-out clientKey\&.pem\fR .PP A preshared secret is most conveniently represented as a sequence of characters, delimited by the double\-quote character (\fB"\fR)\&. The sequence cannot contain a newline or double\-quote\&. Strictly speaking, the secret is actually the sequence of bytes that is used in the file to represent the sequence of characters (excluding the delimiters)\&. A preshared secret may also be represented, without quotes, in any form supported by \fBipsec_ttodata\fR(3)\&. .PP An RSA private key is a composite of eight generally large numbers\&. The notation used is a brace\-enclosed list of field name and value pairs (see the example above)\&. A suitable key, in a suitable format, may be generated by \fBipsec_rsasigkey\fR(8)\&. The structure is very similar to that used by BIND 8\&.2\&.2 or later, but note that the numbers must have a \(lq0s\(rq prefix if they are in base 64\&. The order of the fields is fixed\&. .PP The first token an entry must start in the first column of its line\&. Subsequent tokens must be separated by whitespace, except for a colon token, which only needs to be followed by whitespace\&. A newline is taken as whitespace, but every line of an entry after the first must be indented\&. .PP Whitespace at the end of a line is ignored (except in the 0t notation for a key)\&. At the start of line or after whitespace, \fB#\fR and the following text up to the end of the line is treated as a comment\&. Within entries, all lines must be indented (except for lines with no tokens)\&. Outside entries, no line may be indented (this is to make sure that the file layout reflects its structure)\&. .PP An include directive causes the contents of the named file to be processed before continuing with the current file\&. The filename is subject to \(lqglobbing\(rq as in \fBsh\fR(1), so every file with a matching name is processed\&. Includes may be nested to a modest depth (10, currently)\&. If the filename doesn\'t start with a \fB/\fR, the directory containing the current file is prepended to the name\&. The include directive is a line that starts with the word \fBinclude\fR, followed by whitespace, followed by the filename (which must not contain whitespace)\&. .SH "FILES" .PP /etc/ipsec\&.secrets .SH "SEE ALSO" .PP The rest of the Openswan distribution, in particular \fBipsec.conf\fR(5), \fBipsec\fR(8), \fBipsec_newhostkey\fR(8), \fBipsec_rsasigkey\fR(8), \fBipsec_showhostkey\fR(8), \fBipsec_auto\fR(8) \fB\-\-rereadsecrets\fR, and \fBipsec_pluto\fR(8) \fB\-\-listen\fR,\&. BIND 8\&.2\&.2 or later, \m[blue]\fBftp://ftp\&.isc\&.org/isc/bind/src/\fR\m[] .SH "HISTORY" .PP Originally designed for the FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by D\&. Hugh Redelmeier\&. Updated for Openswan by Ken Bantoft\&. .SH "BUGS" .PP If an ID is 0\&.0\&.0\&.0, it will match \fB%any\fR; if it is \fB0::0\fR, it will match \fB%any6\fR\&.