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
63 two parts are separated by a colon (:) that is followed by whitespace
64 or a newline.
65 An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
67 %any or %any6 (other kinds may come). An IP address may be written in
68 the familiar dotted quad form or as a domain name to be looked up when
69 the file is loaded. Be aware that using domain names requires DNS to be
70 functional before the IPsec tunnel comes up. To denote a Fully
71 Qualified Domain Name (as opposed to an IP address denoted by its
72 domain name), precede the name with an at sign (@).
73 Matching IDs with indices is fairly straightforward: they have to be
75 equal. In the case of a "Road Warrior" connection, if an equal match is
76 not found for the Peer's ID, and it is in the form of an IP address, an
77 index of %any will match the peer's IP address if IPV4 and %any6 will
78 match a the peer's IP address if IPV6.
79 This file is only read at startup time. If any changes are made to this
81 file, the pluto daemon should be told to re-read this file using the
82 command ipsec secrets or ipsec auto --rereadsecrets. Note that
83 currently there is no way to add a specific new entry - it's all or
84 nothing.
85 Smartcard support has been moved from Libreswan to NSS. Please see the
87 NSS documentation on how to configure smartcards.
88 An additional complexity arises in the case of authentication by
90 preshared secret in IKEv1 Main Mode: the responder will need to look up
91 the secret before the Peer's ID payload has been decoded, so the ID
92 used will be the IP address. IKEv1 Aggressive Mode (aggrmode=yes) can
93 be used to work around this, at the price of leaking the ID in the
94 clear and allowing a brute force attack against the PSK to be performed
95 offline. PSKs are the least secure authentication method and should be
96 avoided.
97 To authenticate a connection between two hosts, the entry that most
99 specifically matches the host and peer IDs is used. An entry with no
100 index will match any host and peer. More specifically, an entry with
101 one index will match a host and peer if the index matches the host's ID
102 (the peer isn't considered). Still more specifically, an entry with
103 multiple indices will match a host and peer if the host ID and peer ID
104 each match one of the indices. If the key is for an asymmetric
105 authentication technique (i.e. a public key system such as RSA), an
106 entry with multiple indices will match a host and peer even if only the
107 host ID matches an index (it is presumed that the multiple indices are
108 all identities of the host). It is acceptable for two entries to be the
109 best match as long as they agree about the secret or private key.
110 Authentication by preshared secret requires that both systems find the
112 identical secret (the secret is not actually transmitted by the IKE
113 protocol). If both the host and peer appear in the index list, the same
114 entry will be suitable for both systems so verbatim copying between
115 systems can be used. This naturally extends to larger groups sharing
116 the same secret. Thus multiple-index entries are best for PSK
117 authentication.
118 When running in FIPS mode, PSK's need to comply to a minimum strength
120 requirement depending on the integrity algorithm used. It is
121 recommended not to use PSK's shorter then 64 random characters.
122 Authentication by raw RSA Signatures requires that each host have its
124 own private key. A host could reasonably use a different private keys
125 for different interfaces and for different peers. But it would not be
126 normal to share entries between systems. Thus no-index and one-index
127 forms of entry often make sense for RSA Signature authentication.
128 The key part of an entry may start with a token indicating the kind of
130 key. "RSA" signifies RSA private key and "PSK" signifies PreShared Key
131 (case is ignored).
132 The token "XAUTH" indicates an IKEv1 eXtended Authentication password.
134 There should be one index, and it should be in the @FQDN format. The
135 file will be searched with the XAUTH username, which is usually
136 provided in the configuration file. XAUTH is otherwise identical to PSK
137 in syntax.
138 A preshared secret is most conveniently represented as a sequence of
140 characters, delimited by the double-quote character ("). The sequence
141 cannot contain a newline or double-quote. Strictly speaking, the secret
142 is actually the sequence of bytes that is used in the file to represent
143 the sequence of characters (excluding the delimiters). A preshared
144 secret may also be represented, without quotes, in any of supported
145 formats.
146 Currently supported formats are hexadecimal, base64, and characters.
148 A hexadecimal text value begins with a 0x (or 0X) prefix and continues
150 with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each
151 group encoding the value of one binary byte, high-order digit first. A
152 single _ (underscore) between consecutive groups is ignored, permitting
153 punctuation to improve readability; doing this every eight digits seems
154 about right.
155 A base64 text value begins with a 0s (or 0S) prefix and continues with
157 four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each
158 group encoding the value of three binary bytes as described in section
159 6.8 of RFC 2045. If flags has the TTODATAV_IGNORESPACE bit on, blanks
160 are ignore (after the prefix). Note that the last one or two digits of
161 a base64 group can be = to indicate that fewer than three binary bytes
162 are encoded.
163 A character text value begins with a 0t (or 0T) prefix and continues
165 with text characters, each being the value of one binary byte.
166 A raw RSA private key is a composite of eight generally large numbers.
168 The notation used is a brace-enclosed list of field name and value
169 pairs (see the example above). A suitable key, in a suitable format,
170 may be generated by ipsec_rsasigkey(8). The structure is very similar
171 to that used by BIND 8.2.2 or later, but note that the numbers must
172 have a "0s" prefix if they are in base 64. The order of the fields is
173 fixed. Note that most fields are now unused and filled in with the
174 CKAID, which is a reference to the location within the NSS database.
175 Post-quantum preshared keys (PPK) can be static. The token “PPKS”
177 indicates that the following key will be a PPK. The next token is a
178 PPK_ID that uniquely represents the given PPK. PPK_ID must be
179 represented as a sequence of characters delimited by the double-quote
180 character ("). The next token is a PPK itself. The static PPK may be
181 represented in any format that can be used for representing a preshared
182 secret. It is recommended that the static PPK be at least 256 bits in
183 order to provide real security against quantum computer attacks.
184 The first token of an entry must start in the first column of its line.
186 Subsequent tokens must be separated by whitespace, except for a colon
187 token, which only needs to be followed by whitespace. A newline is
188 taken as whitespace, but every line of an entry after the first must be
189 indented.
190 Whitespace at the end of a line is ignored (except in the 0t notation
192 for a key). At the start of line or after whitespace, # and the
193 following text up to the end of the line is treated as a comment.
194 Within entries, all lines must be indented (except for lines with no
195 tokens). Outside entries, no line may be indented (this is to make sure
196 that the file layout reflects its structure).
197 An include directive causes the contents of the named file to be
199 processed before continuing with the current file. The filename is
200 subject to "globbing" as in sh(1), so every file with a matching name
201 is processed. Includes may be nested to a modest depth (10, currently).
202 If the filename doesn't start with a /, the directory containing the
203 current file is prepended to the name. The include directive is a line
204 that starts with the word include, followed by whitespace, followed by
205 the filename (which must not contain whitespace).
206
208 /etc/ipsec.secrets
209
211 The rest of the Libreswan distribution, in particular ipsec.conf(5),
212 ipsec(8), ipsec_newhostkey(8), ipsec_rsasigkey(8),
213 ipsec_showhostkey(8), ipsec_auto(8) --rereadsecrets, and pluto(8)
214 --listen.
215
217 Originally designed for the FreeS/WAN project
218 <https://www.freeswan.org> by D. Hugh Redelmeier. Updated for Openswan
219 by Ken Bantoft. Updated for Libreswan by Paul Wouters
220 This file originally stored the private part of RSA keys. All private
222 key material is now stored in the NSS database. The fields of the raw
223 RSA key currently filled with the CKAID might be ignored and removed in
224 future versions.
225
227 If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
228 %any6.
229
231 Paul Wouters
232 libreswan secrets files
233libreswan 06/10/2019 IPSEC.SECRETS(5)