bionic (5) ipsec.secrets.5.gz

Provided by: strongswan-starter_5.6.2-1ubuntu2.9_amd64 bug

NAME

       ipsec.secrets - secrets for IKE/IPsec authentication

DESCRIPTION

       The  file  ipsec.secrets holds a table of secrets.  These secrets are used by the strongSwan Internet Key
       Exchange (IKE) daemons pluto (IKEv1) and charon (IKEv2) to authenticate other hosts.

       It is vital that these secrets be protected.  The file  should  be  owned  by  the  super-user,  and  its
       permissions should be set to block all access by others.

       The file is a sequence of entries and include directives.  Here is an example.

              # /etc/ipsec.secrets - strongSwan IPsec secrets file
              192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"

              : RSA moonKey.pem

              alice@strongswan.org : EAP "x3.dEhgN"

              carol : XAUTH "4iChxLT3"

              dave  : XAUTH "ryftzG4A"

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

       Each  entry  in  the  file  is  a list of optional ID selectors, followed by a secret.  The two parts are
       separated by a colon (:) that is surrounded by whitespace. If no ID selectors are specified the line must
       start with a colon.

       A  selector  is  an  IP address, a Fully Qualified Domain Name, user@FQDN, %any or %any6 (other kinds may
       come).

       Matching IDs with selectors 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, a selector of %any will match the peer's IP address if IPV4 and %any6 will match a the peer's IP
       address if IPV6.  Currently, the obsolete notation 0.0.0.0 may be used in place of %any.

       In IKEv1 an additional complexity arises in the case of authentication by preshared secret: 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.

       To  authenticate  a  connection  between two hosts, the entry that most specifically matches the host and
       peer IDs is used.  An entry with no selectors will match any host and peer.  More specifically, an  entry
       with  one  selector  will  match  a  host  and peer if the selector matches the host's ID (the peer isn't
       considered).  Still more specifically, an entry with multiple selectors will match a host and peer if the
       host  ID  and  peer  ID  each match one of the selectors.  If the key is for an asymmetric authentication
       technique (i.e. a public key system such as RSA), an entry with multiple selectors will match a host  and
       peer even if only the host ID matches a selector (it is presumed that the selectors 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  selector  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-selector entries are best  for
       PSK authentication.

       Authentication  by  public  key  systems such as RSA 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 thus no-selector and one-selector forms of
       entry often make sense for public key authentication.

       The key part of an entry must start with a token indicating the kind of  key.   The  following  types  of
       secrets are currently supported:

       PSK    defines a pre-shared key

       RSA    defines an RSA private key

       ECDSA  defines an ECDSA private key

       P12    defines a PKCS#12 container

       EAP    defines EAP credentials

       NTLM   defines NTLM credentials

       XAUTH  defines XAUTH credentials

       PIN    defines a smartcard PIN

       Details on each type of secret are given below.

       Whitespace  at  the  end  of  a  line  is  ignored. At the start of a line or after whitespace, # and the
       following text up to the end of the line is treated as a comment.

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

   TYPES OF SECRETS
       [ <selectors> ] : PSK <secret>
              A  preshared  secret  is  most  conveniently  represented  as  a  sequence of characters, which is
              delimited by double-quote characters (").  The sequence cannot  contain  newline  or  double-quote
              characters.
              Alternatively,  preshared  secrets  can  be  represented  as  hexadecimal or Base64 encoded binary
              values. A character sequence beginning with 0x is interpreted as sequence of  hexadecimal  digits.
              Similarly, a character sequence beginning with 0s is interpreted as Base64 encoded binary data.

       : RSA <private key file> [ <passphrase> | %prompt ]
       : ECDSA <private key file> [ <passphrase> | %prompt ]
              For  the  private  key  file  both  absolute  paths  or paths relative to /etc/ipsec.d/private are
              accepted. If the private key file is encrypted, the passphrase  must  be  defined.  Instead  of  a
              passphrase  %prompt  can  be  used  which  then causes the daemon to ask the user for the password
              whenever it is required to decrypt the key.

       : P12 <PKCS#12 file> [ <passphrase> | %prompt ]
              For the PKCS#12 file both absolute paths or paths relative to /etc/ipsec.d/private  are  accepted.
              If the container is encrypted, the passphrase must be defined. Instead of a passphrase %prompt can
              be used which then causes the daemon to ask the user for the password whenever it is  required  to
              decrypt  the container. Private keys, client and CA certificates are extracted from the container.
              To use such a client certificate in a connection  set  leftid  to  one  of  the  subjects  of  the
              certificate.

       <user id> : EAP <secret>
              The format of secret is the same as that of PSK secrets.
              EAP secrets are IKEv2 only.

       <user id> : NTLM <secret>
              The  format  of  secret is the same as that of PSK secrets, but the secret is stored as NTLM hash,
              which is MD4(UTF-16LE(secret)), instead of as cleartext.
              NTLM secrets can only be used with the eap-mschapv2 plugin.

       [ <servername> ] <username> : XAUTH <password>
              The format of password is the same as that of PSK secrets.  XAUTH secrets are IKEv1 only.

       : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt
              The smartcard selector always requires a keyid to uniquely select the correct key. The slot number
              defines  the  slot  on  the  token,  the  module  name  refers  to  the  module  name  defined  in
              strongswan.conf(5).  Instead of specifying the pin code  statically,  %prompt  can  be  specified,
              which causes the daemon to ask the user for the pin code.

FILES

       /etc/ipsec.secrets

SEE ALSO

       ipsec.conf(5), strongswan.conf(5), ipsec(8)

HISTORY

       Originally  written  for  the  FreeS/WAN  project  by  D.  Hugh Redelmeier.  Updated and extended for the
       strongSwan project <http://www.strongswan.org> by Tobias Brunner and Andreas Steffen.

BUGS

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