man/ipsec.secrets.5.in

   1 .TH IPSEC.SECRETS 5 "2011-12-14" "@PACKAGE_VERSION@" "strongSwan"
   2 .SH NAME
   3 ipsec.secrets \- secrets for IKE/IPsec authentication
   4 .SH DESCRIPTION
   5 The file \fIipsec.secrets\fP holds a table of secrets.
   6 These secrets are used by the strongSwan Internet Key Exchange (IKE) daemons
   7 pluto (IKEv1) and charon (IKEv2) to authenticate other hosts.
   8 .LP
   9 It is vital that these secrets be protected.  The file should be owned
  10 by the super-user,
  11 and its permissions should be set to block all access by others.
  12 .LP
  13 The file is a sequence of entries and include directives.
  14 Here is an example.
  15 .LP
  16 .RS
  17 .nf
  18 # /etc/ipsec.secrets - strongSwan IPsec secrets file
  19 192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
  20
  21 : RSA moonKey.pem
  22
  23 alice@strongswan.org : EAP "x3.dEhgN"
  24
  25 carol : XAUTH "4iChxLT3"
  26
  27 dave  : XAUTH "ryftzG4A"
  28
  29 # get secrets from other files
  30 include ipsec.*.secrets
  31 .fi
  32 .RE
  33 .LP
  34 Each entry in the file is a list of optional ID selectors, followed by a secret.
  35 The two parts are separated by a colon (\fB:\fP) that is surrounded
  36 by whitespace. If no ID selectors are specified the line must start with a
  37 colon.
  38 .LP
  39 A selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
  40 \fB%any\fP or \fB%any6\fP (other kinds may come).
  41 .LP
  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
  44 match is not found for the Peer's ID, and it is in the form of an IP
  45 address, a selector of \fB%any\fP will match the peer's IP address if IPV4
  46 and \fB%any6\fP will match a the peer's IP address if IPV6.
  47 Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
  48 \fB%any\fP.
  49 .LP
  50 In IKEv1 an additional complexity
  51 arises in the case of authentication by preshared secret: the
  52 responder will need to look up the secret before the Peer's ID payload has
  53 been decoded, so the ID used will be the IP address.
  54 .LP
  55 To authenticate a connection between two hosts, the entry that most
  56 specifically matches the host and peer IDs is used.  An entry with no
  57 selectors will match any host and peer.  More specifically, an entry with one
  58 selector will match a host and peer if the selector matches the host's ID (the
  59 peer isn't considered).  Still more specifically, an entry with multiple
  60 selectors will match a host and peer if the host ID and peer ID each match one
  61 of the selectors.  If the key is for an asymmetric authentication technique
  62 (i.e. a public key system such as RSA), an entry with multiple selectors will
  63 match a host and peer even if only the host ID matches a selector (it is
  64 presumed that the selectors are all identities of the host).
  65 It is acceptable for two entries to be the best match as
  66 long as they agree about the secret or private key.
  67 .LP
  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 PSK
  74 authentication.
  75 .LP
  76 Authentication by public key systems such as RSA requires that each host
  77 have its own private key.  A host could reasonably use a different private keys
  78 for different interfaces and for different peers.  But it would not
  79 be normal to share entries between systems.  Thus thus no-selector and
  80 one-selector forms of entry often make sense for public key authentication.
  81 .LP
  82 The key part of an entry must start with a token indicating the kind of
  83 key.  The following types of secrets are currently supported:
  84 .TP
  85 .B PSK
  86 defines a pre-shared key
  87 .TP
  88 .B RSA
  89 defines an RSA private key
  90 .TP
  91 .B ECDSA
  92 defines an ECDSA private key
  93 .TP
  94 .B P12
  95 defines a PKCS#12 container
  96 .TP
  97 .B EAP
  98 defines EAP credentials
  99 .TP
 100 .B NTLM
 101 defines NTLM credentials
 102 .TP
 103 .B XAUTH
 104 defines XAUTH credentials
 105 .TP
 106 .B PIN
 107 defines a smartcard PIN
 108 .LP
 109 Details on each type of secret are given below.
 110 .LP
 111 Whitespace at the end of a line is ignored. At the start of a line or
 112 after whitespace, \fB#\fP and the following text up to the end of the
 113 line is treated as a comment.
 114 .LP
 115 An include directive causes the contents of the named file to be processed
 116 before continuing with the current file.  The filename is subject to
 117 ``globbing'' as in \fIsh\fP(1), so every file with a matching name
 118 is processed.  Includes may be nested to a modest
 119 depth (10, currently).  If the filename doesn't start with a \fB/\fP, the
 120 directory containing the current file is prepended to the name.  The
 121 include directive is a line that starts with the word \fBinclude\fP,
 122 followed by whitespace, followed by the filename (which must not contain
 123 whitespace).
 124 .SS TYPES OF SECRETS
 125 .TP
 126 .B [ <selectors> ] : PSK <secret>
 127 A preshared \fIsecret\fP is most conveniently represented as a sequence of
 128 characters, which is delimited by double-quote characters (\fB"\fP).
 129 The sequence cannot contain newline or double-quote characters.
 130 .br
 131 Alternatively, preshared secrets can be represented as hexadecimal or Base64
 132 encoded binary values. A character sequence beginning with
 133 .B 0x
 134 is interpreted as sequence of hexadecimal digits.
 135 Similarly, a character sequence beginning with
 136 .B 0s
 137 is interpreted as Base64 encoded binary data.
 138 .TP
 139 .B : RSA <private key file> [ <passphrase> | %prompt ]
 140 .TQ
 141 .B : ECDSA <private key file> [ <passphrase> | %prompt ]
 142 For the private key file both absolute paths or paths relative to
 143 \fI/etc/ipsec.d/private\fP are accepted. If the private key file is
 144 encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
 145 .B %prompt
 146 can be used which then causes the daemon to ask the user for the password
 147 whenever it is required to decrypt the key.
 148 .TP
 149 .B : P12 <PKCS#12 file> [ <passphrase> | %prompt ]
 150 For the PKCS#12 file both absolute paths or paths relative to
 151 \fI/etc/ipsec.d/private\fP are accepted. If the container is
 152 encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
 153 .B %prompt
 154 can be used which then causes the daemon to ask the user for the password
 155 whenever it is required to decrypt the container. Private keys, client and CA
 156 certificates are extracted from the container. To use such a client certificate
 157 in a connection set leftid to one of the subjects of the certificate.
 158 .TP
 159 .B <user id> : EAP <secret>
 160 The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets.
 161 .br
 162 \fBEAP\fP secrets are IKEv2 only.
 163 .TP
 164 .B <user id> : NTLM <secret>
 165 The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets, but the
 166 secret is stored as NTLM hash, which is MD4(UTF-16LE(secret)), instead of as
 167 cleartext.
 168 .br
 169 \fBNTLM\fP secrets can only be used with the \fBeap-mschapv2\fP plugin.
 170 .TP
 171 .B [ <servername> ] <username> : XAUTH <password>
 172 The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets.
 173 \fBXAUTH\fP secrets are IKEv1 only.
 174 .TP
 175 .B : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt
 176 The smartcard selector always requires a keyid to uniquely select the correct
 177 key. The slot number defines the slot on the token, the module name refers to
 178 the module name defined in strongswan.conf(5).
 179 Instead of specifying the pin code statically,
 180 .B %prompt
 181 can be specified, which causes the daemon to ask the user for the pin code.
 182 .LP
 183
 184 .SH FILES
 185 /etc/ipsec.secrets
 186 .SH SEE ALSO
 187 ipsec.conf(5), strongswan.conf(5), ipsec(8)
 188 .br
 189 .SH HISTORY
 190 Originally written for the FreeS/WAN project by D. Hugh Redelmeier.
 191 Updated and extended for the strongSwan project <http://www.strongswan.org> by
 192 Tobias Brunner and Andreas Steffen.
 193 .SH BUGS
 194 If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
 195 if it is \fB0::0\fP, it will match \fB%any6\fP.