contrib/ntp/html/genkeys.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2 <html>
   3 <head>
   4 <meta name="generator" content="HTML Tidy, see www.w3.org">
   5 <title>ntp-genkeys - generate public and private keys</title>
   6 </head>
   7 <body>
   8 <h3><tt>ntp-genkeys</tt> - generate public and private keys</h3>
   9
  10 <img align="left" src="pic/alice23.gif" alt="gif"><a href=
  11 "http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's
  12 Adventures in Wonderland</i>, Lewis Carroll</a>
  13
  14 <p>Alice holds the key.<br clear="left">
  15 </p>
  16
  17 <hr>
  18 <h4>Synopsis</h4>
  19
  20 <tt>ntp-genkeys</tt>
  21
  22 <h4>Description</h4>
  23
  24 <p>This program generates random keys used by either or both the
  25 NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey)
  26 cryptographic authentication schemes. By default the program
  27 generates the <tt>ntp.keys</tt> file containing 16 random symmetric
  28 keys. In addition, if the <tt>rsaref20</tt> package is configured
  29 for the software build, the program generates cryptographic values
  30 used by the Autokey scheme. These values are incorporated as a set
  31 of three files, <tt>ntpkey</tt> containing the RSA private key,
  32 <tt>ntpkey_<i>host</i></tt> containing the RSA public key, where
  33 <tt><i>host</i></tt> is the DNS name of the generating machine, and
  34 <tt>ntpkey_dh</tt> containing the parameters for the Diffie-Hellman
  35 key-agreement algorithm. All files and are in printable ASCII
  36 format. A timestamp in NTP seconds is appended to each. Since the
  37 algorithms are seeded by the system clock, each run of this program
  38 produces a different file and file name.</p>
  39
  40 <p>The <tt>ntp.keys</tt> file contains 16 MD5 keys. Each key
  41 consists of 16 characters randomized over the ASCII 95-character
  42 printing subset. The file is read by the daemon at the location
  43 specified by the <tt>keys</tt> configuration file command and made
  44 visible only to root. An additional key consisting of a easily
  45 remembered password should be added by hand for use with the <tt>
  46 ntpq</tt> and <tt>ntpdc</tt> programs. The file must be distributed
  47 by secure means to other servers and clients sharing the same
  48 security compartment. While the key identifiers for MD5 and DES
  49 keys must be in the range 1-65534, inclusive, the <tt>
  50 ntp-genkeys</tt> program uses only the identifiers from 1 to 16.
  51 The key identifier for each association is specified as the key
  52 argument in the <tt>server</tt> or peer configuration file
  53 command.</p>
  54
  55 <p>The <tt>ntpkey</tt> file contains the RSA private key. It is
  56 read by the daemon at the location specified by the <tt>
  57 privatekey</tt> argument of the <tt>crypto</tt> configuration file
  58 command and made visible only to root. This file is useful only to
  59 the machine that generated it and never shared with any other
  60 daemon or application program.</p>
  61
  62 <p>The <tt>ntpkey_<i>host</i></tt> file contains the RSA public
  63 key, where <tt><i>host</i></tt> is the DNS name of the host that
  64 generated it. The file is read by the daemon at the location
  65 specified by the <tt>publickey</tt> argument to the <tt>server</tt>
  66 or <tt>peer</tt> configuration file command. This file can be
  67 widely distributed and stored without using secure means, since the
  68 data are public values.</p>
  69
  70 <p>The <tt>ntp_dh</tt> file contains two Diffie-Hellman parameters:
  71 the prime modulus and the generator. The file is read by the daemon
  72 at the location specified by the <tt>dhparams</tt> argument of the
  73 <tt>crypto</tt> configuration file command. The file can be
  74 distributed by insecure means to other servers and clients sharing
  75 the same key agreement compartment, since the data are public
  76 values.</p>
  77
  78 <p>The file formats begin with two lines, the first containing the
  79 generating system DNS name and the second the datestamp. Lines
  80 beginning with <tt>#</tt> are considered comments and ignored by
  81 the daemon. In the <tt>ntp.keys</tt> file, the next 16 lines
  82 contain the MD5 keys in order. If necessary, this file can be
  83 further customized by an ordinary text editor. The format is
  84 described in the following section. In the <tt>ntpkey</tt> and <tt>
  85 ntpkey_<i>host</i></tt> files, the next line contains the modulus
  86 length in bits followed by the key as a PEM encoded string. In the
  87 <tt>ntpkey_dh</tt> file, the next line contains the prime length in
  88 bytes followed by the prime as a PEM encoded string, and the next
  89 and final line contains the generator length in bytes followed by
  90 the generator as a PEM encoded string.</p>
  91
  92 <p>Note: See the file <tt>./source/rsaref.h</tt> in the <tt>
  93 rsaref20</tt> package for explanation of return values, if
  94 necessary.</p>
  95
  96 <h4>Symmetric Key File Format</h4>
  97
  98 In the case of DES, the keys are 56 bits long with, depending on
  99 type, a parity check on each byte. In the case of MD5, the keys are
 100 64 bits (8 bytes). <tt>ntpd</tt> reads its keys from a file
 101 specified using the <tt>-k</tt> command line option or the <tt>
 102 keys</tt> statement in the configuration file. While key number 0
 103 is fixed by the NTP standard (as 56 zero bits) and may not be
 104 changed, one or more of the keys numbered 1 through 15 may be
 105 arbitrarily set in the keys file.
 106
 107 <p>The key file uses the same comment conventions as the
 108 configuration file. Key entries use a fixed format of the form</p>
 109
 110 <p><i><tt>keyno type key</tt></i></p>
 111
 112 <p>where <i><tt>keyno</tt></i> is a positive integer, <i><tt>
 113 type</tt></i> is a single character which defines the key format,
 114 and <i><tt>key</tt></i> is the key itself.</p>
 115
 116 <p>The key may be given in one of three different formats,
 117 controlled by the <i><tt>type</tt></i> character. The three key
 118 types, and corresponding formats, are listed following.</p>
 119
 120 <dl>
 121 <dt><tt>S</tt></dt>
 122
 123 <dd>The key is a 64-bit hexadecimal number in the format specified
 124 in the DES specification; that is, the high order seven bits of
 125 each octet are used to form the 56-bit key while the low order bit
 126 of each octet is given a value such that odd parity is maintained
 127 for the octet. Leading zeroes must be specified (i.e., the key must
 128 be exactly 16 hex digits long) and odd parity must be maintained.
 129 Hence a zero key, in standard format, would be given as <tt>
 130 0101010101010101</tt>.</dd>
 131
 132 <dt><tt>N</tt></dt>
 133
 134 <dd>The key is a 64-bit hexadecimal number in the format specified
 135 in the NTP standard. This is the same as the DES format, except the
 136 bits in each octet have been rotated one bit right so that the
 137 parity bit is now the high order bit of the octet. Leading zeroes
 138 must be specified and odd parity must be maintained. A zero key in
 139 NTP format would be specified as <tt>8080808080808080</tt>.</dd>
 140
 141 <dt><tt>A</tt></dt>
 142
 143 <dd>The key is a 1-to-8 character ASCII string. A key is formed
 144 from this by using the low order 7 bits of each ASCII character in
 145 the string, with zeroes added on the right when necessary to form a
 146 full width 56-bit key, in the same way that encryption keys are
 147 formed from Unix passwords.</dd>
 148
 149 <dt><tt>M</tt></dt>
 150
 151 <dd>The key is a 1-to-8 character ASCII string, using the MD5
 152 authentication scheme. Note that both the keys and the
 153 authentication schemes (DES or MD5) must be identical between a set
 154 of peers sharing the same key number.</dd>
 155 </dl>
 156
 157 <p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt>
 158 programs are checked against passwords requested by the programs
 159 and entered by hand, so it is generally appropriate to specify
 160 these keys in ASCII format.</p>
 161
 162 <h4>Files</h4>
 163
 164 The RSA Laboratories package <tt>rsaref20</tt> of cryptographic
 165 routines is necessary in order to build and use this program.
 166
 167 <h4>Bugs</h4>
 168
 169 It can take quite a while to generate the RSA public/private key
 170 pair and Diffie-Hellman parameters, from a few seconds on a modern
 171 workstation to several minutes on older machines.
 172
 173 <hr>
 174 <a href="index.htm"><img align="left" src="pic/home.gif" alt=
 175 "gif"></a>
 176
 177 <address><a href="mailto:mills@udel.edu">David L. Mills
 178 &lt;mills@udel.edu&gt;</a></address>
 179 </body>
 180 </html>
 181