<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry>
  <refmeta>
    <refentrytitle>IPSEC.SECRETS</refentrytitle>
    <manvolnum>5</manvolnum>
    <refmiscinfo class='date'>25 September 2020</refmiscinfo>
    <refmiscinfo class="source">Libreswan</refmiscinfo>
    <refmiscinfo class="version">@@IPSECVERSION@@</refmiscinfo>
    <refmiscinfo class="manual">File formats and conventions</refmiscinfo>
  </refmeta>
  <refnamediv id='name'>
    <refname>ipsec.secrets</refname>
    <refpurpose>secrets for IKE/IPsec authentication</refpurpose>
  </refnamediv>
  <!-- body begins here -->
  <refsect1 id='description'>
    <title>DESCRIPTION</title>
    <para>
      The file <filename>ipsec.secrets</filename> 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.
    </para>

    <para>
      These secrets are used by
      <citerefentry><refentrytitle>pluto</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      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.
    </para>

    <para>
      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)
    </para>

    <para>
      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.
    </para>


    <programlisting><xi:include  href="ipsec.secrets.example"  parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>

    <para>
      Each entry in the file is a list of indices, followed by a secret.
      The two parts are separated by a colon (<emphasis>:</emphasis>) that is
      followed by whitespace or a newline.
    </para>

    <para>
      An index is an IP address, or a Fully Qualified
      Domain Name, user@FQDN, <emphasis>%any</emphasis>
      or <emphasis>%any6</emphasis> (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 (<emphasis>@</emphasis>).
    </para>

    <para>
      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 <emphasis>%any</emphasis> will match the
      peer's IP address if IPV4 and <emphasis>%any6</emphasis> will
      match a the peer's IP address if IPV6.
    </para>

    <para>
      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
      <command>ipsec rereadsecrets</command>.
      Note that currently there is no way to add a specific new entry - it's
      all or nothing.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      It is acceptable for two entries to be the best match as
      long as they agree about the secret.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      A preshared secret is most conveniently represented as a sequence of
      characters, delimited by the double-quote
      character (<emphasis>"</emphasis>).  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.
    </para>

    <para>
      Currently supported formats are hexadecimal, base64, and characters.
    </para>

    <para>
      A hexadecimal text value begins with a <emphasis>0x</emphasis>
      (or <emphasis>0X</emphasis>) 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 <emphasis>_</emphasis> (underscore)
      between consecutive groups is ignored, permitting punctuation to improve
      readability; doing this every eight digits seems about right.
    </para>

    <para>
      A base64 text value begins with a <emphasis>0s</emphasis>
      (or <emphasis>0S</emphasis>) 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 <varname role='parameter'>flags</varname> has the
      <emphasis>TTODATAV_IGNORESPACE</emphasis> bit on, blanks are ignore
      (after the prefix). Note that the last one or two digits of a base64 group
      can be <emphasis>=</emphasis> to indicate that fewer than three binary
      bytes are encoded.
    </para>

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

    <para>
      Post-quantum preshared keys (PPK) can be static. The token &ldquo;PPKS&rdquo;
      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
      (<emphasis>"</emphasis>). 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.
    </para>

    <para>
      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.
    </para>

    <para>
      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,
      <emphasis>#</emphasis> 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).
    </para>

    <para>
      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 <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      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 <emphasis>/</emphasis>, the directory containing the current
      file is prepended to the name.  The include directive is a line that
      starts with the word <emphasis>include</emphasis>, followed by
      whitespace, followed by the filename (which must not contain
      whitespace).
    </para>
  </refsect1>

  <refsect1 id='files'>
    <title>FILES</title>
    <para>
      <filename>@@IPSEC_SECRETS@@</filename>
    </para>
  </refsect1>

  <refsect1 id='see_also'>
    <title>SEE ALSO</title>
    <para>
      The rest of the Libreswan distribution, in particular
      <citerefentry><refentrytitle>ipsec.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ipsec</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ipsec-newhostkey</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ipsec-rsasigkey</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ipsec-showhostkey</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>ipsec-rereadsecrets</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      and <citerefentry><refentrytitle>ipsec-listen</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
    </para>
  </refsect1>

  <refsect1 id='history'>
    <title>HISTORY</title>
    <para>
      Originally designed for the FreeS/WAN project
      &lt;<ulink url='https://www.freeswan.org'>https://www.freeswan.org</ulink>&gt;
      by D. Hugh Redelmeier. Updated for Openswan by Ken Bantoft. Updated for
      Libreswan by Paul Wouters</para> <para>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.
    </para>
  </refsect1>

  <refsect1 id='bugs'><title>BUGS</title>
  <para>
    If an ID is <literal>0.0.0.0</literal>, it will match <emphasis>%any</emphasis>;
    if it is <emphasis>0::0</emphasis>, it will match <emphasis>%any6</emphasis>.
  </para>
  </refsect1>

  <refsect1 id='author'>
    <title>AUTHOR</title>
    <para>
      <author><personname><firstname>Paul</firstname><surname>Wouters</surname></personname></author>
    </para>
  </refsect1>
</refentry>