Merge branch 'ah'
[strongswan.git] / man / ipsec.secrets.5.in
index 5292a90..15e36fa 100644 (file)
@@ -1,4 +1,4 @@
-.TH IPSEC.SECRETS 5 "2010-05-30" "@IPSEC_VERSION@" "strongSwan"
+.TH IPSEC.SECRETS 5 "2011-12-14" "@PACKAGE_VERSION@" "strongSwan"
 .SH NAME
 ipsec.secrets \- secrets for IKE/IPsec authentication
 .SH DESCRIPTION
@@ -37,13 +37,7 @@ 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).
+\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
@@ -97,9 +91,15 @@ defines an RSA private key
 .B ECDSA
 defines an ECDSA private key
 .TP
+.B P12
+defines a PKCS#12 container
+.TP
 .B EAP
 defines EAP credentials
 .TP
+.B NTLM
+defines NTLM credentials
+.TP
 .B XAUTH
 defines XAUTH credentials
 .TP
@@ -124,49 +124,67 @@ 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).
+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 ]
+.B : RSA <private key file> [ <passphrase> | %prompt ]
 .TQ
-.B [ <selectors> ] : ECDSA <private key file> [ <passphrase> | %prompt ]
+.B : 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
+can be used which then causes the daemon to ask the user for the password
 whenever it is required to decrypt the key.
 .TP
+.B : P12 <PKCS#12 file> [ <passphrase> | %prompt ]
+For the PKCS#12 file both absolute paths or paths relative to
+\fI/etc/ipsec.d/private\fP are accepted. If the container is
+encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
+.B %prompt
+can be used which then causes the daemon to ask the user for the password
+whenever it is required to decrypt the container. Private keys, client and CA
+certificates are extracted from the container. To use such a client certificate
+in a connection set leftid to one of the subjects of the certificate.
+.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).
+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 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 : 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.
+can be specified, which causes the daemon to ask the user for the pin code.
 .LP
 
 .SH FILES
 /etc/ipsec.secrets
 .SH SEE ALSO
-\fIipsec.conf\fP(5),
-\fIipsec\fP(8)
+ipsec.conf(5), strongswan.conf(5), ipsec(8)
 .br
 .SH HISTORY
 Originally written for the FreeS/WAN project by D. Hugh Redelmeier.