Currently there are two kinds of secrets: preshared secrets and
.\" the private part of DSS keys.
RSA private keys.
.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.  Each entry or directive must start at the
left margin, but if it continues beyond a single line, each continuation
line must be indented.
.LP
.RS
.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"

# 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"

.\" # Private part of our DSS key, in base 64,
.\" # as generated by BIND 8.2.1's dnskeygen.
.\" # Since this is the default key for this host,
.\" # there is no need to specify indices.
.\" : DSS 0siMs0N/hfRoCBMXA6plPtuv58/+c=
# 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...
\ \ \ \ }

include ipsec.*.secrets	# get secrets from other files
.fi
.RE
.LP
Each entry in the file is a list of indices, followed by a secret.
The two parts are separated by a colon (\fB:\fP) 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.
address, an index 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
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
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.
.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 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.
.LP
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 thus no-index and
one-index forms of entry often make sense for RSA Signature authentication.
.LP
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 compatability with previous
forms of this file, PSK is the default.
.LP
A preshared secret is most conveniently represented as a sequence of
characters, delimited by the double-quote
character (\fB"\fP).  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
\fIipsec_ttodata\fP(3).
.LP
An RSA private key is a composite of eight generally large numbers.  The notation
notation for a key).  At the start of line or
after whitespace, \fB#\fP 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).
.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).
.SH FILES
/etc/ipsec.secrets
.SH SEE ALSO
The rest of the Openswan distribution, in particular
\fIipsec.conf\fP(5),
\fIipsec\fP(8),
\fIipsec_newhostkey\fP(8),
\fIipsec_rsasigkey\fP(8),
\fIipsec_showhostkey\fP(8),
\fIipsec_auto\fP(8) \fB\-\-rereadsecrets\fP,
and \fIipsec_pluto\fP(8) \fB\-\-listen\fP,.
.br
BIND 8.2.2 or later, ftp://ftp.isc.org/isc/bind/src/
.SH HISTORY
Originally designed for the FreeS/WAN project



Man(1) output converted with
man2html