Provided by: openswan_2.4.4-3ubuntu1_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 ipsec_pluto(8), the  Open  Internet  Key  Exchange  daemon,  to
       authenticate  other  hosts.   Currently there are two kinds of secrets:
       preshared secrets and RSA private keys.

       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.  Each entry or directive must start at the left margin, but if
       it continues beyond a single  line,  each  continuation  line  must  be
       indented.

              # sample /etc/ipsec.secrets file for 10.1.0.1
              10.1.0.1 10.2.0.1: PSK "secret shared by two hosts"

              # 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"

              # an RSA private key.
              # note that the lines are too wide for a
              # man page, so ... has been substituted for
              # the truncated part
              @my.com: rsa {
                  Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt...
                  PublicExponent: 0sAw==
                  PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN...
                  Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l...
                  Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0...
                  Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r...
                  Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6...
                  Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ...
                  }

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

       Each entry in the file is a list of indices, followed by a secret.  The
       two parts are separated by a colon (:) that is followed  by  whitespace
       or  a  newline.  For compatability with the previous form of this file,
       if the key part is just a double-quoted string the colon  may  be  left
       out.

       An index is an IP address, or 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 (or in any of the forms supported  by  the  Openswan
       ipsec_ttoaddr(3)  routine).   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  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 %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.

       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
       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.   If  the  key is for an asymmetric
       authentication technique (i.e. a public key system  such  as  RSA),  an
       entry with multiple indices will match a host and peer even if only the
       host ID matches an index (it is presumed that the multiple indices  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  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.

       Authentication by RSA Signatures 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-index and one-
       index forms of entry often make sense for RSA Signature authentication.

       The  key part of an entry may start with a token indicating the kind of
       key.  ‘‘RSA’’ signifies RSA private key and ‘‘PSK’’ signifies PreShared
       Key  (case  is ignored).  For compatability with previous forms of this
       file, PSK is the default.

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

       An RSA private key is a composite of  eight  generally  large  numbers.
       The  notation  used  is  a  brace-enclosed list of field name and value
       pairs (see the example above).  A suitable key, in a  suitable  format,
       may  be generated by ipsec_rsasigkey(8).  The structure is very similar
       to that used by BIND 8.2.2 or later, but note  that  the  numbers  must
       have  a  ‘‘0s’’ prefix if they are in base 64.  The order of the fields
       is fixed.

       The first token 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.

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

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

FILES

       /etc/ipsec.secrets

SEE ALSO

       The  rest  of  the  Openswan distribution, in particular ipsec.conf(5),
       ipsec(8),           ipsec_newhostkey(8),            ipsec_rsasigkey(8),
       ipsec_showhostkey(8), ipsec_auto(8) --rereadsecrets, and ipsec_pluto(8)
       --listen,.
       BIND 8.2.2 or later, ftp://ftp.isc.org/isc/bind/src/

HISTORY

       Originally designed for the FreeS/WAN project <http://www.freeswan.org>
       by D. Hugh Redelmeier.

BUGS

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

                                 28 March 1999                IPSEC.SECRETS(5)