contrib/ntp/html/keygen.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   5     <meta name="generator" content="HTML Tidy, see www.w3.org">
   6     <title>ntp-keygen - generate public and private keys</title>
   7     <link href="scripts/style.css" type="text/css" rel="stylesheet">
   8   </head>
   9   <body>
  10     <h3><tt>ntp-keygen</tt> - generate public and private keys</h3>
  11     <p><img src="pic/alice23.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a></p>
  12     <p>Alice holds the key.</p>
  13     <p>Last update:
  14       <!-- #BeginDate format:En2m -->11-Jan-2018  11:55<!-- #EndDate -->
  15       UTC</p>
  16     <br clear="left">
  17     <h4>Related Links</h4>
  18     <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
  19     <h4>Table of Contents</h4>
  20     <ul>
  21       <li class="inline"><a href="#synop">Synopsis</a></li>
  22       <li class="inline"><a href="#descrip">Description</a></li>
  23       <li class="inline"><a href="#run">Running the program</a></li>
  24       <li class="inline"><a href="#cmd">Command Line Options</a></li>
  25       <li class="inline"><a href="#rand">Random Seed File</a></li>
  26       <li class="inline"><a href="#fmt">Cryptographic Data Files</a></li>
  27       <li class="inline"><a href="#bug">Bugs</a></li>
  28     </ul>
  29     <hr>
  30     <h4 id="synop">Synopsis</h4>
  31     <p id="intro"><tt>ntp-keygen [ -deGHIMPT ] [ -b <i>modulus</i> ] [ -c [ RSA-MD2 | RSA-MD5 | RSA-SHA
  32         | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ]
  33         [ -C <i>cipher</i> ] [-i <i>group</i> ] [ -l <em>days</em>]
  34         [ -m <i>modulus</i> ]  [ -p <i>passwd1</i> ] [ -q <i>passwd2</i> ]
  35         [ -S [ RSA | DSA ] ] [ -s <i>host</i> ] [ -V <i>nkeys</i> ]</tt></p>
  36     <h4 id="descrip">Description</h4>
  37     <p>This program generates cryptographic data files used by the NTPv4
  38       authentication and identity schemes.  It can generate message digest keys
  39       used in symmetric key cryptography and, if the OpenSSL software library
  40       has been installed, it can generate host keys, sign keys, certificates,
  41       and identity keys and parameters used by the Autokey public key
  42       cryptography.  The message digest keys file is generated in a format
  43       compatible with NTPv3.  All other files are in PEM-encoded printable ASCII
  44       format so they can be embedded as MIME attachments in mail to other
  45       sites.</p>
  46     <p>When used to generate message digest keys, the program produces a file
  47       containing ten pseudo-random printable ASCII strings suitable for the MD5
  48       message digest algorithm included in the distribution.  If the OpenSSL
  49       library is installed, it produces an additional ten hex-encoded random bit
  50       strings suitable for the SHA1, AES-128 CMAC, and other message digest
  51       algorithms.  The message digest keys file must be distributed and stored
  52       using secure means beyond the scope of NTP itself.  Besides the keys used
  53       for ordinary NTP associations, additional keys can be defined as passwords
  54       for the <tt><a href="ntpq.html">ntpq</a></tt>
  55       and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs.</p>
  56     <p>The remaining generated files are compatible with other OpenSSL
  57       applications and other Public Key Infrastructure (PKI)
  58       resources.  Certificates generated by this program are compatible with
  59       extant industry practice, although some users might find the
  60       interpretation of X509v3 extension fields somewhat liberal.  However,
  61       the identity keys are probably not compatible with anything other than
  62       Autokey.</p>
  63     <p>Some files used by this program are encrypted using a private
  64       password.  The <tt>-p</tt> option specifies the password for local
  65       encrypted files and the <tt>-q</tt> option the password for encrypted
  66       files sent to remote sites.  If no password is specified, the host name
  67       returned by the Unix <tt>gethostname()</tt> function, normally the DNS
  68       name of the host, is used.</p>
  69     <p>The <tt>pw</tt> option of the <tt>crypto</tt> configuration command
  70       specifies the read password for previously encrypted local files.
  71       This must match the local password used by this program.  If not
  72       specified, the host name is used.  Thus, if files are generated by
  73       this program without password, they can be read back by <tt>ntpd</tt>
  74       without password, but only on the same host.</p>
  75     <p>Normally, encrypted files for each host are generated by that host
  76       and used only by that host, although exceptions exist as noted later
  77       on this page.  The symmetric keys file, normally
  78       called <tt>ntp.keys</tt>, is usually installed in <tt>/etc</tt>.
  79       Other files and links are usually installed
  80       in <tt>/usr/local/etc</tt>, which is normally in a shared filesystem
  81       in NFS-mounted networks and cannot be changed by shared clients.  The
  82       location of the keys directory can be changed by the <tt>keysdir</tt>
  83       configuration command in such cases.  Normally, this is
  84       in <tt>/etc</tt>.</p>
  85     <p>This program directs commentary and error messages to the standard
  86       error stream <tt>stderr</tt> and remote files to the standard output
  87       stream <tt>stdout</tt> where they can be piped to other applications
  88       or redirected to files.  The names used for generated files and links
  89       all begin with the string <tt>ntpkey</tt> and include the file type,
  90       generating host and filestamp, as described in
  91       the <a href="#fmt">Cryptographic Data Files</a> section below</p>
  92     <h4 id="run">Running the Program</h4>
  93     <p>To test and gain experience with Autokey concepts, log in as root and
  94       change to the keys directory, usually <tt>/usr/local/etc</tt>.  When
  95       run for the first time, or if all files with names
  96       beginning <tt>ntpkey</tt> have been removed, use
  97       the <tt>ntp-keygen</tt> command without arguments to generate a
  98       default RSA host key and matching RSA-MD5 certificate with expiration
  99       date one year hence.  If run again without options, the program uses
 100       the existing keys and parameters and generates only a new certificate
 101       with new expiration date one year hence.</p>
 102     <p>Run the command on as many hosts as necessary.  Designate one of them
 103       as the trusted host (TH) using <tt>ntp-keygen</tt> with
 104       the <tt>-T</tt> option and configure it to synchronize from reliable
 105       Internet servers.  Then configure the other hosts to synchronize to
 106       the TH directly or indirectly.  A certificate trail is created when
 107       Autokey asks the immediately ascendant host towards the TH to sign its
 108       certificate, which is then provided to the immediately descendant host
 109       on request.  All group hosts should have acyclic certificate trails
 110       ending on the TH.</p>
 111     <p>The host key is used to encrypt the cookie when required and so must
 112       be RSA type.  By default, the host key is also the sign key used to
 113       encrypt signatures.  A different sign key can be assigned using
 114       the <tt>-S</tt> option and this can be either RSA or DSA type.  By
 115       default, the signature message digest type is MD5, but any combination
 116       of sign key type and message digest type supported by the OpenSSL
 117       library can be specified using the <tt>-c</tt> option.</p>
 118     <p>The rules say cryptographic media should be generated with proventic
 119       filestamps, which means the host should already be synchronized before
 120       this program is run.  This of course creates a chicken-and-egg problem
 121       when the host is started for the first time.  Accordingly, the host
 122       time should be set by some other means, such as
 123       eyeball-and-wristwatch, at least so that the certificate lifetime is
 124       within the current year.  After that and when the host is synchronized
 125       to a proventic source, the certificate should be re-generated.</p>
 126     <p>Additional information on trusted groups and identity schemes is on
 127       the <a href="autokey.html">Autokey Public-Key Authentication</a>
 128       page.</p>
 129     <h4 id="cmd">Command Line Options</h4>
 130     <dl>
 131       <dt><tt>-b <i>modulus</i></tt></dt>
 132       <dd>Set the modulus for generating identity keys to <i>modulus</i>
 133         bits.  The modulus defaults to 256, but can be set from 256 (32
 134         octets) to 2048 (256 octets).  Use the larger moduli with caution,
 135         as this can consume considerable computing resources and increases
 136         the size of authenticated packets.</dd>
 137       <dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt></dt>
 138       <dd>Select certificate digital signature and message digest scheme.
 139         Note that RSA schemes must be used with an RSA sign key and DSA
 140         schemes must be used with a DSA sign key.  The default without this
 141         option is <tt>RSA-MD5</tt>.  If compatibility with FIPS 140-2 is
 142         required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme
 143         must be used.</dd>
 144       <dt><tt>-C <i>cipher</i></tt></dt>
 145       <dd>Select the OpenSSL cipher to use for password-protected keys.
 146         The <tt>openssl -h</tt> command provided with OpenSSL displays
 147         available ciphers.  The default without this option
 148         is <tt>des-ede3-cbc</tt>.</dd>
 149       <dt><tt>-d</tt></dt>
 150       <dd>Enable debugging.  This option displays the cryptographic data
 151         produced for eye-friendly billboards.</dd>
 152       <dt><tt>-e</tt></dt>
 153       <dd>Extract the IFF or GQ public parameters from the <tt>IFFkey</tt>
 154         or <tt>GQkey</tt> keys file previously specified.  Send the
 155         unencrypted data to the standard output stream <tt>stdout</tt>.</dd>
 156       <dt><tt>-G</tt></dt>
 157       <dd>Generate a new encrypted GQ key file for the Guillou-Quisquater
 158        (GQ) identity scheme.  This option is mutually exclusive with
 159        the <tt>-I</tt> and <tt>-V</tt> options.</dd>
 160       <dt><tt>-H</tt></dt>
 161       <dd>Generate a new encrypted RSA public/private host key file.</dd>
 162       <dt><tt>-i <i>group</i></tt></dt>
 163       <dd>Set the optional Autokey group name to <tt><i>group</i></tt>. This
 164         is used in the identity scheme parameter file names.  In that role,
 165         the default is the host name if no group is provided.  The group
 166         name, if specified using <tt>-i</tt> or using <tt>-s</tt> following
 167         an <tt>@</tt> character, is also used in certificate subject and
 168         issuer names in the form <tt><i>host</i>@<i>group</i></tt> and
 169         should match the group specified via <tt>crypto ident</tt>
 170         or <tt>server ident</tt> in ntpd's configuration file.</dd>
 171       <dt><tt>-I</tt></dt>
 172       <dd>Generate a new encrypted IFF key file for the Schnorr (IFF)
 173         identity scheme.  This option is mutually exclusive with
 174         the <tt>-G</tt> and <tt>-V</tt> options.</dd>
 175       <dt><tt>-l <i>days</i></tt></dt>
 176       <dd>Set the lifetime for certificates to <tt><i>days</i></tt>.  The
 177       default lifetime is one year (365 d).</dd>
 178       <dt><tt>-m <i>modulus</i></tt></dt>
 179       <dd>Set the modulus for generating files to <i>modulus</i> bits.  The
 180         modulus defaults to 512, but can be set from 256 (32 octets) to 2048
 181         (256 octets).  Use the larger moduli with caution, as this can
 182         consume considerable computing resources and increases the size of
 183         authenticated packets.</dd>
 184       <dt><tt>-M</tt></dt>
 185       <dd>Generate a new keys file containing 10 MD5 keys and 10 SHA keys.
 186         An MD5 key is a string of 20 random printable ASCII characters,
 187         while a SHA key is a string of 40 random hex digits. The file can be
 188         edited using a text editor to change the key type or key content.
 189         This option is mutually exclusive with all other options.</dd>
 190       <dt><tt>-P</tt></dt>
 191       <dd>Generate a new private certificate used by the PC identity scheme.
 192         By default, the program generates public certificates.  Note: the PC
 193         identity scheme is not recommended for new installations.</dd>
 194       <dt><tt>-p <i>passwd</i></tt></dt>
 195       <dd>Set the password for reading and writing encrypted files
 196         to <tt><i>passwd</i></tt>.  These include the host, sign and
 197         identify key files.  By default, the password is the string returned
 198         by the Unix <tt>gethostname()</tt> routine.</dd>
 199       <dt><tt>-q <i>passwd</i></tt></dt>
 200       <dd>Set the password for writing encrypted IFF, GQ and MV identity
 201         files redirected to <tt>stdout</tt> to <tt><i>passwd</i></tt>=.  In
 202         effect, these files are decrypted with the <tt>-p</tt> password,
 203         then encrypted with the <tt>-q</tt> password.  By default, the
 204         password is the string returned by the Unix <tt>gethostname()</tt>
 205         routine.</dd>
 206       <dt><tt>-S [ RSA | DSA ]</tt></dt>
 207       <dd>Generate a new encrypted public/private sign key file of the
 208         specified type.  By default, the sign key is the host key and has
 209         the same type.  If compatibly with FIPS 140-2 is required, the sign
 210         key type must be <tt>DSA</tt>.</dd>
 211       <dt><tt>-s <i>host</i>[@<i>group</i>]</tt></dt>
 212       <dd>Specify the Autokey host name, where <tt><i>host</i></tt> is the
 213         host name and <tt><i>group</i></tt> is the optional group name.  The
 214         host name, and if provided, group name are used
 215         in <tt><i>host</i>@<i>group</i></tt> form as certificate subject and
 216         issuer.  Specifying <tt>-s @<i>group</i></tt> is allowed, and
 217         results in leaving the host name unchanged, as
 218         with <tt>-i <i>group</i></tt>.  The group name, or if no group is
 219         provided, the host name are also used in the file names of IFF, GQ,
 220         and MV identity scheme parameter files.  If <tt><i>host</i></tt> is
 221         not specified, the default host name is the string returned by
 222         the <tt>gethostname()</tt> routine.</dd>
 223       <dt><tt>-T</tt></dt>
 224       <dd>Generate a trusted certificate.  By default, the program generates
 225         nontrusted certificates.</dd>
 226       <dt><tt>-V <i>nkeys</i></tt></dt>
 227       <dd>Generate <tt>nkeys</tt> encrypted server keys for the
 228         Mu-Varadharajan (MV) identity scheme.  This option is mutually
 229         exclusive with the <tt>-I</tt> and <tt>-G</tt> options.  Note:
 230         support for this option should be considered a work in
 231         progress.</dd>
 232     </dl>
 233     <h4 id="rand">Random Seed File</h4>
 234     <p>All cryptographically sound key generation schemes must have means to
 235       randomize the entropy seed used to initialize the internal
 236       pseudo-random number generator used by the OpenSSL library routines.
 237       If a site supports <tt>ssh</tt>, it is very likely that means to do
 238       this are already available.  The entropy seed used by the OpenSSL
 239       library is contained in a file, usually called <tt>.rnd</tt>, which
 240       must be available when starting the <tt>ntp-keygen</tt> program
 241       or <tt>ntpd</tt> daemon.</p>
 242     <p>The OpenSSL library looks for the file using the path specified by
 243       the <tt>RANDFILE</tt> environment variable in the user home directory,
 244       whether root or some other user.  If the <tt>RANDFILE</tt> environment
 245       variable is not present, the library looks for the <tt>.rnd</tt> file
 246       in the user home directory.  Since both the <tt>ntp-keygen</tt>
 247       program and <tt>ntpd</tt> daemon must run as root, the logical place
 248       to put this file is in <tt>/.rnd</tt> or <tt>/root/.rnd</tt>.  If the
 249       file is not available or cannot be written, the program exits with a
 250       message to the system log.</p>
 251     <h4 id="fmt">Cryptographic Data Files</h4>
 252     <p>File and link names are in the
 253       form <tt>ntpkey_<i>key</i>_<i>name</i>.<i>fstamp</i></tt>,
 254       where <tt><i>key</i></tt> is the key or parameter
 255       type, <tt><i>name</i></tt> is the host or group name
 256       and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the
 257       file was created).  By convention, <em><tt>key</tt></em> names in
 258       generated file names include both upper and lower case characters,
 259       while <em><tt>key</tt></em> names in generated link names include only
 260       lower case characters.  The filestamp is not used in generated link
 261       names.</p>
 262     <p>The <em><tt>key</tt></em> name is a string defining the cryptographic
 263       key type.  Key types include public/private keys <tt>host</tt>
 264       and <tt>sign</tt>, certificate <tt>cert</tt> and several
 265       challenge/response key types.  By convention, client files used for
 266       challenges have a <tt>par</tt> subtype, as in the IFF
 267       challenge <tt>IFFpar</tt>, while server files for responses have
 268       a <tt>key</tt> subtype, as in the GQ response <tt>GQkey</tt>.</p>
 269     <p>All files begin with two nonencrypted lines.  The first line contains
 270     the file name in the
 271     format <tt>ntpkey_<i>key</i>_<i>host</i>.<i>fstamp</i></tt>.  The second
 272     line contains the datestamp in conventional Unix <tt>date</tt> format.
 273     Lines beginning with <tt>#</tt> are ignored.</p>
 274     <p>The remainder of the file contains cryptographic data encoded first
 275       using ASN.1 rules, then encrypted using the DES-CBC algorithm with
 276       given password and finally written in PEM-encoded printable ASCII text
 277       preceded and followed by MIME content identifier lines.</p>
 278     <p>The format of the symmetric keys file, ordinarily
 279       named <tt>ntp.keys,</tt> is somewhat different than the other files in
 280       the interest of backward compatibility.  Ordinarily, the file is
 281       generated by this program, but it can be constructed and edited using
 282       an ordinary text editor.</p>
 283     <table>
 284       <caption style="caption-side: bottom;">
 285         Figure 1. Typical Symmetric Key File
 286       </caption>
 287       <tr><td style="border: 1px solid black; border-spacing: 0;">
 288           <pre style="color:grey;">
 289             # ntpkey_MD5key_bk.ntp.org.3595864945
 290             # Thu Dec 12 19:22:25 2013
 291
 292             1  MD5 L";Nw&lt;`.I&lt;f4U0)247"i  # MD5 key
 293             2  MD5 &amp;&gt;l0%XXK9O'51VwV&lt;xq~  # MD5 key
 294             3  MD5 lb4zLW~d^!K:]RsD'qb6  # MD5 key
 295             4  MD5 Yue:tL[+vR)M`n~bY,'?  # MD5 key
 296             5  MD5 B;fxlKgr/&amp;4ZTbL6=RxA  # MD5 key
 297             6  MD5 4eYwa`o}3i@@V@..R9!l  # MD5 key
 298             7  MD5 `A.([h+;wTQ|xfi%Sn_!  # MD5 key
 299             8  MD5 45:V,r4]l6y^JH6.Sh?F  # MD5 key
 300             9  MD5 3-5vcn*6l29DS?Xdsg)*  # MD5 key
 301             10 MD5 2late4Me              # MD5 key
 302             11 SHA1 a27872d3030a9025b8446c751b4551a7629af65c  # SHA1 key
 303             12 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74  # SHA1 key
 304             13 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9  # SHA1 key
 305             14 SHA  a5332809c8878dd3a5b918819108a111509aeceb  # SHA  key
 306             15 MD2  2fe16c88c760ff2f16d4267e36c1aa6c926e6964  # MD2  key
 307             16 MD4  b2691811dc19cfc0e2f9bcacd74213f29812183d  # MD4  key
 308             17 MD5  e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c  # MD5  key
 309             18 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc  # MDC2 key
 310             19 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2  # RIPEMD160 key
 311             20 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878  # AES128CMAC key
 312             21 MD5 sampo 10.1.2.3/24
 313     </pre></td></tr></table>
 314     <p>Figure 1 shows a typical symmetric keys file used by the reference
 315       implementation.  Each line of the file contains three or four fields,
 316       first an integer between 1 and 65534, inclusive, representing the key
 317       identifier used in the <tt>server</tt> and <tt>peer</tt> configuration
 318       commands.  Second is the key type for the message digest algorithm,
 319       which in the absence of the OpenSSL library must be <tt>MD5</tt> to
 320       designate the MD5 message digest algorithm.  If the OpenSSL library is
 321       installed, the key type can be any message digest algorithm supported
 322       by that library.  However, if compatibility with FIPS 140-2 is
 323       required, the key type must be either <tt>SHA</tt> or <tt>SHA1</tt>.
 324       The key type can be changed using an ASCII text editor.</p>
 325     <p>The third field is the key.</p>
 326     <p>An MD5 key consists of a printable ASCII string less than or equal to
 327       16 characters and terminated by whitespace or a # character.  An
 328       OpenSSL key consists of a hex-encoded ASCII string of 40 characters,
 329       which is truncated as necessary.</p>
 330     <p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt>
 331       programs are checked against passwords requested by the programs and
 332       entered by hand, so it is generally appropriate to specify these keys
 333       in human readable ASCII format.</p>
 334     <p>The optional fourth field is one or more IPs, with each IP separated
 335       with a comma.  An IP may end with an optional <tt>/subnetbits</tt>
 336       suffix, which limits the acceptance of the key identifier to packets
 337       claiming to be from the described IP space.</p>
 338     <p>The <tt>ntp-keygen</tt> program generates a MD5 symmetric keys
 339       file <tt>ntpkey_MD5key_<i>hostname.filestamp</i></tt>.  Since the file
 340       contains private shared keys, it should be visible only to root and
 341       distributed by secure means to other subnet hosts.  The NTP daemon
 342       loads the file <tt>ntp.keys</tt>, so <tt>ntp-keygen</tt> installs a
 343       soft link from this name to the generated file.  Subsequently, similar
 344       soft links must be installed by manual or automated means on the other
 345       subnet hosts.  While this file is not used with the Autokey Version 2
 346       protocol, it is needed to authenticate some remote configuration
 347       commands used by the <a href="ntpq.html"><tt>ntpq</tt></a>
 348       and <a href="ntpdc.html"><tt>ntpdc</tt></a> utilities.</p>
 349     <h4 id="bug">Bugs</h4>
 350     <p>It can take quite a while to generate some cryptographic values.</p>
 351     <hr>
 352     <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
 353   </body>
 354 </html>