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

NAME

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

DESCRIPTION

9       The file ipsec.secrets holds a table of secrets. These secrets are used
10       by ipsec_pluto(8), the Open Internet Key Exchange daemon, to  authenti‐
11       cate  other hosts. Currently there are four kinds of secrets: preshared
12       secrets, RSA private keys, passwords/PIN codes for  X.509  certificates
13       and  if  compiled  with USE_SMARTCARD=true, there is additional support
14       for storing the PINCODES of smartcards or USB tokens
15
16
17       It is vital that these secrets be protected. The file should  be  owned
18       by  the  super-user,  and  its  permissions  should be set to block all
19       access by others.
20
21
22       The file is a sequence of entries and include directives.  Here  is  an
23       example.  Each entry or directive must start at the left margin, but if
24       it continues beyond a single  line,  each  continuation  line  must  be
25       indented.
26
27
28       # 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
31       # an entry may be split across lines,
32       # but indentation matters
33       www.xs4all.nl @www.kremvax.ru
34           10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5"
35
36       # an RSA private key.
37       # note that the lines are too wide for a
38       # man page, so ... has been substituted for
39       # the truncated part
40       @my.com: rsa {
41           Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt...
42           PublicExponent: 0sAw==
43           PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN...
44           Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l...
45           Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0...
46           Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r...
47           Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6...
48           Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ...
49           }
50
51       # An X.509 pem encoded private key file with (optional) passphrase
52       : RSA vpnserverKey.pem "<optional passphrase>"
53       # An X.509 pem encoded private key file locked with a passphrase
54       :  RSA vpnserverKey.pem %prompt
55
56       # Entering a PIN code for a smartcard
57       : PIN %smartcard "12345678"
58       # For multiple smartcards use:
59       : PIN %smartcard<reader nr>:<PKCS#15 key id>"<PIN code>"
60       # or if you want to interactively type in the pin code
61       : PIN %smartcard %prompt
62
63       include ipsec.*.secrets  # get secrets from other files
64
65          Each  entry  in the file is a list of indices, followed by a secret.
66       The two parts are separated by a colon (:) that is followed  by  white‐
67       space  or  a  newline. For compatability with the previous form of this
68       file, if the key part is just a double-quoted string the colon  may  be
69       left out. If filenames are not absolute paths, they are relative to the
70       ipsec.d/private/ directory.
71
72
73       An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
74       %any  or  %any6 (other kinds may come). An IP address may be written in
75       the familiar dotted quad form or as a domain name to be looked up  when
76       the  file  is  loaded (or in any of the forms supported by the Openswan
77       ipsec_ttoaddr(3) routine). In many cases it is a bad idea to use domain
78       names because the name server may not be running or may be insecure. To
79       denote a Fully Qualified Domain Name  (as  opposed  to  an  IP  address
80       denoted by its domain name), precede the name with an at sign (@).
81
82
83       Matching  IDs  with  indices is fairly straightforward: they have to be
84       equal. In the case of a “Road Warrior” connection, if an equal match is
85       not found for the Peer's ID, and it is in the form of an IP address, an
86       index of %any will match the peer's IP address if IPV4 and  %any6  will
87       match a the peer's IP address if IPV6. Currently, the obsolete notation
88       0.0.0.0 may be used in place of %any.
89
90
91       This file is only read at startup time. If any changes are made to this
92       file,  the  pluto  daemon should be told to re-read this file using the
93       command ipsec secrets or ipsec auto --rereadsecrets. If there  are  any
94       keyfiles  or smartcards protected by a passphrase or pin using %prompt,
95       you will be prompted again to enter  these  passphrases.  To  skip  the
96       prompting,  just  hit  return to skip unlocking that particular private
97       key.
98
99
100       An additional complexity arises in the case of authentication  by  pre‐
101       shared secret: the responder will need to look up the secret before the
102       Peer's ID payload has been decoded, so the  ID  used  will  be  the  IP
103       address.
104
105
106       To  authenticate  a  connection  between two hosts, the entry that most
107       specifically matches the host and peer IDs is used. An  entry  with  no
108       index  will  match  any host and peer. More specifically, an entry with
109       one index will match a host and peer if the index matches the host's ID
110       (the  peer  isn't  considered).  Still more specifically, an entry with
111       multiple indices will match a host and peer if the host ID and peer  ID
112       each  match one of the indices. If the key is for an asymmetric authen‐
113       tication technique (i.e. a public key system such  as  RSA),  an  entry
114       with  multiple indices will match a host and peer even if only the host
115       ID matches an index (it is presumed that the multiple indices  are  all
116       identities  of  the  host).  It is acceptable for two entries to be the
117       best match as long as they agree about the secret or private key.
118
119
120       Authentication by preshared secret requires that both systems find  the
121       identical  secret  (the  secret  is not actually transmitted by the IKE
122       protocol). If both the host and peer appear in the index list, the same
123       entry  will  be  suitable  for both systems so verbatim copying between
124       systems can be used. This naturally extends to  larger  groups  sharing
125       the same secret. Thus multiple-index entries are best for PSK authenti‐
126       cation.
127
128
129       Authentication by RSA Signatures requires that each host have  its  own
130       private  key.  A host could reasonably use a different private keys for
131       different interfaces and for different peers. But it would not be  nor‐
132       mal to share entries between systems. Thus no-index and one-index forms
133       of entry often make sense for RSA Signature authentication.
134
135
136       The key part of an entry may start with a token indicating the kind  of
137       key.  “RSA” signifies RSA private key and “PSK” signifies PreShared Key
138       (case is ignored). For compatability with previous forms of this  file,
139       PSK is the default.
140
141
142       If  the RSA points to a filename, this is assumed to be a PEM (or DER?)
143       encoded X.509 private key. The private key may be protected by  a  3DES
144       encryption.  1DES  encrypted key files will be rejected. If the private
145       key is protected by a passphrase and this passphrase is  not  specified
146       in  ipsec.secrets, the connection cannot be automatically started using
147       auto=start, but instead must  be  brought  up  using  ipsec  auto  --up
148       connname,  upon  which  the user will be prompted for the passphrase to
149       unlock the private key belonging  to  the  X.509  certificate.  PKCS#12
150       files,  which  include  the  private  key  file, cannot be specified in
151       ipsec.secrets. Private keys can be extracted from PKCS#12  files  using
152       the  following command: openssl pkcs12 -nocerts -in clientCert.p12 -out
153       clientKey.pem
154
155
156       A preshared secret is most conveniently represented as  a  sequence  of
157       characters,  delimited  by the double-quote character ("). The sequence
158       cannot contain a newline or double-quote. Strictly speaking, the secret
159       is actually the sequence of bytes that is used in the file to represent
160       the sequence of characters  (excluding  the  delimiters).  A  preshared
161       secret  may  also be represented, without quotes, in any form supported
162       by ipsec_ttodata(3).
163
164
165       An RSA private key is a composite of eight generally large numbers. The
166       notation  used  is  a brace-enclosed list of field name and value pairs
167       (see the example above). A suitable key, in a suitable format,  may  be
168       generated  by ipsec_rsasigkey(8). The structure is very similar to that
169       used by BIND 8.2.2 or later, but note that the numbers must have a “0s”
170       prefix if they are in base 64. The order of the fields is fixed.
171
172
173       The  first  token  an entry must start in the first column of its line.
174       Subsequent tokens must be separated by whitespace, except for  a  colon
175       token,  which  only  needs  to  be followed by whitespace. A newline is
176       taken as whitespace, but every line of an entry after the first must be
177       indented.
178
179
180       Whitespace  at  the end of a line is ignored (except in the 0t notation
181       for a key). At the start of line or after whitespace, # and the follow‐
182       ing  text  up  to  the  end of the line is treated as a comment. Within
183       entries, all lines must be indented (except for lines with no  tokens).
184       Outside entries, no line may be indented (this is to make sure that the
185       file layout reflects its structure).
186
187
188       An include directive causes the contents of the named file to  be  pro‐
189       cessed before continuing with the current file. The filename is subject
190       to “globbing” as in sh(1), so every file with a matching name  is  pro‐
191       cessed.  Includes  may  be nested to a modest depth (10, currently). If
192       the filename doesn't start with a /, the directory containing the  cur‐
193       rent  file  is  prepended  to the name. The include directive is a line
194       that starts with the word include, followed by whitespace, followed  by
195       the filename (which must not contain whitespace).
196
197

FILES

199       /etc/ipsec.secrets
200
201

SEE ALSO

203       The  rest  of  the  Openswan distribution, in particular ipsec.conf(5),
204       ipsec(8),           ipsec_newhostkey(8),            ipsec_rsasigkey(8),
205       ipsec_showhostkey(8),      ipsec_auto(8)       --rereadsecrets,     and
206       ipsec_pluto(8)      --listen,.      BIND      8.2.2      or      later,
207       ftp://ftp.isc.org/isc/bind/src/: ftp://ftp.isc.org/isc/bind/src/
208
209

HISTORY

211       Originally designed for the FreeS/WAN project <http://www.freeswan.org:
212       http://www.freeswan.org> by D. Hugh Redelmeier.
213
214

BUGS

216       If an ID is 0.0.0.0, it will match %any; if it is 0::0, it  will  match
217       %any6.
218
219
220
221
222                                                              IPSEC.SECRETS(5)
Impressum