Provided by: strongswan-starter_4.5.2-1.1ubuntu1_i386 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).  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.  In many cases it is a bad idea to use domain names
       because  the  name  server  may  not be running or may be insecure.  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 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

       EAP    defines EAP 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,  delimited  by  double-quote  characters
              (").   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).

       [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ]
       [ <selectors> ] : 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 daemons to
              ask the user for the password whenever it is required to decrypt
              the key.

       <user id> : EAP <secret>
              As  with  PSK  secrets  the  secret is a sequence of characters,
              delimited by double-quote characters (").
              EAP secrets are IKEv2 only.

       [ <servername> ] <username> : XAUTH <password>
              XAUTH secrets are IKEv1 only.

       : PIN <smartcard selector> <pin code> | %prompt
              IKEv1  uses  the  format  %smartcard[<slot  nr>[:<key  id>]]  to
              specify the smartcard selector (e.g. %smartcard1:50).  The IKEv2
              daemon   supports   multiple    modules    with    the    format
              %smartcard[<slot nr>[@<module>]]:<keyid> , but always requires a
              keyid to uniquely select the correct key. Instead of  specifying
              the  pin code statically, %prompt can be specified, which causes
              the daemons 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.