Provided by: libreswan_3.23-4_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), RSA keys and XAUTH passwords. 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.
RSA private keys are stored in the NSS database. The secrets file only contains a reference to these
private RSA keys. For RSA keys belonging to imported X.509 certificates, the certificate "friendly name"
is used. For raw RSA keys, the CKAID is used.
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"
# sample entry for dynamic PPK
10.1.0.1 10.2.0.1 : PPKF "PPK_ID_2" "/etc/ipsec.d/name_of_the_dynamic_ppk_file.txt"
# a raw RSA private key in NSS.
# note that the lines are too wide for a
# man page, so ... has been substituted for
# the truncated part
@my.com : RSA {
#ckaid: 0x316e6593...
#pubkey=0sAQPaGwWbUSK...
Modulus: 0x.....
PublicExponent: 0x03
}
# XAUTH password, used with leftxauthusername=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 (or in any of the forms supported by the Libreswan ipsec_ttoaddr(3) routine). 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. Please see the NSS documentation on how to
configure smartcards.
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. 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.
When running in FIPS mode, PSK's need to comply to a minimum strength requirement depending on the
integrity algorithm used. It is recommended not to use PSK's shorter then 64 random characters.
Authentication by raw 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 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).
The token "XAUTH" indicates an IKEv1 eXtended Authentication password. There should be one indice, 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 form
supported by ipsec_ttodata(3).
A raw 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. Note that most fields are now unused and filled in with the CKAID, which is a reference
to the location within the NSS database.
Post-quantum preshared keys can be static or dynamic. Token “PPKS” indicates that the following PPK will
be a static one, token “PPKF” indicates that the following PPK will be a dynamic one. In both cases, the
next token is a PPK_ID that uniquely represent the given PPK. PPK_ID must be represented as a sequence of
characters delimited by the double-quote character ("). If PPK is a static one, then the next token is a
PPK, otherwise the next token is a filename of a file that has a dynamic PPK. Dynamic PPK is one-time
pad. Dynamic PPK file has a offset in it's first token. This offset should be number delimited by the
double-quote character ("). Second token is a OTP which the PPK will be extracted from. Every time one
PPK hase been extracted, the offset is increased in the size of the PPK. When first time used, the offset
should be given in a format "00...00". PPK may be represented in any format which can be used for
representing a preshared secret.
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
SEE ALSO
The rest of the Libreswan distribution, in particular ipsec.conf(5), ipsec(8), ipsec_newhostkey(8), ipsec_rsasigkey(8), ipsec_showhostkey(8), ipsec_auto(8) --rereadsecrets, and pluto(8) --listen.
HISTORY
Originally designed for the FreeS/WAN project <http://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. All private key material is now stored in the NSS database. The fields of the raw RSA key currently filled with the CKAID might be ignored and removed in future versions.
BUGS
If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match %any6.
AUTHOR
Paul Wouters
libreswan secrets files