]>
Commit | Line | Data |
---|---|---|
8250fc10 | 1 | .TH IPSEC.SECRETS 5 "2011-12-14" "@PACKAGE_VERSION@" "strongSwan" |
997358a6 MW |
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. | |
1d3a48b5 TB |
6 | These secrets are used by the strongSwan Internet Key Exchange (IKE) daemons |
7 | pluto (IKEv1) and charon (IKEv2) to authenticate other hosts. | |
997358a6 MW |
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. | |
1d3a48b5 | 14 | Here is an example. |
997358a6 MW |
15 | .LP |
16 | .RS | |
17 | .nf | |
1d3a48b5 TB |
18 | # /etc/ipsec.secrets - strongSwan IPsec secrets file |
19 | 192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL" | |
997358a6 | 20 | |
1d3a48b5 | 21 | : RSA moonKey.pem |
997358a6 | 22 | |
1d3a48b5 | 23 | alice@strongswan.org : EAP "x3.dEhgN" |
997358a6 | 24 | |
cb7a0cef | 25 | carol : XAUTH "4iChxLT3" |
1d3a48b5 | 26 | |
cb7a0cef | 27 | dave : XAUTH "ryftzG4A" |
1d3a48b5 TB |
28 | |
29 | # get secrets from other files | |
30 | include ipsec.*.secrets | |
997358a6 MW |
31 | .fi |
32 | .RE | |
33 | .LP | |
1d3a48b5 TB |
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. | |
997358a6 | 38 | .LP |
1d3a48b5 | 39 | A selector is an IP address, a Fully Qualified Domain Name, user@FQDN, |
3689f0f6 | 40 | \fB%any\fP or \fB%any6\fP (other kinds may come). |
997358a6 | 41 | .LP |
1d3a48b5 | 42 | Matching IDs with selectors is fairly straightforward: they have to be |
997358a6 MW |
43 | equal. In the case of a ``Road Warrior'' connection, if an equal |
44 | match is not found for the Peer's ID, and it is in the form of an IP | |
1d3a48b5 | 45 | address, a selector of \fB%any\fP will match the peer's IP address if IPV4 |
997358a6 MW |
46 | and \fB%any6\fP will match a the peer's IP address if IPV6. |
47 | Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of | |
48 | \fB%any\fP. | |
49 | .LP | |
1d3a48b5 | 50 | In IKEv1 an additional complexity |
997358a6 MW |
51 | arises in the case of authentication by preshared secret: the |
52 | responder will need to look up the secret before the Peer's ID payload has | |
53 | been decoded, so the ID used will be the IP address. | |
54 | .LP | |
55 | To authenticate a connection between two hosts, the entry that most | |
56 | specifically matches the host and peer IDs is used. An entry with no | |
1d3a48b5 TB |
57 | selectors will match any host and peer. More specifically, an entry with one |
58 | selector will match a host and peer if the selector matches the host's ID (the | |
59 | peer isn't considered). Still more specifically, an entry with multiple | |
60 | selectors will match a host and peer if the host ID and peer ID each match one | |
61 | of the selectors. If the key is for an asymmetric authentication technique | |
62 | (i.e. a public key system such as RSA), an entry with multiple selectors will | |
63 | match a host and peer even if only the host ID matches a selector (it is | |
64 | presumed that the selectors are all identities of the host). | |
997358a6 MW |
65 | It is acceptable for two entries to be the best match as |
66 | long as they agree about the secret or private key. | |
67 | .LP | |
68 | Authentication by preshared secret requires that both systems find the | |
69 | identical secret (the secret is not actually transmitted by the IKE | |
1d3a48b5 | 70 | protocol). If both the host and peer appear in the selector list, the |
997358a6 MW |
71 | same entry will be suitable for both systems so verbatim copying |
72 | between systems can be used. This naturally extends to larger groups | |
1d3a48b5 | 73 | sharing the same secret. Thus multiple-selector entries are best for PSK |
997358a6 MW |
74 | authentication. |
75 | .LP | |
1d3a48b5 TB |
76 | Authentication by public key systems such as RSA requires that each host |
77 | have its own private key. A host could reasonably use a different private keys | |
997358a6 | 78 | for different interfaces and for different peers. But it would not |
1d3a48b5 TB |
79 | be normal to share entries between systems. Thus thus no-selector and |
80 | one-selector forms of entry often make sense for public key authentication. | |
81 | .LP | |
82 | The key part of an entry must start with a token indicating the kind of | |
83 | key. The following types of secrets are currently supported: | |
84 | .TP | |
85 | .B PSK | |
86 | defines a pre-shared key | |
87 | .TP | |
88 | .B RSA | |
89 | defines an RSA private key | |
90 | .TP | |
91 | .B ECDSA | |
92 | defines an ECDSA private key | |
93 | .TP | |
7971278c TB |
94 | .B P12 |
95 | defines a PKCS#12 container | |
96 | .TP | |
1d3a48b5 TB |
97 | .B EAP |
98 | defines EAP credentials | |
99 | .TP | |
2380f3a8 TB |
100 | .B NTLM |
101 | defines NTLM credentials | |
102 | .TP | |
1d3a48b5 TB |
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 | |
997358a6 | 112 | after whitespace, \fB#\fP and the following text up to the end of the |
1d3a48b5 | 113 | line is treated as a comment. |
997358a6 MW |
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). | |
1d3a48b5 TB |
124 | .SS TYPES OF SECRETS |
125 | .TP | |
126 | .B [ <selectors> ] : PSK <secret> | |
6d4c6b8f TB |
127 | A preshared \fIsecret\fP is most conveniently represented as a sequence of |
128 | characters, which is delimited by double-quote characters (\fB"\fP). | |
129 | The sequence cannot contain newline or double-quote characters. | |
130 | .br | |
131 | Alternatively, preshared secrets can be represented as hexadecimal or Base64 | |
132 | encoded binary values. A character sequence beginning with | |
133 | .B 0x | |
134 | is interpreted as sequence of hexadecimal digits. | |
135 | Similarly, a character sequence beginning with | |
136 | .B 0s | |
137 | is interpreted as Base64 encoded binary data. | |
1d3a48b5 | 138 | .TP |
7971278c | 139 | .B : RSA <private key file> [ <passphrase> | %prompt ] |
1d3a48b5 | 140 | .TQ |
7971278c | 141 | .B : ECDSA <private key file> [ <passphrase> | %prompt ] |
1d3a48b5 TB |
142 | For the private key file both absolute paths or paths relative to |
143 | \fI/etc/ipsec.d/private\fP are accepted. If the private key file is | |
144 | encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase | |
145 | .B %prompt | |
7971278c | 146 | can be used which then causes the daemon to ask the user for the password |
1d3a48b5 TB |
147 | whenever it is required to decrypt the key. |
148 | .TP | |
7971278c TB |
149 | .B : P12 <PKCS#12 file> [ <passphrase> | %prompt ] |
150 | For the PKCS#12 file both absolute paths or paths relative to | |
151 | \fI/etc/ipsec.d/private\fP are accepted. If the container is | |
152 | encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase | |
153 | .B %prompt | |
154 | can be used which then causes the daemon to ask the user for the password | |
155 | whenever it is required to decrypt the container. Private keys, client and CA | |
156 | certificates are extracted from the container. To use such a client certificate | |
157 | in a connection set leftid to one of the subjects of the certificate. | |
158 | .TP | |
1d3a48b5 | 159 | .B <user id> : EAP <secret> |
6d4c6b8f | 160 | The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets. |
1d3a48b5 TB |
161 | .br |
162 | \fBEAP\fP secrets are IKEv2 only. | |
163 | .TP | |
2380f3a8 TB |
164 | .B <user id> : NTLM <secret> |
165 | The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets, but the | |
166 | secret is stored as NTLM hash, which is MD4(UTF-16LE(secret)), instead of as | |
167 | cleartext. | |
168 | .br | |
169 | \fBNTLM\fP secrets can only be used with the \fBeap-mschapv2\fP plugin. | |
170 | .TP | |
cb7a0cef | 171 | .B [ <servername> ] <username> : XAUTH <password> |
6d4c6b8f | 172 | The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets. |
1d3a48b5 TB |
173 | \fBXAUTH\fP secrets are IKEv1 only. |
174 | .TP | |
cd844e1c MW |
175 | .B : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt |
176 | The smartcard selector always requires a keyid to uniquely select the correct | |
177 | key. The slot number defines the slot on the token, the module name refers to | |
178 | the module name defined in strongswan.conf(5). | |
179 | Instead of specifying the pin code statically, | |
1d3a48b5 | 180 | .B %prompt |
7971278c | 181 | can be specified, which causes the daemon to ask the user for the pin code. |
1d3a48b5 TB |
182 | .LP |
183 | ||
997358a6 MW |
184 | .SH FILES |
185 | /etc/ipsec.secrets | |
186 | .SH SEE ALSO | |
8207a742 | 187 | ipsec.conf(5), strongswan.conf(5), ipsec(8) |
997358a6 | 188 | .br |
997358a6 | 189 | .SH HISTORY |
1d3a48b5 TB |
190 | Originally written for the FreeS/WAN project by D. Hugh Redelmeier. |
191 | Updated and extended for the strongSwan project <http://www.strongswan.org> by | |
192 | Tobias Brunner and Andreas Steffen. | |
997358a6 MW |
193 | .SH BUGS |
194 | If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP; | |
195 | if it is \fB0::0\fP, it will match \fB%any6\fP. |