Fixed SEE ALSO references in main man pages.
[strongswan.git] / man / ipsec.secrets.5.in
1 .TH IPSEC.SECRETS 5 "2010-05-30" "@IPSEC_VERSION@" "strongSwan"
2 .SH NAME
3 ipsec.secrets \- secrets for IKE/IPsec authentication
4 .SH DESCRIPTION
5 The file \fIipsec.secrets\fP holds a table of secrets.
6 These secrets are used by the strongSwan Internet Key Exchange (IKE) daemons
7 pluto (IKEv1) and charon (IKEv2) to authenticate other hosts.
8 .LP
9 It is vital that these secrets be protected.  The file should be owned
10 by the super-user,
11 and its permissions should be set to block all access by others.
12 .LP
13 The file is a sequence of entries and include directives.
14 Here is an example.
15 .LP
16 .RS
17 .nf
18 # /etc/ipsec.secrets - strongSwan IPsec secrets file
19 192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
20
21 : RSA moonKey.pem
22
23 alice@strongswan.org : EAP "x3.dEhgN"
24
25 carol : XAUTH "4iChxLT3"
26
27 dave  : XAUTH "ryftzG4A"
28
29 # get secrets from other files
30 include ipsec.*.secrets
31 .fi
32 .RE
33 .LP
34 Each entry in the file is a list of optional ID selectors, followed by a secret.
35 The two parts are separated by a colon (\fB:\fP) that is surrounded
36 by whitespace. If no ID selectors are specified the line must start with a
37 colon.
38 .LP
39 A selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
40 \fB%any\fP or \fB%any6\fP (other kinds may come).  An IP address may be written
41 in the familiar dotted quad form or as a domain name to be looked up
42 when the file is loaded.
43 In many cases it is a bad idea to use domain names because
44 the name server may not be running or may be insecure.  To denote a
45 Fully Qualified Domain Name (as opposed to an IP address denoted by
46 its domain name), precede the name with an at sign (\fB@\fP).
47 .LP
48 Matching IDs with selectors is fairly straightforward: they have to be
49 equal.  In the case of a ``Road Warrior'' connection, if an equal
50 match is not found for the Peer's ID, and it is in the form of an IP
51 address, a selector of \fB%any\fP will match the peer's IP address if IPV4
52 and \fB%any6\fP will match a the peer's IP address if IPV6.
53 Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
54 \fB%any\fP.
55 .LP
56 In IKEv1 an additional complexity
57 arises in the case of authentication by preshared secret: the
58 responder will need to look up the secret before the Peer's ID payload has
59 been decoded, so the ID used will be the IP address.
60 .LP
61 To authenticate a connection between two hosts, the entry that most
62 specifically matches the host and peer IDs is used.  An entry with no
63 selectors will match any host and peer.  More specifically, an entry with one
64 selector will match a host and peer if the selector matches the host's ID (the
65 peer isn't considered).  Still more specifically, an entry with multiple
66 selectors will match a host and peer if the host ID and peer ID each match one
67 of the selectors.  If the key is for an asymmetric authentication technique
68 (i.e. a public key system such as RSA), an entry with multiple selectors will
69 match a host and peer even if only the host ID matches a selector (it is
70 presumed that the selectors are all identities of the host).
71 It is acceptable for two entries to be the best match as
72 long as they agree about the secret or private key.
73 .LP
74 Authentication by preshared secret requires that both systems find the
75 identical secret (the secret is not actually transmitted by the IKE
76 protocol).  If both the host and peer appear in the selector list, the
77 same entry will be suitable for both systems so verbatim copying
78 between systems can be used.  This naturally extends to larger groups
79 sharing the same secret.  Thus multiple-selector entries are best for PSK
80 authentication.
81 .LP
82 Authentication by public key systems such as RSA requires that each host
83 have its own private key.  A host could reasonably use a different private keys
84 for different interfaces and for different peers.  But it would not
85 be normal to share entries between systems.  Thus thus no-selector and
86 one-selector forms of entry often make sense for public key authentication.
87 .LP
88 The key part of an entry must start with a token indicating the kind of
89 key.  The following types of secrets are currently supported:
90 .TP
91 .B PSK
92 defines a pre-shared key
93 .TP
94 .B RSA
95 defines an RSA private key
96 .TP
97 .B ECDSA
98 defines an ECDSA private key
99 .TP
100 .B EAP
101 defines EAP credentials
102 .TP
103 .B XAUTH
104 defines XAUTH credentials
105 .TP
106 .B PIN
107 defines a smartcard PIN
108 .LP
109 Details on each type of secret are given below.
110 .LP
111 Whitespace at the end of a line is ignored. At the start of a line or
112 after whitespace, \fB#\fP and the following text up to the end of the
113 line is treated as a comment.
114 .LP
115 An include directive causes the contents of the named file to be processed
116 before continuing with the current file.  The filename is subject to
117 ``globbing'' as in \fIsh\fP(1), so every file with a matching name
118 is processed.  Includes may be nested to a modest
119 depth (10, currently).  If the filename doesn't start with a \fB/\fP, the
120 directory containing the current file is prepended to the name.  The
121 include directive is a line that starts with the word \fBinclude\fP,
122 followed by whitespace, followed by the filename (which must not contain
123 whitespace).
124 .SS TYPES OF SECRETS
125 .TP
126 .B [ <selectors> ] : PSK <secret>
127 A preshared secret is most conveniently represented as a sequence of
128 characters, delimited by double-quote characters (\fB"\fP).
129 The sequence cannot contain a newline or double-quote.
130 Strictly speaking, the secret is actually the sequence
131 of bytes that is used in the file to represent the sequence of
132 characters (excluding the delimiters).
133 .TP
134 .B [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ]
135 .TQ
136 .B [ <selectors> ] : ECDSA <private key file> [ <passphrase> | %prompt ]
137 For the private key file both absolute paths or paths relative to
138 \fI/etc/ipsec.d/private\fP are accepted. If the private key file is
139 encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
140 .B %prompt
141 can be used which then causes the daemons to ask the user for the password
142 whenever it is required to decrypt the key.
143 .TP
144 .B <user id> : EAP <secret>
145 As with \fBPSK\fP secrets the \fIsecret\fP is a sequence of characters,
146 delimited by double-quote characters (\fB"\fP).
147 .br
148 \fBEAP\fP secrets are IKEv2 only.
149 .TP
150 .B [ <servername> ] <username> : XAUTH <password>
151 \fBXAUTH\fP secrets are IKEv1 only.
152 .TP
153 .B : PIN <smartcard selector> <pin code> | %prompt
154 IKEv1 uses the format
155 .B "%smartcard[<slot nr>[:<key id>]]"
156 to specify the smartcard selector (e.g. %smartcard1:50).
157 The IKEv2 daemon supports multiple modules with the format
158 .B "%smartcard[<slot nr>[@<module>]]:<keyid>"
159 , but always requires a keyid to uniquely select the correct key. Instead of
160 specifying the pin code statically,
161 .B %prompt
162 can be specified, which causes the daemons to ask the user for the pin code.
163 .LP
164
165 .SH FILES
166 /etc/ipsec.secrets
167 .SH SEE ALSO
168 ipsec.conf(5), strongswan.conf(5), ipsec(8)
169 .br
170 .SH HISTORY
171 Originally written for the FreeS/WAN project by D. Hugh Redelmeier.
172 Updated and extended for the strongSwan project <http://www.strongswan.org> by
173 Tobias Brunner and Andreas Steffen.
174 .SH BUGS
175 If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
176 if it is \fB0::0\fP, it will match \fB%any6\fP.