It is vital that these secrets be protected. The file should be owned by the super-user, and its permissions should be set to block all access by others.
The file is a sequence of entries and include directives. Here is an example. Each entry or directive must start at the left margin, but if it continues beyond a single line, each continuation line must be indented.
# sample /etc/ipsec.secrets file for 10.1.0.1 10.1.0.1 10.2.0.1: PSK "secret shared by two hosts" # an entry may be split across lines, # but indentation matters www.xs4all.nl @www.kremvax.ru 10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5" # an RSA private key. # note that the lines are too wide for a # man page, so ... has been substituted for # the truncated part @my.com: rsa { Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt... PublicExponent: 0sAw== PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN... Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l... Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0... Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r... Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6... Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ... } include ipsec.*.secrets # get secrets from other files
Each entry in the file is a list of indices, followed by a secret. The two parts are separated by a colon (:) that is followed by whitespace or a newline. For compatability with the previous form of this file, if the key part is just a double-quoted string the colon may be left out.
An index is an IP address, or a Fully Qualified Domain Name, user@FQDN, %any or %any6 (other kinds may come). An IP address may be written in the familiar dotted quad form or as a domain name to be looked up when the file is loaded (or in any of the forms supported by the FreeS/WAN ipsec_ttoaddr(3) routine). In many cases it is a bad idea to use domain names because the name server may not be running or may be insecure. To denote a Fully Qualified Domain Name (as opposed to an IP address denoted by its domain name), precede the name with an at sign (@).
Matching IDs with indices is fairly straightforward: they have to be equal. In the case of a ``Road Warrior'' connection, if an equal match is not found for the Peer's ID, and it is in the form of an IP address, an index of %any will match the peer's IP address if IPV4 and %any6 will match a the peer's IP address if IPV6. Currently, the obsolete notation 0.0.0.0 may be used in place of %any.
An additional complexity arises in the case of authentication by preshared secret: the responder will need to look up the secret before the Peer's ID payload has been decoded, so the ID used will be the IP address.
To authenticate a connection between two hosts, the entry that most specifically matches the host and peer IDs is used. An entry with no index will match any host and peer. More specifically, an entry with one index will match a host and peer if the index matches the host's ID (the peer isn't considered). Still more specifically, an entry with multiple indices will match a host and peer if the host ID and peer ID each match one of the indices. If the key is for an asymmetric authentication technique (i.e. a public key system such as RSA), an entry with multiple indices will match a host and peer even if only the host ID matches an index (it is presumed that the multiple indices are all identities of the host). It is acceptable for two entries to be the best match as long as they agree about the secret or private key.
Authentication by preshared secret requires that both systems find the identical secret (the secret is not actually transmitted by the IKE protocol). If both the host and peer appear in the index list, the same entry will be suitable for both systems so verbatim copying between systems can be used. This naturally extends to larger groups sharing the same secret. Thus multiple-index entries are best for PSK authentication.
Authentication by RSA Signatures requires that each host have its own private key. A host could reasonably use a different private keys for different interfaces and for different peers. But it would not be normal to share entries between systems. Thus thus no-index and one-index forms of entry often make sense for RSA Signature authentication.
The key part of an entry may start with a token indicating the kind of key. ``RSA'' signifies RSA private key and ``PSK'' signifies PreShared Key (case is ignored). For compatability with previous forms of this file, PSK is the default.
A preshared secret is most conveniently represented as a sequence of characters, delimited by the double-quote character ("). The sequence cannot contain a newline or double-quote. Strictly speaking, the secret is actually the sequence of bytes that is used in the file to represent the sequence of characters (excluding the delimiters). A preshared secret may also be represented, without quotes, in any form supported by ipsec_ttodata(3).
An RSA private key is a composite of eight generally large numbers. The notation used is a brace-enclosed list of field name and value pairs (see the example above). A suitable key, in a suitable format, may be generated by ipsec_rsasigkey(8). The structure is very similar to that used by BIND 8.2.2 or later, but note that the numbers must have a ``0s'' prefix if they are in base 64. The order of the fields is fixed.
The first token an entry must start in the first column of its line. Subsequent tokens must be separated by whitespace, except for a colon token, which only needs to be followed by whitespace. A newline is taken as whitespace, but every line of an entry after the first must be indented.
Whitespace at the end of a line is ignored (except in the 0t notation for a key). At the start of line or after whitespace, # and the following text up to the end of the line is treated as a comment. Within entries, all lines must be indented (except for lines with no tokens). Outside entries, no line may be indented (this is to make sure that the file layout reflects its structure).
An include directive causes the contents of the named file to be processed before continuing with the current file. The filename is subject to ``globbing'' as in sh(1), so every file with a matching name is processed. Includes may be nested to a modest depth (10, currently). If the filename doesn't start with a /, the directory containing the current file is prepended to the name. The include directive is a line that starts with the word include, followed by whitespace, followed by the filename (which must not contain whitespace).