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), postquantum preshared keys (PPKs)
11       and XAUTH passwords. As of libreswan version 4.0, the secrets entries
12       for raw RSA keys are no longer needed and ignored. All private keys
13       from public keypairs (RSA or ECDSA) are stored completely in the NSS
14       database and :RSA entries are no longer required to locate these.
15
16       These secrets are used by pluto(8) , the Libreswan Internet Key
17       Exchange daemon, to authenticate other hosts. There is another one type
18       of secret, post-quantum preshared keys (PPKs), that are used for
19       protecting traffic from quantum computer attack.
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           # XAUTH password, used with leftusername=username
46           @username : XAUTH "password"
47
48           include ipsec.*.secrets  # get secrets from other files
49
50
51       Each entry in the file is a list of indices, followed by a secret. The
52       two parts are separated by a colon (:) that is followed by whitespace
53       or a newline.
54
55       An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
56       %any or %any6 (other kinds may come). An IP address may be written in
57       the familiar dotted quad form or as a domain name to be looked up when
58       the file is loaded. Be aware that using domain names requires DNS to be
59       functional before the IPsec tunnel comes up. To denote a Fully
60       Qualified Domain Name (as opposed to an IP address denoted by its
61       domain name), precede the name with an at sign (@).
62
63       Matching IDs with indices is fairly straightforward: they have to be
64       equal. In the case of a "Road Warrior" connection, if an equal match is
65       not found for the Peer's ID, and it is in the form of an IP address, an
66       index of %any will match the peer's IP address if IPV4 and %any6 will
67       match a the peer's IP address if IPV6.
68
69       This file is only read at startup time. If any changes are made to this
70       file, the pluto daemon should be told to re-read this file using the
71       command ipsec secrets or ipsec auto --rereadsecrets. Note that
72       currently there is no way to add a specific new entry - it's all or
73       nothing.
74
75       Smartcard support has been moved from Libreswan to NSS. The location of
76       these are specified using leftcert/rightcert entries with a PKIX URI in
77       ipsec.conf. No entry in the secrets file is required for these.
78
79       An additional complexity arises in the case of authentication by
80       preshared secret in IKEv1 Main Mode: the responder will need to look up
81       the secret before the Peer's ID payload has been decoded, so the ID
82       used will be the IP address. IKEv1 Aggressive Mode (aggrmode=yes) can
83       be used to work around this, at the price of leaking the ID in the
84       clear and allowing a brute force attack against the PSK to be performed
85       offline. PSKs are the least secure authentication method and should be
86       avoided.
87
88       To authenticate a connection between two hosts, the entry that most
89       specifically matches the host and peer IDs is used. An entry with no
90       index will match any host and peer. More specifically, an entry with
91       one index will match a host and peer if the index matches the host's ID
92       (the peer isn't considered). Still more specifically, an entry with
93       multiple indices will match a host and peer if the host ID and peer ID
94       each match one of the indices. It is acceptable for two entries to be
95       the best match as long as they agree about the secret.
96
97       Authentication by preshared secret requires that both systems find the
98       identical secret (the secret is not actually transmitted by the IKE
99       protocol). If both the host and peer appear in the index list, the same
100       entry will be suitable for both systems so verbatim copying between
101       systems can be used. This naturally extends to larger groups sharing
102       the same secret. Thus multiple-index entries are best for PSK
103       authentication.
104
105       When running in FIPS mode, PSK's need to comply to a minimum strength
106       requirement depending on the integrity and PRF algorithm used. It is
107       recommended not to use PSK's shorter then 64 random characters.
108
109       The token "XAUTH" indicates an IKEv1 eXtended Authentication password.
110       There should be one index, and it should be in the @FQDN format. The
111       file will be searched with the XAUTH username, which is usually
112       provided in the configuration file. XAUTH is otherwise identical to PSK
113       in syntax.
114
115       A preshared secret is most conveniently represented as a sequence of
116       characters, delimited by the double-quote character ("). The sequence
117       cannot contain a newline or double-quote. Strictly speaking, the secret
118       is actually the sequence of bytes that is used in the file to represent
119       the sequence of characters (excluding the delimiters). A preshared
120       secret may also be represented, without quotes, in any of supported
121       formats.
122
123       Currently supported formats are hexadecimal, base64, and characters.
124
125       A hexadecimal text value begins with a 0x (or 0X) prefix and continues
126       with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each
127       group encoding the value of one binary byte, high-order digit first. A
128       single _ (underscore) between consecutive groups is ignored, permitting
129       punctuation to improve readability; doing this every eight digits seems
130       about right.
131
132       A base64 text value begins with a 0s (or 0S) prefix and continues with
133       four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each
134       group encoding the value of three binary bytes as described in section
135       6.8 of RFC 2045. If flags has the TTODATAV_IGNORESPACE bit on, blanks
136       are ignore (after the prefix). Note that the last one or two digits of
137       a base64 group can be = to indicate that fewer than three binary bytes
138       are encoded.
139
140       A character text value begins with a 0t (or 0T) prefix and continues
141       with text characters, each being the value of one binary byte.
142
143       Post-quantum preshared keys (PPK) can be static. The token “PPKS”
144       indicates that the following key will be a PPK. The next token is a
145       PPK_ID that uniquely represents the given PPK. PPK_ID must be
146       represented as a sequence of characters delimited by the double-quote
147       character ("). The next token is a PPK itself. The static PPK may be
148       represented in any format that can be used for representing a preshared
149       secret. It is recommended that the static PPK be at least 256 bits in
150       order to provide real security against quantum computer attacks.
151
152       The first token of an entry must start in the first column of its line.
153       Subsequent tokens must be separated by whitespace, except for a colon
154       token, which only needs to be followed by whitespace. A newline is
155       taken as whitespace, but every line of an entry after the first must be
156       indented.
157
158       Whitespace at the end of a line is ignored (except in the 0t notation
159       for a key). At the start of line or after whitespace, # and the
160       following text up to the end of the line is treated as a comment.
161       Within entries, all lines must be indented (except for lines with no
162       tokens). Outside entries, no line may be indented (this is to make sure
163       that the file layout reflects its structure).
164
165       An include directive causes the contents of the named file to be
166       processed before continuing with the current file. The filename is
167       subject to "globbing" as in sh(1), so every file with a matching name
168       is processed. Includes may be nested to a modest depth (10, currently).
169       If the filename doesn't start with a /, the directory containing the
170       current file is prepended to the name. The include directive is a line
171       that starts with the word include, followed by whitespace, followed by
172       the filename (which must not contain whitespace).
173

FILES

175       /etc/ipsec.secrets
176

SEE ALSO

178       The rest of the Libreswan distribution, in particular ipsec.conf(5),
179       ipsec(8), ipsec_newhostkey(8), ipsec_rsasigkey(8),
180       ipsec_showhostkey(8), ipsec_auto(8) --rereadsecrets, and pluto(8)
181       --listen.
182

HISTORY

184       Originally designed for the FreeS/WAN project
185       <https://www.freeswan.org> by D. Hugh Redelmeier. Updated for Openswan
186       by Ken Bantoft. Updated for Libreswan by Paul Wouters
187
188       This file originally stored the private part of RSA keys. This was
189       later on moved to the NSS database, and all private fields were filled
190       with the CKAID to enable lookup in the NSS database. This was further
191       obsoleted in libreswan 4.0 and now the secrets file no longer contains
192       any public key pair information.
193

BUGS

195       If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
196       %any6.
197

AUTHOR

199       Paul Wouters
200           libreswan secrets files
201
202
203
204libreswan                         09/05/2023                  IPSEC.SECRETS(5)
Impressum