1IPSEC.SECRETS(5)              Executable programs             IPSEC.SECRETS(5)
2
3
4

NAME

6       ipsec.secrets - secrets for IKE/IPsec authentication
7

DESCRIPTION

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
16       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
21       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
25       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
30           # 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
37           # 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
42           # 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
45           # 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
56           # XAUTH password, used with leftxauthusername=username
57           @username : XAUTH "password"
58
59           include ipsec.*.secrets  # get secrets from other files
60
61
62       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
66       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
74       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
80       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
86       Smartcard support has been moved from Libreswan to NSS. Please see the
87       NSS documentation on how to configure smartcards.
88
89       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
98       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
111       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
119       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
123       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
129       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
133       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
139       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
147       Currently supported formats are hexadecimal, base64, and characters.
148
149       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
156       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
164       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
167       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
176       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
185       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
191       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
198       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

FILES

208       /etc/ipsec.secrets
209

SEE ALSO

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

HISTORY

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
221       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

BUGS

227       If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
228       %any6.
229

AUTHOR

231       Paul Wouters
232           libreswan secrets files
233
234
235
236libreswan                         06/10/2019                  IPSEC.SECRETS(5)
Impressum