Provided by: openswan_2.4.12+dfsg-1.3_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 four kinds of secrets:
       preshared secrets, RSA private  keys,  passwords/PIN  codes  for  X.509
       certificates   and   if  compiled  with  USE_SMARTCARD=true,  there  is
       additional support for storing the PINCODES of smartcards or USB tokens

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

       # An X.509 pem encoded private key file with (optional) passphrase
       : RSA vpnserverKey.pem "<optional passphrase>"
       # An X.509 pem encoded private key file locked with a passphrase
       :  RSA vpnserverKey.pem %prompt

       # Entering a PIN code for a smartcard
       : PIN %smartcard "12345678"
       # For multiple smartcards use:
       : PIN %smartcard<reader nr>:<PKCS#15 key id>"<PIN code>"
       # or if you want to interactively type in the pin code
       : PIN %smartcard %prompt

       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. If filenames are not absolute paths, they are relative  to
       the ipsec.d/private/ directory.

       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
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 2any will match the peer’s IP address if IPV4 and 2any6 will match a the peer’s IP address if IPV6. Currently, the obsolete notation 0.0.0.0 may be used in place of 2any.
       equal. In the case of a â

       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  ipsec  secrets or ipsec auto --rereadsecrets. If there are any
       keyfiles or smartcards protected by a passphrase or pin using  %prompt,
       you  will  be  prompted  again  to enter these passphrases. To skip the
       prompting, just hit return to skip unlocking  that  particular  private
       key.

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

       If the RSA points to a filename, this is assumed to be a PEM (or  DER?)
       encoded  X.509  private key. The private key may be protected by a 3DES
       encryption. 1DES encrypted key files will be rejected. If  the  private
       key  is  protected by a passphrase and this passphrase is not specified
       in ipsec.secrets, the connection cannot be automatically started  using
       auto=start,  but  instead  must  be  brought  up  using ipsec auto --up
       connname, upon which the user will be prompted for  the  passphrase  to
       unlock  the  private  key  belonging  to the X.509 certificate. PKCS#12
       files, which include the private  key  file,  cannot  be  specified  in
       ipsec.secrets.  Private  keys can be extracted from PKCS#12 files using
       the following command: openssl pkcs12 -nocerts -in clientCert.p12  -out
       clientKey.pem

       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 â

       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
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).
       subject to â

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/: ftp://ftp.isc.org/isc/bind/src/

HISTORY

       Originally designed for the FreeS/WAN project <http://www.freeswan.org:
       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.

                                                              IPSEC.SECRETS(5)