Ubuntu Manpage: ipsec.secrets - secrets for IKE/IPsec authentication

Provided by: libreswan_4.14-1ubuntu2_amd64

NAME

       ipsec.secrets - secrets for IKE/IPsec authentication

DESCRIPTION

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

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.

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. 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 secrets or ipsec auto
--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).

FILES

       /etc/ipsec.secrets

HISTORY

       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.

BUGS

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

AUTHOR