1IPSEC.SECRETS(5) Executable programs IPSEC.SECRETS(5)
2
6 ipsec.secrets - secrets for IKE/IPsec authentication
7
9 The file ipsec.secrets contains a list of secrets. Currently supported
10 secrets are preshared secrets (PSKs), RSA keys and XAUTH passwords.
11 These secrets are used by pluto(8) , the Libreswan Internet Key
12 Exchange daemon, to authenticate other hosts. There is another one type
13 of secret, post-quantum preshared keys (PPKs), that are used for
14 protecting traffic from quantum computer attack.
15 RSA private keys are stored in the NSS database. The secrets file only
17 contains a reference to these private RSA keys. For RSA keys belonging
18 to imported X.509 certificates, the certificate "friendly name" is
19 used. For raw RSA keys, the CKAID is used.
20 XAUTH passwords are stored in plaintext in this file. The secrets file
22 should be owned by root, and permissions should be set to block all
23 access by others. (eg: chmod 600)
24 The file is a sequence of entries and include directives. Here is an
26 example - each entry or directive must start at the left margin, but if
27 it continues beyond a single line, each continuation line must be
28 indented.
29 # sample /etc/ipsec.secrets file for 10.1.0.1
31 10.1.0.1 10.2.0.1 : PSK "secret shared by two hosts"
32 # sample roadwarrior
33 %any gateway.corp.com : PSK "shared secret with many roadwarriors"
34 # sample server for roadwarriors
35 myip %any : PSK "shared secret with many roadwarriors"
36 # an entry may be split across lines,
38 # but indentation matters
39 www.xs4all.nl @www.kremvax.ru
40 10.6.0.1 10.7.0.1 1.8.0.1 : PSK "secret shared by 5 systems"
41 # sample entry for static PPK
43 10.1.0.1 10.2.0.1 : PPKS "PPK_ID_1" "post-quantum preshared key for extra security"
44 # a raw RSA private key in NSS.
46 # note that the lines are too wide for a
47 # man page, so ... has been substituted for
48 # the truncated part
49 @my.com : RSA {
50 #ckaid: 0x316e6593...
51 #pubkey=0sAQPaGwWbUSK...
52 Modulus: 0x.....
53 PublicExponent: 0x03
54 }
55 # XAUTH password, used with leftxauthusername=username
57 @username : XAUTH "password"
58 include ipsec.*.secrets # get secrets from other files
60 Each entry in the file is a list of indices, followed by a secret. The
62 two parts are separated by a colon (:) that is followed by whitespace
63 or a newline.
64 An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
66 %any or %any6 (other kinds may come). An IP address may be written in
67 the familiar dotted quad form or as a domain name to be looked up when
68 the file is loaded. Be aware that using domain names requires DNS to be
69 functional before the IPsec tunnel comes up. To denote a Fully
70 Qualified Domain Name (as opposed to an IP address denoted by its
71 domain name), precede the name with an at sign (@).
72 Matching IDs with indices is fairly straightforward: they have to be
74 equal. In the case of a "Road Warrior" connection, if an equal match is
75 not found for the Peer's ID, and it is in the form of an IP address, an
76 index of %any will match the peer's IP address if IPV4 and %any6 will
77 match a the peer's IP address if IPV6.
78 This file is only read at startup time. If any changes are made to this
80 file, the pluto daemon should be told to re-read this file using the
81 command ipsec secrets or ipsec auto --rereadsecrets. Note that
82 currently there is no way to add a specific new entry - it's all or
83 nothing.
84 Smartcard support has been moved from Libreswan to NSS. Please see the
86 NSS documentation on how to configure smartcards.
87 An additional complexity arises in the case of authentication by
89 preshared secret in IKEv1 Main Mode: the responder will need to look up
90 the secret before the Peer's ID payload has been decoded, so the ID
91 used will be the IP address. IKEv1 Aggressive Mode (aggrmode=yes) can
92 be used to work around this, at the price of leaking the ID in the
93 clear and allowing a brute force attack against the PSK to be performed
94 offline. PSKs are the least secure authentication method and should be
95 avoided.
96 To authenticate a connection between two hosts, the entry that most
98 specifically matches the host and peer IDs is used. An entry with no
99 index will match any host and peer. More specifically, an entry with
100 one index will match a host and peer if the index matches the host's ID
101 (the peer isn't considered). Still more specifically, an entry with
102 multiple indices will match a host and peer if the host ID and peer ID
103 each match one of the indices. If the key is for an asymmetric
104 authentication technique (i.e. a public key system such as RSA), an
105 entry with multiple indices will match a host and peer even if only the
106 host ID matches an index (it is presumed that the multiple indices are
107 all identities of the host). It is acceptable for two entries to be the
108 best match as long as they agree about the secret or private key.
109 Authentication by preshared secret requires that both systems find the
111 identical secret (the secret is not actually transmitted by the IKE
112 protocol). If both the host and peer appear in the index list, the same
113 entry will be suitable for both systems so verbatim copying between
114 systems can be used. This naturally extends to larger groups sharing
115 the same secret. Thus multiple-index entries are best for PSK
116 authentication.
117 When running in FIPS mode, PSK's need to comply to a minimum strength
119 requirement depending on the integrity algorithm used. It is
120 recommended not to use PSK's shorter then 64 random characters.
121 Authentication by raw RSA Signatures requires that each host have its
123 own private key. A host could reasonably use a different private keys
124 for different interfaces and for different peers. But it would not be
125 normal to share entries between systems. Thus no-index and one-index
126 forms of entry often make sense for RSA Signature authentication.
127 The key part of an entry may start with a token indicating the kind of
129 key. "RSA" signifies RSA private key and "PSK" signifies PreShared Key
130 (case is ignored).
131 The token "XAUTH" indicates an IKEv1 eXtended Authentication password.
133 There should be one index, and it should be in the @FQDN format. The
134 file will be searched with the XAUTH username, which is usually
135 provided in the configuration file. XAUTH is otherwise identical to PSK
136 in syntax.
137 A preshared secret is most conveniently represented as a sequence of
139 characters, delimited by the double-quote character ("). The sequence
140 cannot contain a newline or double-quote. Strictly speaking, the secret
141 is actually the sequence of bytes that is used in the file to represent
142 the sequence of characters (excluding the delimiters). A preshared
143 secret may also be represented, without quotes, in any of supported
144 formats.
145 Currently supported formats are hexadecimal, base64, and characters.
147 A hexadecimal text value begins with a 0x (or 0X) prefix and continues
149 with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each
150 group encoding the value of one binary byte, high-order digit first. A
151 single _ (underscore) between consecutive groups is ignored, permitting
152 punctuation to improve readability; doing this every eight digits seems
153 about right.
154 A base64 text value begins with a 0s (or 0S) prefix and continues with
156 four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each
157 group encoding the value of three binary bytes as described in section
158 6.8 of RFC 2045. If flags has the TTODATAV_IGNORESPACE bit on, blanks
159 are ignore (after the prefix). Note that the last one or two digits of
160 a base64 group can be = to indicate that fewer than three binary bytes
161 are encoded.
162 A character text value begins with a 0t (or 0T) prefix and continues
164 with text characters, each being the value of one binary byte.
165 A raw RSA private key is a composite of eight generally large numbers.
167 The notation used is a brace-enclosed list of field name and value
168 pairs (see the example above). A suitable key, in a suitable format,
169 may be generated by ipsec_rsasigkey(8). The structure is very similar
170 to that used by BIND 8.2.2 or later, but note that the numbers must
171 have a "0s" prefix if they are in base 64. The order of the fields is
172 fixed. Note that most fields are now unused and filled in with the
173 CKAID, which is a reference to the location within the NSS database.
174 Post-quantum preshared keys (PPK) can be static. The token “PPKS”
176 indicates that the following key will be a PPK. The next token is a
177 PPK_ID that uniquely represents the given PPK. PPK_ID must be
178 represented as a sequence of characters delimited by the double-quote
179 character ("). The next token is a PPK itself. The static PPK may be
180 represented in any format that can be used for representing a preshared
181 secret. It is recommended that the static PPK be at least 256 bits in
182 order to provide real security against quantum computer attacks.
183 The first token of an entry must start in the first column of its line.
185 Subsequent tokens must be separated by whitespace, except for a colon
186 token, which only needs to be followed by whitespace. A newline is
187 taken as whitespace, but every line of an entry after the first must be
188 indented.
189 Whitespace at the end of a line is ignored (except in the 0t notation
191 for a key). At the start of line or after whitespace, # and the
192 following text up to the end of the line is treated as a comment.
193 Within entries, all lines must be indented (except for lines with no
194 tokens). Outside entries, no line may be indented (this is to make sure
195 that the file layout reflects its structure).
196 An include directive causes the contents of the named file to be
198 processed before continuing with the current file. The filename is
199 subject to "globbing" as in sh(1), so every file with a matching name
200 is processed. Includes may be nested to a modest depth (10, currently).
201 If the filename doesn't start with a /, the directory containing the
202 current file is prepended to the name. The include directive is a line
203 that starts with the word include, followed by whitespace, followed by
204 the filename (which must not contain whitespace).
205
207 /etc/ipsec.secrets
208
210 The rest of the Libreswan distribution, in particular ipsec.conf(5),
211 ipsec(8), ipsec_newhostkey(8), ipsec_rsasigkey(8),
212 ipsec_showhostkey(8), ipsec_auto(8)--rereadsecrets, and
213 pluto(8)--listen.
214
216 Originally designed for the FreeS/WAN project <http://www.freeswan.org>
217 by D. Hugh Redelmeier. Updated for Openswan by Ken Bantoft. Updated for
218 Libreswan by Paul Wouters
219 This file originally stored the private part of RSA keys. All private
221 key material is now stored in the NSS database. The fields of the raw
222 RSA key currently filled with the CKAID might be ignored and removed in
223 future versions.
224
226 If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
227 %any6.
228
230 Paul Wouters
231 libreswan secrets files
232libreswan 02/01/2019 IPSEC.SECRETS(5)