1 files changed, 175 insertions, 0 deletions

diff --git a/src/pluto/ipsec.secrets.5 b/src/pluto/ipsec.secrets.5
new file mode 100644
index 000000000..3cce4d3f8
--- /dev/null
+++ b/src/pluto/ipsec.secrets.5
@@ -0,0 +1,175 @@
+.TH IPSEC.SECRETS 5 "28 March 1999"
+.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 \fIipsec_pluto\fP(8), the FreeS/WAN Internet Key
+Exchange daemon, to authenticate other hosts.
+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.
+.LP
+An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
+\fB%any\fP or \fB%any6\fP (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 FreeS/WAN \fIipsec_ttoaddr\fP(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 (\fB@\fP).
+.LP
+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 \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
+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 \fIipsec_rsasigkey\fP(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.
+.LP
+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.
+.LP
+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, \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 FreeS/WAN 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
+Designed for the FreeS/WAN project
+<http://www.freeswan.org>
+by D. Hugh Redelmeier.
+.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.