Merge branch 'silent-automake'

[thirdparty/strongswan.git] / man / ipsec.secrets.5.in

.TH IPSEC.SECRETS 5 "2011-12-14" "@IPSEC_VERSION@" "strongSwan"
.SH NAME
ipsec.secrets \- secrets for IKE/IPsec authentication
.SH DESCRIPTION
The file \fIipsec.secrets\fP 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.
.LP
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.
.LP
The file is a sequence of entries and include directives.
Here is an example.
.LP
.RS
.nf
# /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
.fi
.RE
.LP
Each entry in the file is a list of optional ID selectors, followed by a secret.
The two parts are separated by a colon (\fB:\fP) that is surrounded
by whitespace. If no ID selectors are specified the line must start with a
colon.
.LP
A selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
\fB%any\fP or \fB%any6\fP (other kinds may come).
.LP
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 \fB%any\fP will match the peer's IP address if IPV4
and \fB%any6\fP will match a the peer's IP address if IPV6.
Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
\fB%any\fP.
.LP
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.
.LP
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.
.LP
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.
.LP
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.
.LP
The key part of an entry must start with a token indicating the kind of
key.  The following types of secrets are currently supported:
.TP
.B PSK
defines a pre-shared key
.TP
.B RSA
defines an RSA private key
.TP
.B ECDSA
defines an ECDSA private key
.TP
.B EAP
defines EAP credentials
.TP
.B NTLM
defines NTLM credentials
.TP
.B XAUTH
defines XAUTH credentials
.TP
.B PIN
defines a smartcard PIN
.LP
Details on each type of secret are given below.
.LP
Whitespace at the end of a line is ignored. At the start of a line or
after whitespace, \fB#\fP and the following text up to the end of the
line is treated as a comment.
.LP
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 \fIsh\fP(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/\fP, the
directory containing the current file is prepended to the name.  The
include directive is a line that starts with the word \fBinclude\fP,
followed by whitespace, followed by the filename (which must not contain
whitespace).
.SS TYPES OF SECRETS
.TP
.B [ <selectors> ] : PSK <secret>
A preshared \fIsecret\fP is most conveniently represented as a sequence of
characters, which is delimited by double-quote characters (\fB"\fP).
The sequence cannot contain newline or double-quote characters.
.br
Alternatively, preshared secrets can be represented as hexadecimal or Base64
encoded binary values. A character sequence beginning with
.B 0x
is interpreted as sequence of hexadecimal digits.
Similarly, a character sequence beginning with
.B 0s
is interpreted as Base64 encoded binary data.
.TP
.B [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ]
.TQ
.B [ <selectors> ] : ECDSA <private key file> [ <passphrase> | %prompt ]
For the private key file both absolute paths or paths relative to
\fI/etc/ipsec.d/private\fP are accepted. If the private key file is
encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
.B %prompt
can be used which then causes the daemons to ask the user for the password
whenever it is required to decrypt the key.
.TP
.B <user id> : EAP <secret>
The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets.
.br
\fBEAP\fP secrets are IKEv2 only.
.TP
.B <user id> : NTLM <secret>
The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets, but the
secret is stored as NTLM hash, which is MD4(UTF-16LE(secret)), instead of as
cleartext.
.br
\fBNTLM\fP secrets can only be used with the \fBeap-mschapv2\fP plugin.
.TP
.B [ <servername> ] <username> : XAUTH <password>
The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets.
\fBXAUTH\fP secrets are IKEv1 only.
.TP
.B : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt
The smartcard selector always requires a keyid to uniquely select the correct
key. The slot number defines the slot on the token, the module name refers to
the module name defined in strongswan.conf(5).
Instead of specifying the pin code statically,
.B %prompt
can be specified, which causes the daemons to ask the user for the pin code.
.LP

.SH FILES
/etc/ipsec.secrets
.SH SEE ALSO
ipsec.conf(5), strongswan.conf(5), ipsec(8)
.br
.SH 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.
.SH BUGS
If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
if it is \fB0::0\fP, it will match \fB%any6\fP.