Provided by:
openswan_2.4.12+dfsg-1.3_i386 
NAME
ipsec.secrets - secrets for IKE/IPsec authentication
DESCRIPTION
The file ipsec.secrets holds a table of secrets. These secrets are used
by ipsec_pluto(8), the Open Internet Key Exchange daemon, to
authenticate other hosts. Currently there are four kinds of secrets:
preshared secrets, RSA private keys, passwords/PIN codes for X.509
certificates and if compiled with USE_SMARTCARD=true, there is
additional support for storing the PINCODES of smartcards or USB tokens
It is vital that these secrets be protected. The file should be owned
by the super-user, and its permissions should be set to block all
access by others.
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"
# 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"
# 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
: RSA vpnserverKey.pem %prompt
# Entering a PIN code for a smartcard
: PIN %smartcard "12345678"
# For multiple smartcards use:
: PIN %smartcard<reader nr>:<PKCS#15 key id>"<PIN code>"
# or if you want to interactively type in the pin code
: PIN %smartcard %prompt
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 compatability 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
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 2any will match the peer’s IP address if IPV4 and 2any6 will match a the peer’s IP address if IPV6. Currently, the obsolete notation 0.0.0.0 may be used in place of 2any.
equal. In the case of a â
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 or smartcards protected by a passphrase or pin 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.
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. â
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 â
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
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).
subject to â
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/: ftp://ftp.isc.org/isc/bind/src/
HISTORY
Originally designed for the FreeS/WAN project <http://www.freeswan.org:
http://www.freeswan.org> by D. Hugh Redelmeier.
BUGS
If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
%any6.
IPSEC.SECRETS(5)