ipsec.secrets - Man Page

The file ipsec​.secrets contains a list of secrets​. Currently supported secrets are preshared secrets (PSKs), postquantum preshared keys (PPKs) and XAUTH passwords​. As of libreswan version 4​.0, the secrets entries for raw RSA keys are no longer needed and ignored​. All private keys from public keypairs (RSA or ECDSA) are stored completely in the NSS database and :RSA entries are no longer required to locate these​.

These secrets are used by ipsec-pluto(8), the Libreswan Internet Key Exchange daemon, to authenticate other hosts​. There is another one type of secret, post-quantum preshared keys (PPKs), that are used for protecting traffic from quantum computer attack​.

XAUTH passwords are stored in plaintext in this file​. The secrets file should be owned by root, and permissions should be set to block all access by others​. (eg: chmod 600)

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"
# same for IPv6
"10::1:0:1" "10::2:0:1" : PSK "secret shared by two IPv6 hosts"

# sample roadwarrior
%any gateway​.corp​.com : PSK "shared secret with many roadwarriors"

# sample server for roadwarriors
myip %any : PSK "shared secret with many roadwarriors"

# 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 systems"

# sample entry for static PPK
10​.1​.0​.1 10​.2​.0​.1 : PPKS "PPK_ID_1" "post-quantum preshared key for extra security"

# XAUTH password, used with leftusername=username
@username : XAUTH "password"

# get secrets from other files
include ipsec​.*​.secrets

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​.

An index is either an IP address, a Fully Qualified Domain Name, user@FQDN, %any or %any6 (other kinds may come)​. An IP address may be written in the dotted quad form (IPv4), colon form (IPv6, wrapped in double quotes) or as a domain name to be looked up when the file is loaded​. Be aware that using domain names requires DNS to be functional before the IPsec tunnel comes up​. 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​.

This file is only read at startup time​. If any changes are made to this file, the pluto daemon should be told to re-read this file using the command ipsec rereadsecrets​. Note that currently there is no way to add a specific new entry - it's all or nothing​.

Smartcard support has been moved from Libreswan to NSS​. The location of these are specified using leftcert/rightcert entries with a PKIX URI in ipsec​.conf​. No entry in the secrets file is required for these​.

An additional complexity arises in the case of authentication by preshared secret in IKEv1 Main Mode: 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​. IKEv1 Aggressive Mode (aggrmode=yes) can be used to work around this, at the price of leaking the ID in the clear and allowing a brute force attack against the PSK to be performed offline​. PSKs are the least secure authentication method and should be avoided​.

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​.

It is acceptable for two entries to be the best match as long as they agree about the secret​.

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​.

When running in FIPS mode, PSK's need to comply to a minimum strength requirement depending on the integrity and PRF algorithm used​. It is recommended not to use PSK's shorter then 64 random characters​.

The token "XAUTH" indicates an IKEv1 eXtended Authentication password​. There should be one index, and it should be in the @FQDN format​. The file will be searched with the XAUTH username, which is usually provided in the configuration file​. XAUTH is otherwise identical to PSK in syntax​.

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 of supported formats​.

Currently supported formats are hexadecimal, base64, and characters​.

A hexadecimal text value begins with a 0x (or 0X) prefix and continues with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each group encoding the value of one binary byte, high-order digit first​. A single _ (underscore) between consecutive groups is ignored, permitting punctuation to improve readability; doing this every eight digits seems about right​.

A base64 text value begins with a 0s (or 0S) prefix and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each group encoding the value of three binary bytes as described in section 6​.8 of RFC 2045​. If flags has the TTODATAV_IGNORESPACE bit on, blanks are ignore (after the prefix)​. Note that the last one or two digits of a base64 group can be = to indicate that fewer than three binary bytes are encoded​.

A character text value begins with a 0t (or 0T) prefix and continues with text characters, each being the value of one binary byte​.

Post-quantum preshared keys (PPK) can be static​. The token “PPKS” indicates that the following key will be a PPK​. The next token is a PPK_ID that uniquely represents the given PPK​. PPK_ID must be represented as a sequence of characters delimited by the double-quote character (")​. The next token is a PPK itself​. The static PPK may be represented in any format that can be used for representing a preshared secret​. It is recommended that the static PPK be at least 256 bits in order to provide real security against quantum computer attacks​.

The first token of 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)​.

/etc/ipsec.secrets

The rest of the Libreswan distribution, in particular ipsec.conf(5), ipsec(8), ipsec-newhostkey(8), ipsec-rsasigkey(8), ipsec-showhostkey(8), ipsec-rereadsecrets(8), and ipsec-listen(8)​.

Originally designed for the FreeS/WAN project <https://www​.freeswan​.org> by D​. Hugh Redelmeier​. Updated for Openswan by Ken Bantoft​. Updated for Libreswan by Paul Wouters

This file originally stored the private part of RSA keys​. This was later on moved to the NSS database, and all private fields were filled with the CKAID to enable lookup in the NSS database​. This was further obsoleted in libreswan 4​.0 and now the secrets file no longer contains any public key pair information​.

If an ID is 0​.0​.0​.0, it will match %any; if it is 0::0, it will match %any6​.

Andrew Cagney, Daniel Kahn Gillmor, D​. Hugh Redelmeier, Harald Jenny, Jose Quaresma, Ken Bantoft, Michael Richardson, Paul Wouters, Tuomo Soini, Vukasin Karadzic

ipsec.conf(5), ipsec-newhostkey(8), ipsec-pluto(8), ipsec-whack(8), libreswan(7), strongswan(8), strongswan.conf(5), strongswan_ipsec.conf(5).