'\" t .\" Title: IPSEC.SECRETS .\" Author: Paul Wouters .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/12/2024 .\" Manual: Executable programs .\" Source: libreswan .\" Language: English .\" .TH "IPSEC\&.SECRETS" "5" "03/12/2024" "libreswan" "Executable programs" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" ipsec.secrets \- secrets for IKE/IPsec authentication .SH "DESCRIPTION" .PP 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\&. .PP These secrets are used by \fBpluto\fR(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\&. .PP 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) .PP 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\&. .sp .if n \{\ .RS 4 .\} .nf # 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 .fi .if n \{\ .RE .\} .sp Each entry in the file is a list of indices, followed by a secret\&. The two parts are separated by a colon (\fB:\fR) that is followed by whitespace or a newline\&. .PP An index is an IP address, or a Fully Qualified Domain Name, user@FQDN, \fB%any\fR or \fB%any6\fR (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 (\fB@\fR)\&. .PP 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\*(Aqs ID, and it is in the form of an IP address, an index of \fB%any\fR will match the peer\*(Aqs IP address if IPV4 and \fB%any6\fR will match a the peer\*(Aqs IP address if IPV6\&. .PP 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 \fBipsec secrets\fR or \fBipsec auto \-\-rereadsecrets\fR\&. Note that currently there is no way to add a specific new entry \- it\*(Aqs all or nothing\&. .PP 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\&. .PP 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\*(Aqs 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\&. .PP 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\*(Aqs ID (the peer isn\*(Aqt 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\&. .PP 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\&. .PP When running in FIPS mode, PSK\*(Aqs need to comply to a minimum strength requirement depending on the integrity and PRF algorithm used\&. It is recommended not to use PSK\*(Aqs shorter then 64 random characters\&. .PP 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\&. .PP A preshared secret is most conveniently represented as a sequence of characters, delimited by the double\-quote character (\fB"\fR)\&. 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\&. .PP Currently supported formats are hexadecimal, base64, and characters\&. .PP A hexadecimal text value begins with a \fB0x\fR (or \fB0X\fR) 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 \fB_\fR (underscore) between consecutive groups is ignored, permitting punctuation to improve readability; doing this every eight digits seems about right\&. .PP A base64 text value begins with a \fB0s\fR (or \fB0S\fR) 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 \fIflags\fR has the \fBTTODATAV_IGNORESPACE\fR bit on, blanks are ignore (after the prefix)\&. Note that the last one or two digits of a base64 group can be \fB=\fR to indicate that fewer than three binary bytes are encoded\&. .PP A character text value begins with a \fB0t\fR (or \fB0T\fR) prefix and continues with text characters, each being the value of one binary byte\&. .PP Post\-quantum preshared keys (PPK) can be static\&. The token \(lqPPKS\(rq 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 (\fB"\fR)\&. 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\&. .PP 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\&. .PP 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, \fB#\fR 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)\&. .PP 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 \fBsh\fR(1), so every file with a matching name is processed\&. Includes may be nested to a modest depth (10, currently)\&. If the filename doesn\*(Aqt start with a \fB/\fR, the directory containing the current file is prepended to the name\&. The include directive is a line that starts with the word \fBinclude\fR, followed by whitespace, followed by the filename (which must not contain whitespace)\&. .SH "FILES" .PP /etc/ipsec\&.secrets .SH "SEE ALSO" .PP The rest of the Libreswan distribution, in particular \fBipsec.conf\fR(5), \fBipsec\fR(8), \fBipsec_newhostkey\fR(8), \fBipsec_rsasigkey\fR(8), \fBipsec_showhostkey\fR(8), \fBipsec_auto\fR(8) \fB\-\-rereadsecrets\fR, and \fBpluto\fR(8) \fB\-\-listen\fR\&. .SH "HISTORY" .PP Originally designed for the FreeS/WAN project <\m[blue]\fBhttps://www\&.freeswan\&.org\fR\m[]> by D\&. Hugh Redelmeier\&. Updated for Openswan by Ken Bantoft\&. Updated for Libreswan by Paul Wouters .PP 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\&. .SH "BUGS" .PP If an ID is 0\&.0\&.0\&.0, it will match \fB%any\fR; if it is \fB0::0\fR, it will match \fB%any6\fR\&. .SH "AUTHOR" .PP \fBPaul Wouters\fR .RS 4 libreswan secrets files .RE