1IPSEC.SECRETS(5)                  strongSwan                  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
10       used by the  strongSwan  Internet  Key  Exchange  (IKE)  daemons  pluto
11       (IKEv1) and charon (IKEv2) to authenticate other hosts.
12
13       It  is vital that these secrets be protected.  The file should be owned
14       by the super-user, and its permissions  should  be  set  to  block  all
15       access by others.
16
17       The  file  is a sequence of entries and include directives.  Here is an
18       example.
19
20              # /etc/ipsec.secrets - strongSwan IPsec secrets file
21              192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
22
23              : RSA moonKey.pem
24
25              alice@strongswan.org : EAP "x3.dEhgN"
26
27              carol : XAUTH "4iChxLT3"
28
29              dave  : XAUTH "ryftzG4A"
30
31              # get secrets from other files
32              include ipsec.*.secrets
33
34       Each entry in the file is a list of optional ID selectors, followed  by
35       a  secret.   The  two  parts  are separated by a colon (:) that is sur‐
36       rounded by whitespace. If no ID selectors are specified the  line  must
37       start with a colon.
38
39       A  selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
40       %any or %any6 (other kinds may come).
41
42       Matching IDs with selectors is fairly straightforward: they have to  be
43       equal.  In the case of a ``Road Warrior'' connection, if an equal match
44       is not found for the Peer's ID, and it is in the form of an IP address,
45       a  selector  of %any will match the peer's IP address if IPV4 and %any6
46       will match a the peer's IP address if IPV6.   Currently,  the  obsolete
47       notation 0.0.0.0 may be used in place of %any.
48
49       In  IKEv1 an additional complexity arises in the case of authentication
50       by preshared secret: the responder will need  to  look  up  the  secret
51       before  the  Peer's ID payload has been decoded, so the ID used will be
52       the IP address.
53
54       To authenticate a connection between two hosts,  the  entry  that  most
55       specifically  matches  the host and peer IDs is used.  An entry with no
56       selectors will match any host and peer.  More  specifically,  an  entry
57       with  one  selector  will match a host and peer if the selector matches
58       the host's ID (the peer isn't considered).  Still more specifically, an
59       entry with multiple selectors will match a host and peer if the host ID
60       and peer ID each match one of the selectors.  If  the  key  is  for  an
61       asymmetric  authentication  technique (i.e. a public key system such as
62       RSA), an entry with multiple selectors will match a host and peer  even
63       if  only the host ID matches a selector (it is presumed that the selec‐
64       tors are all identities of the host).  It is acceptable for two entries
65       to  be the best match as long as they agree about the secret or private
66       key.
67
68       Authentication by preshared secret requires that both systems find  the
69       identical  secret  (the  secret  is not actually transmitted by the IKE
70       protocol).  If both the host and peer appear in the selector list,  the
71       same  entry  will  be  suitable  for  both  systems so verbatim copying
72       between systems can be used.  This naturally extends to  larger  groups
73       sharing  the  same secret.  Thus multiple-selector entries are best for
74       PSK authentication.
75
76       Authentication by public key systems such as  RSA  requires  that  each
77       host have its own private key.  A host could reasonably use a different
78       private keys for different interfaces and for different peers.  But  it
79       would  not  be  normal to share entries between systems.  Thus thus no-
80       selector and one-selector forms of entry often make  sense  for  public
81       key authentication.
82
83       The key part of an entry must start with a token indicating the kind of
84       key.  The following types of secrets are currently supported:
85
86       PSK    defines a pre-shared key
87
88       RSA    defines an RSA private key
89
90       ECDSA  defines an ECDSA private key
91
92       P12    defines a PKCS#12 container
93
94       EAP    defines EAP credentials
95
96       NTLM   defines NTLM credentials
97
98       XAUTH  defines XAUTH credentials
99
100       PIN    defines a smartcard PIN
101
102       Details on each type of secret are given below.
103
104       Whitespace at the end of a line is ignored. At the start of a  line  or
105       after whitespace, # and the following text up to the end of the line is
106       treated as a comment.
107
108       An include directive causes the contents of the named file to  be  pro‐
109       cessed  before  continuing with the current file.  The filename is sub‐
110       ject to ``globbing'' as in sh(1), so every file with a matching name is
111       processed.   Includes  may be nested to a modest depth (10, currently).
112       If the filename doesn't start with a /, the  directory  containing  the
113       current file is prepended to the name.  The include directive is a line
114       that starts with the word include, followed by whitespace, followed  by
115       the filename (which must not contain whitespace).
116
117   TYPES OF SECRETS
118       [ <selectors> ] : PSK <secret>
119              A  preshared  secret  is  most  conveniently  represented  as  a
120              sequence of characters, which is delimited by double-quote char‐
121              acters (").  The sequence cannot contain newline or double-quote
122              characters.
123              Alternatively, preshared secrets can be represented as hexadeci‐
124              mal or Base64 encoded binary values. A character sequence begin‐
125              ning with 0x is interpreted as sequence of  hexadecimal  digits.
126              Similarly, a character sequence beginning with 0s is interpreted
127              as Base64 encoded binary data.
128
129       : RSA <private key file> [ <passphrase> | %prompt ]
130       : ECDSA <private key file> [ <passphrase> | %prompt ]
131              For the private key file both absolute paths or  paths  relative
132              to /etc/ipsec.d/private are accepted. If the private key file is
133              encrypted,  the  passphrase  must  be  defined.  Instead  of   a
134              passphrase  %prompt  can be used which then causes the daemon to
135              ask the user for the password whenever it is required to decrypt
136              the key.
137
138       : P12 <PKCS#12 file> [ <passphrase> | %prompt ]
139              For  the  PKCS#12  file both absolute paths or paths relative to
140              /etc/ipsec.d/private  are  accepted.   If   the   container   is
141              encrypted,   the  passphrase  must  be  defined.  Instead  of  a
142              passphrase %prompt can be used which then causes the  daemon  to
143              ask the user for the password whenever it is required to decrypt
144              the container. Private keys,  client  and  CA  certificates  are
145              extracted  from  the container. To use such a client certificate
146              in a connection set leftid to one of the subjects  of  the  cer‐
147              tificate.
148
149       <user id> : EAP <secret>
150              The format of secret is the same as that of PSK secrets.
151              EAP secrets are IKEv2 only.
152
153       <user id> : NTLM <secret>
154              The format of secret is the same as that of PSK secrets, but the
155              secret is stored as NTLM hash, which  is  MD4(UTF-16LE(secret)),
156              instead of as cleartext.
157              NTLM secrets can only be used with the eap-mschapv2 plugin.
158
159       [ <servername> ] <username> : XAUTH <password>
160              The  format  of  password  is  the  same as that of PSK secrets.
161              XAUTH secrets are IKEv1 only.
162
163       : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt
164              The smartcard selector  always  requires  a  keyid  to  uniquely
165              select  the correct key. The slot number defines the slot on the
166              token, the module name refers to  the  module  name  defined  in
167              strongswan.conf(5).   Instead  of specifying the pin code stati‐
168              cally, %prompt can be specified, which causes the daemon to  ask
169              the user for the pin code.
170

FILES

172       /etc/ipsec.secrets
173

SEE ALSO

175       ipsec.conf(5), strongswan.conf(5), ipsec(8)
176

HISTORY

178       Originally  written  for  the  FreeS/WAN project by D. Hugh Redelmeier.
179       Updated     and     extended     for     the     strongSwan     project
180       <http://www.strongswan.org> by Tobias Brunner and Andreas Steffen.
181

BUGS

183       If  an  ID is 0.0.0.0, it will match %any; if it is 0::0, it will match
184       %any6.
185
186
187
1885.9.1                             2011-12-14                  IPSEC.SECRETS(5)
Impressum