freeswan/pluto/ipsec.secrets.5

   1 .TH IPSEC.SECRETS 5 "28 March 1999"
   2 .SH NAME
   3 ipsec.secrets \- secrets for IKE/IPsec authentication
   4 .SH DESCRIPTION
   5 The file \fIipsec.secrets\fP holds a table of secrets.
   6 These secrets are used by \fIipsec_pluto\fP(8), the FreeS/WAN Internet Key
   7 Exchange daemon, to authenticate other hosts.
   8 Currently there are two kinds of secrets: preshared secrets and
   9 .\" the private part of DSS keys.
  10 RSA private keys.
  11 .LP
  12 It is vital that these secrets be protected.  The file should be owned
  13 by the super-user,
  14 and its permissions should be set to block all access by others.
  15 .LP
  16 The file is a sequence of entries and include directives.
  17 Here is an example.  Each entry or directive must start at the
  18 left margin, but if it continues beyond a single line, each continuation
  19 line must be indented.
  20 .LP
  21 .RS
  22 .nf
  23 # sample /etc/ipsec.secrets file for 10.1.0.1
  24 10.1.0.1 10.2.0.1: PSK "secret shared by two hosts"
  25
  26 # an entry may be split across lines,
  27 # but indentation matters
  28 www.xs4all.nl @www.kremvax.ru
  29 \ \ \ \ 10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5"
  30
  31 .\" # Private part of our DSS key, in base 64,
  32 .\" # as generated by BIND 8.2.1's dnskeygen.
  33 .\" # Since this is the default key for this host,
  34 .\" # there is no need to specify indices.
  35 .\" : DSS 0siMs0N/hfRoCBMXA6plPtuv58/+c=
  36 # an RSA private key.
  37 # note that the lines are too wide for a
  38 # man page, so ... has been substituted for
  39 # the truncated part
  40 @my.com: rsa {
  41 \ \ \ \ Modulus:\ 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt...
  42 \ \ \ \ PublicExponent:\ 0sAw==
  43 \ \ \ \ PrivateExponent:\ 0shlGbVR1m8Z+7rhzSyenCaBN...
  44 \ \ \ \ Prime1:\ 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l...
  45 \ \ \ \ Prime2:\ 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0...
  46 \ \ \ \ Exponent1:\ 0soaXj85ihM5M2inVf/NfHmtLutVz4r...
  47 \ \ \ \ Exponent2:\ 0sjdAL9VFizF+BKU4ohguJFzOd55OG6...
  48 \ \ \ \ Coefficient:\ 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ...
  49 \ \ \ \ }
  50
  51 include ipsec.*.secrets # get secrets from other files
  52 .fi
  53 .RE
  54 .LP
  55 Each entry in the file is a list of indices, followed by a secret.
  56 The two parts are separated by a colon (\fB:\fP) that is
  57 followed by whitespace or a newline.  For compatability
  58 with the previous form of this file, if the key part is just a
  59 double-quoted string the colon may be left out.
  60 .LP
  61 An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
  62 \fB%any\fP or \fB%any6\fP (other kinds may come).  An IP address may be written
  63 in the familiar dotted quad form or as a domain name to be looked up
  64 when the file is loaded
  65 (or in any of the forms supported by the FreeS/WAN \fIipsec_ttoaddr\fP(3)
  66 routine).  In many cases it is a bad idea to use domain names because
  67 the name server may not be running or may be insecure.  To denote a
  68 Fully Qualified Domain Name (as opposed to an IP address denoted by
  69 its domain name), precede the name with an at sign (\fB@\fP).
  70 .LP
  71 Matching IDs with indices is fairly straightforward: they have to be
  72 equal.  In the case of a ``Road Warrior'' connection, if an equal
  73 match is not found for the Peer's ID, and it is in the form of an IP
  74 address, an index of \fB%any\fP will match the peer's IP address if IPV4
  75 and \fB%any6\fP will match a the peer's IP address if IPV6.
  76 Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
  77 \fB%any\fP.
  78 .LP
  79 An additional complexity
  80 arises in the case of authentication by preshared secret: the
  81 responder will need to look up the secret before the Peer's ID payload has
  82 been decoded, so the ID used will be the IP address.
  83 .LP
  84 To authenticate a connection between two hosts, the entry that most
  85 specifically matches the host and peer IDs is used.  An entry with no
  86 index will match any host and peer.  More specifically, an entry with one index will
  87 match a host and peer if the index matches the host's ID (the peer isn't
  88 considered).  Still more specifically, an entry with multiple indices will match a host and
  89 peer if the host ID and peer ID each match one of the indices.  If the key
  90 is for an asymmetric authentication technique (i.e. a public key
  91 system such as RSA), an entry with multiple indices will match a host
  92 and peer even if only the host ID matches an index (it is presumed that the
  93 multiple indices are all identities of the host).
  94 It is acceptable for two entries to be the best match as
  95 long as they agree about the secret or private key.
  96 .LP
  97 Authentication by preshared secret requires that both systems find the
  98 identical secret (the secret is not actually transmitted by the IKE
  99 protocol).  If both the host and peer appear in the index list, the
 100 same entry will be suitable for both systems so verbatim copying
 101 between systems can be used.  This naturally extends to larger groups
 102 sharing the same secret.  Thus multiple-index entries are best for PSK
 103 authentication.
 104 .LP
 105 Authentication by RSA Signatures requires that each host have its own private
 106 key.  A host could reasonably use a different private keys
 107 for different interfaces and for different peers.  But it would not
 108 be normal to share entries between systems.  Thus thus no-index and
 109 one-index forms of entry often make sense for RSA Signature authentication.
 110 .LP
 111 The key part of an entry may start with a token indicating the kind of
 112 key.  ``RSA'' signifies RSA private key and ``PSK'' signifies
 113 PreShared Key (case is ignored).  For compatability with previous
 114 forms of this file, PSK is the default.
 115 .LP
 116 A preshared secret is most conveniently represented as a sequence of
 117 characters, delimited by the double-quote
 118 character (\fB"\fP).  The sequence cannot contain a newline or
 119 double-quote.  Strictly speaking, the secret is actually the sequence
 120 of bytes that is used in the file to represent the sequence of
 121 characters (excluding the delimiters).
 122 A preshared secret may also be represented in any form supported by
 123 \fIipsec_atodata\fP(3).
 124 .LP
 125 An RSA private key is a composite of eight generally large numbers.  The notation
 126 used is a brace-enclosed list of field name and value pairs (see the example above).
 127 A suitable key, in a suitable format, may be generated by \fIipsec_rsasigkey\fP(8).
 128 The structure is very similar to that used by BIND 8.2.2, but note that
 129 the numbers must have a ``0s'' prefix if they are in base 64.  The order of
 130 the fields is fixed.
 131 .LP
 132 The first token an entry must start in
 133 the first column of its line.  Subsequent tokens must be
 134 separated by whitespace,
 135 except for a colon token, which only needs to be followed by whitespace.
 136 A newline is taken as whitespace, but every
 137 line of an entry after the first must be indented.
 138 .LP
 139 Whitespace at the end of a line is ignored (except in the 0t
 140 notation for a key).  At the start of line or
 141 after whitespace, \fB#\fP and the following text up to the end of the
 142 line is treated as a comment.  Within entries, all lines must be
 143 indented (except for lines with no tokens).
 144 Outside entries, no line may be indented (this is to make sure that
 145 the file layout reflects its structure).
 146 .LP
 147 An include directive causes the contents of the named file to be processed
 148 before continuing with the current file.  The filename is subject to
 149 ``globbing'' as in \fIsh\fP(1), so every file with a matching name
 150 is processed.  Includes may be nested to a modest
 151 depth (10, currently).  If the filename doesn't start with a \fB/\fP, the
 152 directory containing the current file is prepended to the name.  The
 153 include directive is a line that starts with the word \fBinclude\fP,
 154 followed by whitespace, followed by the filename (which must not contain
 155 whitespace).
 156 .SH FILES
 157 /etc/ipsec.secrets
 158 .SH SEE ALSO
 159 The rest of the FreeS/WAN distribution, in particular
 160 \fIipsec\fP(8), \fIipsec_rsasigkey\fP(8), and \fIipsec_pluto\fP(8).
 161 .br
 162 BIND 8.2.2, ftp://ftp.isc.org/isc/bind/src/
 163 .SH HISTORY
 164 Designed for the FreeS/WAN project
 165 <http://www.freeswan.org>
 166 by D. Hugh Redelmeier.
 167 .SH BUGS
 168 If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
 169 if it is \fB0::0\fP, it will match \fB%any6\fP.