NAME¶
ipsec.secrets - secrets for IKE/IPsec authentication
DESCRIPTION¶
The file
ipsec.secrets holds a table of secrets. These secrets are used
by the strongSwan Internet Key Exchange (IKE) daemons pluto (IKEv1) and charon
(IKEv2) to authenticate other hosts.
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.
# /etc/ipsec.secrets - strongSwan IPsec secrets file
192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
: RSA moonKey.pem
alice@strongswan.org : EAP "x3.dEhgN"
carol : XAUTH "4iChxLT3"
dave : XAUTH "ryftzG4A"
# get secrets from other files
include ipsec.*.secrets
Each entry in the file is a list of optional ID selectors, followed by a secret.
The two parts are separated by a colon (
:) that is surrounded by
whitespace. If no ID selectors are specified the line must start with a colon.
A selector is an IP address, 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. 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 selectors 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, a selector 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.
In IKEv1 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 selectors will match
any host and peer. More specifically, an entry with one selector will match a
host and peer if the selector matches the host's ID (the peer isn't
considered). Still more specifically, an entry with multiple selectors will
match a host and peer if the host ID and peer ID each match one of the
selectors. If the key is for an asymmetric authentication technique (i.e. a
public key system such as RSA), an entry with multiple selectors will match a
host and peer even if only the host ID matches a selector (it is presumed that
the selectors 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 selector 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-selector entries are best for PSK authentication.
Authentication by public key systems such as RSA 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 thus no-selector and one-selector forms of
entry often make sense for public key authentication.
The key part of an entry must start with a token indicating the kind of key. The
following types of secrets are currently supported:
- PSK
- defines a pre-shared key
- RSA
- defines an RSA private key
- ECDSA
- defines an ECDSA private key
- EAP
- defines EAP credentials
- XAUTH
- defines XAUTH credentials
- PIN
- defines a smartcard PIN
Details on each type of secret are given below.
Whitespace at the end of a line is ignored. At the start of a line or after
whitespace,
# and the following text up to the end of the line is
treated as a comment.
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).
TYPES OF SECRETS¶
- [ <selectors> ] : PSK <secret>
- A preshared secret is most conveniently represented as a
sequence of characters, delimited by double-quote characters (
"). 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).
- [ <selectors> ] : RSA <private key file> [
<passphrase> | %prompt ]
- [ <selectors> ] : ECDSA <private key file> [
<passphrase> | %prompt ] For the private key file both absolute
paths or paths relative to /etc/ipsec.d/private are accepted. If
the private key file is encrypted, the passphrase must be defined.
Instead of a passphrase %prompt can be used which then causes the
daemons to ask the user for the password whenever it is required to
decrypt the key.
- <user id> : EAP <secret>
- As with PSK secrets the secret is a sequence
of characters, delimited by double-quote characters ( ").
EAP secrets are IKEv2 only.
- [ <servername> ] <username> : XAUTH
<password>
- XAUTH secrets are IKEv1 only.
- : PIN <smartcard selector> <pin code> |
%prompt
- IKEv1 uses the format %smartcard[<slot
nr>[:<key id>]] to specify the smartcard selector (e.g.
%smartcard1:50). The IKEv2 daemon supports multiple modules with the
format %smartcard[<slot nr>[@<module>]]:<keyid> ,
but always requires a keyid to uniquely select the correct key. Instead of
specifying the pin code statically, %prompt can be specified, which
causes the daemons to ask the user for the pin code.
FILES¶
/etc/ipsec.secrets
SEE ALSO¶
ipsec.conf(5),
strongswan.conf(5),
ipsec(8)
HISTORY¶
Originally written for the FreeS/WAN project by D. Hugh Redelmeier. Updated and
extended for the strongSwan project <
http://www.strongswan.org> by
Tobias Brunner and Andreas Steffen.
BUGS¶
If an ID is
0.0.0.0, it will match
%any; if it is
0::0, it
will match
%any6.