[svn-upgrade] new version strongswan (4.5.0)

1 files changed, 176 insertions, 0 deletions

diff --git a/man/ipsec.secrets.5.in b/man/ipsec.secrets.5.in
new file mode 100644
index 000000000..875b8e219
--- /dev/null
+++ b/man/ipsec.secrets.5.in
@@ -0,0 +1,176 @@
+.TH IPSEC.SECRETS 5 "2010-05-30" "@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).  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 (\fB@\fP).
+.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 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 secret is most conveniently represented as a sequence of
+characters, delimited by double-quote characters (\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).
+.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>
+As with \fBPSK\fP secrets the \fIsecret\fP is a sequence of characters,
+delimited by double-quote characters (\fB"\fP).
+.br
+\fBEAP\fP secrets are IKEv2 only.
+.TP
+.B [ <servername> ] <username> : XAUTH <password>
+\fBXAUTH\fP secrets are IKEv1 only.
+.TP
+.B : PIN <smartcard selector> <pin code> | %prompt
+IKEv1 uses the format
+.B "%smartcard[<slot nr>[:<key id>]]"
+to specify the smartcard selector (e.g. %smartcard1:50).
+The IKEv2 daemon supports multiple modules with the format
+.B "%smartcard[<slot nr>[@<module>]]:<keyid>"
+, but always requires a keyid to uniquely select the correct key. 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.