IPSEC.SECRETS(5)                                                    strongSwan                                                    IPSEC.SECRETS(5)

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 sur-
       rounded 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  sub-
       ject  to  ``globbing''  as  in  sh(1), so every file with a matching name is processed.  Includes may be nested to a modest depth (10, cur-
       rently).  If the filename doesn't start with a /, the directory containing the current file is prepended to the name.  The  include  direc-
       tive 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.

4.5.2                                                               2010-05-30                                                    IPSEC.SECRETS(5)