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), 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 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 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 # XAUTH password, used with leftusername=username
46 @username : XAUTH "password"
47 include ipsec.*.secrets # get secrets from other files
49 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 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 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 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 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 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 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 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 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 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 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 Currently supported formats are hexadecimal, base64, and characters.
124 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 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 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 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 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 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 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
175 /etc/ipsec.secrets
176
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
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 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
195 If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
196 %any6.
197
199 Paul Wouters
200 libreswan secrets files
201libreswan 09/05/2023 IPSEC.SECRETS(5)