1IPSEC.SECRETS(5) IPSEC.SECRETS(5)
2
6 ipsec.secrets - secrets for IKE/IPsec authentication
7
9 The file ipsec.secrets holds a table of secrets. These secrets are used
10 by ipsec_pluto(8), the Open Internet Key Exchange daemon, to authenti‐
11 cate other hosts. Currently there are four kinds of secrets: preshared
12 secrets, RSA private keys, passwords/PIN codes for X.509 certificates
13 and if compiled with USE_SMARTCARD=true, there is additional support
14 for storing the PINCODES of smartcards or USB tokens
15 It is vital that these secrets be protected. The file should be owned
18 by the super-user, and its permissions should be set to block all
19 access by others.
20 The file is a sequence of entries and include directives. Here is an
23 example. Each entry or directive must start at the left margin, but if
24 it continues beyond a single line, each continuation line must be
25 indented.
26 # sample /etc/ipsec.secrets file for 10.1.0.1
29 10.1.0.1 10.2.0.1: PSK "secret shared by two hosts"
30 # an entry may be split across lines,
32 # but indentation matters
33 www.xs4all.nl @www.kremvax.ru
34 10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5"
35 # an RSA private key.
37 # note that the lines are too wide for a
38 # man page, so ... has been substituted for
39 # the truncated part
40 @my.com: rsa {
41 Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt...
42 PublicExponent: 0sAw==
43 PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN...
44 Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l...
45 Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0...
46 Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r...
47 Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6...
48 Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ...
49 }
50 # An X.509 pem encoded private key file with (optional) passphrase
52 : RSA vpnserverKey.pem "<optional passphrase>"
53 # An X.509 pem encoded private key file locked with a passphrase
54 : RSA vpnserverKey.pem %prompt
55 # Entering a PIN code for a smartcard
57 : PIN %smartcard "12345678"
58 # For multiple smartcards use:
59 : PIN %smartcard<reader nr>:<PKCS#15 key id>"<PIN code>"
60 # or if you want to interactively type in the pin code
61 : PIN %smartcard %prompt
62 include ipsec.*.secrets # get secrets from other files
64 Each entry in the file is a list of indices, followed by a secret.
66 The two parts are separated by a colon (:) that is followed by white‐
67 space or a newline. For compatability with the previous form of this
68 file, if the key part is just a double-quoted string the colon may be
69 left out. If filenames are not absolute paths, they are relative to the
70 ipsec.d/private/ directory.
71 An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
74 %any or %any6 (other kinds may come). An IP address may be written in
75 the familiar dotted quad form or as a domain name to be looked up when
76 the file is loaded (or in any of the forms supported by the Openswan
77 ipsec_ttoaddr(3) routine). In many cases it is a bad idea to use domain
78 names because the name server may not be running or may be insecure. To
79 denote a Fully Qualified Domain Name (as opposed to an IP address
80 denoted by its domain name), precede the name with an at sign (@).
81 Matching IDs with indices is fairly straightforward: they have to be
84 equal. In the case of a “Road Warrior” connection, if an equal match is
85 not found for the Peer's ID, and it is in the form of an IP address, an
86 index of %any will match the peer's IP address if IPV4 and %any6 will
87 match a the peer's IP address if IPV6. Currently, the obsolete notation
88 0.0.0.0 may be used in place of %any.
89 This file is only read at startup time. If any changes are made to this
92 file, the pluto daemon should be told to re-read this file using the
93 command ipsec secrets or ipsec auto --rereadsecrets. If there are any
94 keyfiles or smartcards protected by a passphrase or pin using %prompt,
95 you will be prompted again to enter these passphrases. To skip the
96 prompting, just hit return to skip unlocking that particular private
97 key.
98 An additional complexity arises in the case of authentication by pre‐
101 shared secret: the responder will need to look up the secret before the
102 Peer's ID payload has been decoded, so the ID used will be the IP
103 address.
104 To authenticate a connection between two hosts, the entry that most
107 specifically matches the host and peer IDs is used. An entry with no
108 index will match any host and peer. More specifically, an entry with
109 one index will match a host and peer if the index matches the host's ID
110 (the peer isn't considered). Still more specifically, an entry with
111 multiple indices will match a host and peer if the host ID and peer ID
112 each match one of the indices. If the key is for an asymmetric authen‐
113 tication technique (i.e. a public key system such as RSA), an entry
114 with multiple indices will match a host and peer even if only the host
115 ID matches an index (it is presumed that the multiple indices are all
116 identities of the host). It is acceptable for two entries to be the
117 best match as long as they agree about the secret or private key.
118 Authentication by preshared secret requires that both systems find the
121 identical secret (the secret is not actually transmitted by the IKE
122 protocol). If both the host and peer appear in the index list, the same
123 entry will be suitable for both systems so verbatim copying between
124 systems can be used. This naturally extends to larger groups sharing
125 the same secret. Thus multiple-index entries are best for PSK authenti‐
126 cation.
127 Authentication by RSA Signatures requires that each host have its own
130 private key. A host could reasonably use a different private keys for
131 different interfaces and for different peers. But it would not be nor‐
132 mal to share entries between systems. Thus no-index and one-index forms
133 of entry often make sense for RSA Signature authentication.
134 The key part of an entry may start with a token indicating the kind of
137 key. “RSA” signifies RSA private key and “PSK” signifies PreShared Key
138 (case is ignored). For compatability with previous forms of this file,
139 PSK is the default.
140 If the RSA points to a filename, this is assumed to be a PEM (or DER?)
143 encoded X.509 private key. The private key may be protected by a 3DES
144 encryption. 1DES encrypted key files will be rejected. If the private
145 key is protected by a passphrase and this passphrase is not specified
146 in ipsec.secrets, the connection cannot be automatically started using
147 auto=start, but instead must be brought up using ipsec auto --up
148 connname, upon which the user will be prompted for the passphrase to
149 unlock the private key belonging to the X.509 certificate. PKCS#12
150 files, which include the private key file, cannot be specified in
151 ipsec.secrets. Private keys can be extracted from PKCS#12 files using
152 the following command: openssl pkcs12 -nocerts -in clientCert.p12 -out
153 clientKey.pem
154 A preshared secret is most conveniently represented as a sequence of
157 characters, delimited by the double-quote character ("). The sequence
158 cannot contain a newline or double-quote. Strictly speaking, the secret
159 is actually the sequence of bytes that is used in the file to represent
160 the sequence of characters (excluding the delimiters). A preshared
161 secret may also be represented, without quotes, in any form supported
162 by ipsec_ttodata(3).
163 An RSA private key is a composite of eight generally large numbers. The
166 notation used is a brace-enclosed list of field name and value pairs
167 (see the example above). A suitable key, in a suitable format, may be
168 generated by ipsec_rsasigkey(8). The structure is very similar to that
169 used by BIND 8.2.2 or later, but note that the numbers must have a “0s”
170 prefix if they are in base 64. The order of the fields is fixed.
171 The first token an entry must start in the first column of its line.
174 Subsequent tokens must be separated by whitespace, except for a colon
175 token, which only needs to be followed by whitespace. A newline is
176 taken as whitespace, but every line of an entry after the first must be
177 indented.
178 Whitespace at the end of a line is ignored (except in the 0t notation
181 for a key). At the start of line or after whitespace, # and the follow‐
182 ing text up to the end of the line is treated as a comment. Within
183 entries, all lines must be indented (except for lines with no tokens).
184 Outside entries, no line may be indented (this is to make sure that the
185 file layout reflects its structure).
186 An include directive causes the contents of the named file to be pro‐
189 cessed before continuing with the current file. The filename is subject
190 to “globbing” as in sh(1), so every file with a matching name is pro‐
191 cessed. Includes may be nested to a modest depth (10, currently). If
192 the filename doesn't start with a /, the directory containing the cur‐
193 rent file is prepended to the name. The include directive is a line
194 that starts with the word include, followed by whitespace, followed by
195 the filename (which must not contain whitespace).
196
199 /etc/ipsec.secrets
200
203 The rest of the Openswan distribution, in particular ipsec.conf(5),
204 ipsec(8), ipsec_newhostkey(8), ipsec_rsasigkey(8),
205 ipsec_showhostkey(8), ipsec_auto(8) --rereadsecrets, and
206 ipsec_pluto(8) --listen,. BIND 8.2.2 or later,
207 ftp://ftp.isc.org/isc/bind/src/: ftp://ftp.isc.org/isc/bind/src/
208
211 Originally designed for the FreeS/WAN project <http://www.freeswan.org:
212 http://www.freeswan.org> by D. Hugh Redelmeier.
213
216 If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
217 %any6.
218 IPSEC.SECRETS(5)