NAME¶
ipsec.secrets - secrets for IKE/IPsec authentication
DESCRIPTION¶
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
ipsec_pluto(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
USE_XAUTH=true there is support for XAUTH static passwords.
Smartcard support has been moved to the NSS framework.
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)
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.
# 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 "<optional passphrase>"
# 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 ipsec_whack(8)
: RSA vpnserverKey.pem %prompt
# XAUTH password, used with leftxauthusername=username
@username : XAUTH "password"
include ipsec.*.secrets # get secrets from other files
Each entry in the file is a list of indices, followed by a secret. The two parts
are separated by a colon (
:) 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
ipsec.d/private/
directory.
An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
%any or
%any6 (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
ipsec_ttoaddr(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 (
@).
Matching IDs with indices is fairly straightforward: they have to be equal. In
the case of a “Road Warrior” 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
%any will match the peer´s IP address if IPV4 and
%any6
will match a the peer´s IP address if IPV6. Currently, the obsolete
notation 0.0.0.0 may be used in place of
%any, but please stop doing
this, as it will likely stop working around Openswan v3.0.
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
ipsec secrets or
ipsec auto --rereadsecrets. If there are any
keyfiles protected by a passphrase using
%prompt, 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.
Smartcard support has been moved from Openswan to NSS. Please see the NSS
documentation on how to configure smartcards.
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.
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.
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.
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.
The key part of an entry may start with a token indicating the kind of key.
“RSA” signifies RSA private key and “PSK” signifies
PreShared Key (case is ignored). For compatibility with previous forms of this
file, PSK is the default.
The token “XAUTH” 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.
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
ipsec.secrets, the
connection cannot be automatically started using
auto=start, but
instead must be brought up using
ipsec auto --up connname, 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
ipsec.secrets. Private keys can be
extracted from PKCS#12 files using the following command:
openssl pkcs12
-nocerts -in clientCert.p12 -out clientKey.pem
A preshared secret is most conveniently represented as a sequence of characters,
delimited by the double-quote character (
"). 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
ipsec_ttodata(3).
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
ipsec_rsasigkey(8). The structure is very similar to that used by BIND
8.2.2 or later, but note that the numbers must have a “0s” prefix
if they are in base 64. The order of the fields is fixed.
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.
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,
# 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).
An include directive causes the contents of the named file to be processed
before continuing with the current file. The filename is subject to
“globbing” as in
sh(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
/, the directory containing the
current file is prepended to the name. The include directive is a line that
starts with the word
include, followed by whitespace, followed by the
filename (which must not contain whitespace).
FILES¶
/etc/ipsec.secrets
SEE ALSO¶
The rest of the Openswan distribution, in particular
ipsec.conf(5),
ipsec(8),
ipsec_newhostkey(8),
ipsec_rsasigkey(8),
ipsec_showhostkey(8),
ipsec_auto(8) --rereadsecrets, and
ipsec_pluto(8) --listen,. BIND 8.2.2 or later,
ftp://ftp.isc.org/isc/bind/src/
HISTORY¶
Originally designed for the FreeS/WAN project <
http://www.freeswan.org> by D. Hugh Redelmeier. Updated for Openswan
by Ken Bantoft.
BUGS¶
If an ID is 0.0.0.0, it will match
%any; if it is
0::0, it will
match
%any6.