unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

IPSEC.SECRETS(5)                                              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 ipsec_pluto(8), the Open Internet Key Exchange daemon, to  authenti-
       cate  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  white-
       space  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
       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.


       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  pre-
       shared 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 authen-
       tication 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 authenti-
       cation.


       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  nor-
       mal 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.  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.


       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  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 follow-
       ing  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  pro-
       cessed before continuing with the current file. The filename is subject
       to globbing as in sh(1), so every file with a  matching  name  is  pro-
       cessed.  Includes  may  be nested to a modest depth (10, currently). If
       the filename doesn't start with a /, the directory containing the  cur-
       rent  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/: 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)