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.
13 RSA private keys are stored in the NSS database. The secrets file only
15 contains a reference to these private RSA keys. For RSA keys belonging
16 to imported X.509 certificates, the certificate "friendly name" is
17 used. For raw RSA keys, the CKAID is used.
18 XAUTH passwords are stored in plaintext in this file. The secrets file
20 should be owned by root, and permissions should be set to block all
21 access by others. (eg: chmod 600)
22 The file is a sequence of entries and include directives. Here is an
24 example - each entry or directive must start at the left margin, but if
25 it continues beyond a single line, each continuation line must be
26 indented.
27 # sample /etc/ipsec.secrets file for 10.1.0.1
29 10.1.0.1 10.2.0.1 : PSK "secret shared by two hosts"
30 # sample roadwarrior
31 %any gateway.corp.com : PSK "shared secret with many roadwarriors"
32 # sample server for roadwarriors
33 myip %any : PSK "shared secret with many roadwarriors"
34 # an entry may be split across lines,
36 # but indentation matters
37 www.xs4all.nl @www.kremvax.ru
38 10.6.0.1 10.7.0.1 1.8.0.1 : PSK "secret shared by 5 systems"
39 # a raw RSA private key in NSS. All but the public exponent now point
41 # to the NSS CKAIDNSS
42 # note that the lines are too wide for a
43 # man page, so ... has been substituted for
44 # the truncated part
45 @my.com : RSA {
46 #pubkey=0sAQPaGwWbUSK...
47 PublicExponent: 0x03
48 PrivateExponent: 0x316e6593...
49 Prime1: 0x316e6593...
50 Prime2: 0x316e6593...
51 Exponent1: 0x316e6593...
52 Exponent2: 0x316e6593...
53 Coefficient: 0x316e6593...
54 CKAIDNSS: 0x316e6593...
55 }
56 # an imported X.509 certificate in NSS
58 : RSA "<friendly name>"
59 # XAUTH password, used with leftxauthusername=username
61 @username : XAUTH "password"
62 include ipsec.*.secrets # get secrets from other files
64 Each entry in the file is a list of indices, followed by a secret. The
67 two parts are separated by a colon (:) that is followed by whitespace
68 or a newline.
69 An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
71 %any or %any6 (other kinds may come). An IP address may be written in
72 the familiar dotted quad form or as a domain name to be looked up when
73 the file is loaded (or in any of the forms supported by the Libreswan
74 ipsec_ttoaddr(3) routine). Be aware that using domain names requires
75 DNS to be functional before the IPsec tunnel comes up. To denote a
76 Fully Qualified Domain Name (as opposed to an IP address denoted by its
77 domain name), precede the name with an at sign (@).
78 Matching IDs with indices is fairly straightforward: they have to be
80 equal. In the case of a “Road Warrior” connection, if an equal match is
81 not found for the Peer´s ID, and it is in the form of an IP address, an
82 index of %any will match the peer´s IP address if IPV4 and %any6 will
83 match a the peer´s IP address if IPV6.
84 This file is only read at startup time. If any changes are made to this
86 file, the pluto daemon should be told to re-read this file using the
87 command ipsec secrets or ipsec auto --rereadsecrets. Note that
88 currently there is no way to add a specific new entry - it´s all or
89 nothing.
90 Smartcard support has been moved from Libreswan to NSS. Please see the
92 NSS documentation on how to configure smartcards.
93 An additional complexity arises in the case of authentication by
95 preshared secret: the responder will need to look up the secret before
96 the Peer´s ID payload has been decoded, so the ID used will be the IP
97 address.
98 To authenticate a connection between two hosts, the entry that most
100 specifically matches the host and peer IDs is used. An entry with no
101 index will match any host and peer. More specifically, an entry with
102 one index will match a host and peer if the index matches the host´s ID
103 (the peer isn´t considered). Still more specifically, an entry with
104 multiple indices will match a host and peer if the host ID and peer ID
105 each match one of the indices. If the key is for an asymmetric
106 authentication technique (i.e. a public key system such as RSA), an
107 entry with multiple indices will match a host and peer even if only the
108 host ID matches an index (it is presumed that the multiple indices are
109 all identities of the host). It is acceptable for two entries to be the
110 best match as long as they agree about the secret or private key.
111 Authentication by preshared secret requires that both systems find the
113 identical secret (the secret is not actually transmitted by the IKE
114 protocol). If both the host and peer appear in the index list, the same
115 entry will be suitable for both systems so verbatim copying between
116 systems can be used. This naturally extends to larger groups sharing
117 the same secret. Thus multiple-index entries are best for PSK
118 authentication.
119 Authentication by raw RSA Signatures requires that each host have its
121 own private key. A host could reasonably use a different private keys
122 for different interfaces and for different peers. But it would not be
123 normal to share entries between systems. Thus no-index and one-index
124 forms of entry often make sense for RSA Signature authentication.
125 The key part of an entry may start with a token indicating the kind of
127 key. “RSA” signifies RSA private key and “PSK” signifies PreShared Key
128 (case is ignored).
129 The token “XAUTH” indicates a eXtended Authentication password. There
131 should be one indice, and it should be in the @FQDN format. The file
132 will be searched with the XAUTH username, which is usually provided in
133 the configuration file. XAUTH is otherwise identical to PSK in syntax.
134 A preshared secret is most conveniently represented as a sequence of
136 characters, delimited by the double-quote character ("). The sequence
137 cannot contain a newline or double-quote. Strictly speaking, the secret
138 is actually the sequence of bytes that is used in the file to represent
139 the sequence of characters (excluding the delimiters). A preshared
140 secret may also be represented, without quotes, in any form supported
141 by ipsec_ttodata(3).
142 A raw RSA private key is a composite of eight generally large numbers.
144 The notation used is a brace-enclosed list of field name and value
145 pairs (see the example above). A suitable key, in a suitable format,
146 may be generated by ipsec_rsasigkey(8). The structure is very similar
147 to that used by BIND 8.2.2 or later, but note that the numbers must
148 have a “0s” prefix if they are in base 64. The order of the fields is
149 fixed. Note that most fields are now unused and filled in with the
150 CKAID, which is a reference to the location within the NSS database.
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 <http://www.freeswan.org>
185 by D. Hugh Redelmeier. Updated for Openswan by Ken Bantoft. Updated for
186 Libreswan by Paul Wouters
187 This file originally stored the private part of RSA keys. All private
189 key material is now stored in the NSS database. The fields of the raw
190 RSA key currently filled with the CKAID might be ignored and removed in
191 future versions.
192
194 If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
195 %any6.
196
198 Paul Wouters
199 placeholder to suppress warning
200libreswan 10/04/2017 IPSEC.SECRETS(5)