<h3>Authentication Options</h3>
<img src="pic/alice44.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>Our resident cryptographer; now you see him, now you don't.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">01:29</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="338">Wednesday, September 13, 2006</csobj></p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">02:46</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="301">Monday, September 03, 2007</csobj></p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/links9.txt"></script>
<li class="inline"><a href="#auth">Authentication Support</a>
<li class="inline"><a href="#symm">Symmetric Key Cryptography</a>
<li class="inline"><a href="#pub">Public Key Cryptography</a>
+ <li class="inline"><a href="#group">NTP Secure Groups</a>
+ <li class="inline"><a href="#name">Naming Conventions</a>
<li class="inline"><a href="#cfg">Configuration</a>
<li class="inline"><a href="#inter">Operation</a>
- <li class="inline"><a href="#key">Key Management</a>
<li class="inline"><a href="#cmd">Authentication Commands</a>
<li class="inline"><a href="#err">Error Codes</a>
<li class="inline"><a href="#file">Files</a>
</ul>
<hr>
<h4 id="auth">Authentication Support</h4>
- <p>Authentication support allows the NTP client to verify that the server is in fact known and trusted and not an intruder intending accidentally or on purpose to masquerade as that server. The NTPv3 specification RFC-1305 defines a scheme which provides cryptographic authentication of received NTP packets. Originally, this was done using the Data Encryption Standard (DES) algorithm operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by the RSA Message Digest 5 (MD5) algorithm using a private key, commonly called keyed-MD5. Either algorithm computes a message digest, or one-way hash, which can be used to verify the server has the correct private key and key identifier.</p>
- <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key cryptography, and, in addition, provides a new Autokey scheme based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on a private value which is generated by each host and never revealed. With the exception of the group key described later, all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, which can be provided by commercial services or produced by utility programs in the OpenSSL software library or the NTPv4 distribution.</p>
+ <p>Authentication support allows the NTP client to verify that the server is in fact known and trusted and not an intruder intending accidentally or on purpose to masquerade as a legitimate server. The NTPv3 specification RFC-1305 defines a scheme which provides cryptographic authentication of received NTP packets. Originally, this was done using the Data Encryption Standard (DES) algorithm operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by the RSA Message Digest 5 (MD5) algorithm using a private key, commonly called keyed-MD5. Either algorithm computes a message digest, or one-way hash, which can be used to verify the server has the correct private key and key identifier.</p>
+ <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key cryptography and, in addition, provides a new Autokey scheme based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on private values which are generated by each participant and never revealed. With the exception of the group parameters described later, all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, which can be provided by commercial services or produced by utility programs in the OpenSSL software library or the NTPv4 distribution.</p>
<p>While the algorithms for symmetric key cryptography are included in the NTPv4 distribution, public key cryptography requires the OpenSSL software library to be installed before building the NTP distribution. This library is available from <a href="http://www.openssl.org">http://www.openssl.org</a> and can be installed using the procedures outlined in the <a href="build/build.html">Building and Installing the Distribution</a> page. Once installed, the configure and build process automatically detects the library and links the library routines required.</p>
- <p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> subcommand on the <tt>peer</tt>, <tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> configuration commands as described in the <a href="confopt.html">Configuration Options</a> page. The authentication options described below specify the locations of the key files, if other than default, which symmetric keys are trusted and the interval between various operations, if other than default.</p>
- <p>Authentication is always enabled, although ineffective if not configured as described below. If a NTP packet arrives including a message authentication code (MAC), it is accepted only if it passes all cryptographic checks. The checks require correct key ID, key value and message digest. If the packet has been modified in any way or replayed by an intruder, it will fail one or more of these checks and be discarded. Furthermore, the Autokey scheme requires a preliminary protocol exchange to obtain the server certificate, verify its credentials and initialize the protocol</p>
- <p>The <tt>auth</tt> flag controls whether new associations or remote configuration commands require cryptographic authentication. This flag can be set or reset by the <tt>enable</tt> and <tt>disable</tt> commands and also by remote configuration commands sent by a <tt>ntpdc</tt> program running on another machine. If this flag is enabled, which is the default case, new broadcast/manycast client and symmetric passive associations and remote configuration commands must be cryptographically authenticated using either symmetric key or public key cryptography. If this flag is disabled, these operations are effective even if not cryptographic authenticated. It should be understood that operating with the <tt>auth</tt> flag disabled invites a significant vulnerability where a rogue hacker can masquerade as a truechimer and seriously disrupt system timekeeping. It is important to note that this flag has no purpose other than to allow or disallow a new association in response to new broadcast and symmetric active messages and remote configuration commands and, in particular, the flag has no effect on the authentication process itself.</p>
+ <p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> subcommand on the <tt>peer</tt>, <tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> configuration commands as described in the <a href="confopt.html">Configuration Options</a> page. The authentication options described below specify the locations of the key files, if other than default, which symmetric keys are trusted and other details needed by the optional Autokey protocol. The <a href="keygen.html">ntp-keygen</a> program is used to generate the various key files, certificate files and identity parameters files described below.</p>
+ <p>Authentication is always enabled, although ineffective if not configured as described below. If an NTP packet includes a message authentication code (MAC), consisting of a key ID;and message digest, it is accepted only if the key ID matches a trusted key and and the message digest is verified with this key. Furthermore, the Autokey scheme requires a preliminary protocol exchange to obtain the server certificate, verify its credentials and initialize the protocol</p>
+ <p>The <tt>auth</tt> flag controls whether new associations or remote configuration commands require cryptographic authentication. This flag can be set or reset by the <tt>enable</tt> and <tt>disable</tt> commands and also by remote configuration commands sent by a <tt>ntpdc</tt> program running on another machine. If this flag is enabled, which is the default, new broadcast/manycast client and symmetric passive associations and remote configuration commands must be cryptographically authenticated using either symmetric key or public key cryptography. If this flag is disabled, these operations are effective even if not cryptographic authenticated. It should be understood that operating with the <tt>auth</tt> flag disabled invites a significant vulnerability where a rogue hacker can masquerade as a legitimate server and seriously disrupt system timekeeping. It is important to note that this flag has no purpose other than to allow or disallow a new association in response to new broadcast and symmetric active messages and remote configuration commands and, in particular, the flag has no effect on the authentication process itself.</p>
<p>The security model and protocol schemes for both symmetric key and public key cryptography are summarized below; further details are in the briefings, papers and reports at the NTP project page linked from <a href="http://www.ntp.org">www.ntp.org</a>.</p>
- <h4 id="symm">Symmetric Key Cryptography</h4>
-
- The original RFC-1305 specification allows any one of possibly 65,534 keys, each distinguished by a 32-bit key identifier, to authenticate an association. The servers and clients involved must agree on the key and key identifier to authenticate NTP packets. Keys and related information are specified in a key file, usually called <tt>ntp.keys</tt>, which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, additional keys can be used as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs. Ordinarily, the <tt>ntp.keys</tt> file is generated by the <tt><a href="keygen.html">ntp-keygen</a></tt> program.
+ <h4 id="symm">Symmetric Key Cryptography</h4>The original RFC-1305 specification allows any one of possibly 65,534 keys (excluding zero), each distinguished by a 32-bit key identifier, to authenticate an association. The servers and clients involved must agree on the key and key identifier to authenticate NTP packets. Keys and related information are specified in a key file, usually called <tt>ntp.keys</tt>, which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, additional keys can be used as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs. Ordinarily, the <tt>ntp.keys</tt> file is generated by the <tt><a href="keygen.html">ntp-keygen</a></tt> program.
<p>When <tt>ntpd</tt> is first started, it reads the key file specified in the <tt>keys</tt> configuration command and installs the keys in the key cache. However, individual keys must be activated with the <tt>trustedkey</tt> command before use. This allows, for instance, the installation of possibly several batches of keys and then activating or deactivating each batch remotely using <tt>ntpdc</tt>. This also provides a revocation capability that can be used if a key becomes compromised. The <tt>requestkey</tt> command selects the key used as the password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt> command selects the key used as the password for the <tt>ntpq</tt> utility.</p>
<h4 id="pub">Public Key Cryptography</h4>
- <p>NTPv4 supports the original NTPv3 symmetric key scheme described in RFC-1305 and in addition the Autokey protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source with digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page and based on cryptographic challenge/response algorithms are also available. Using these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks.</p>
- <p>The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. Most modes use a special cookie which can be computed independently by the client and server, but encrypted in transmission. All modes use in addition a variant of the S-KEY scheme, in which a pseudo-random key list is generated and used in reverse order. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/%7emills/autokey.html">Autonomous Authentication</a> page.</p>
- <p>The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program. This includes a required host key file, required host certificate file and optional sign key file, leapsecond file and identity scheme files. The digest/signature scheme is specified in the X.509 certificate along with the matching sign key. There are several schemes available in the OpenSSL software library, each identified by a specific string such as <tt>md5WithRSAEncryption</tt>, which stands for the MD5 message digest with RSA encryption scheme. The current NTP distribution supports all the schemes in the OpenSSL library, including those based on RSA and DSA digital signatures.</p>
- <p>NTP secure groups can be used to define cryptographic compartments and security hierarchies. It is important that every host in the group be able to construct a certificate trail to one or more trusted hosts in the same group. Each group host runs the Autokey protocol to obtain the certificates for all hosts along the trail to one or more trusted hosts. This requires the configuration file in all hosts to be engineered so that, even under anticipated failure conditions, the NTP subnet will form such that every group host can find a trail to at least one trusted host.</p>
- <h4>Naming and Addressing</h4>
- <p>It is important to note that Autokey does not use DNS to resolve addresses, since DNS can't be completely trusted until the name servers have synchronized clocks. The cryptographic name used by Autokey to bind the host identity credentials and cryptographic values must be independent of interface, network and any other naming convention. The name appears in the host certificate in either or both the subject and issuer fields, so protection against DNS compromise is essential.</p>
- <p>By convention, the name of an Autokey host is the name returned by the Unix <tt>gethostname()</tt> system call or equivalent in other systems. By the system design model, there are no provisions to allow alternate names or aliases. However, this is not to say that DNS aliases, different names for each interface, etc., are constrained in any way.</p>
- <p>It is also important to note that Autokey verifies authenticity using the host name, network address and public keys, all of which are bound together by the protocol specifically to deflect masquerade attacks. For this reason Autokey includes the source and destinatino IP addresses in message digest computations and so the same addresses must be available at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p>
+ <p>NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page are based on cryptographic challenge/response exchanges. Using these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/%7emills/autokey.html">Autonomous Authentication</a> page.</p>
+ <p>The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program. These define the required host key, required host certificate and optional sign key and identity parameters. The certificate defines the Autokey host name and the selected cryptographic algorithms.</p>
+ <h4 id="group">NTP Secure Groups</h4>
+ <p>NTP secure groups are used to define cryptographic compartments and security hierarchies. All hosts belonging to a named secure group share a secret group key which can be encrypted with individual passwords. Each group includes one or more trusted hosts operating at the root, or lowest stratum in the group. The other hosts in the group are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts, to one or more trusted hosts. When the protocol first starts, each host recursively retrieves the certificates along the trail in order to verify the host identity and avoid masquerade and middleman attacks. The trail concludes at a trusted host, the name of which defines the identity parameters used to confirm group membership.</p>
+ <p>Secure groups can be configured as hierarchies where the trusted hosts of one group can be clients of one or more other groups operating at a lower stratum. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.</p>
+ <h4 id="name">Naming Conventions</h4>
+ <p>It is important to note that Autokey does not use DNS to resolve names or addresses, since DNS can't be completely trusted until the name servers have synchronized clocks. The Autokey names for hosts and groups are used only to verify group membership and create group hierarchies.</p>
+ <p>By convention the Autokey name of a group host other than the trusted hosts is the name returned by the Unix <tt>gethostname()</tt> system call or equivalent in other systems. Also by convention the host name for all trusted hosts is the same name, called the group name. However, it is possible to use other names as long as the certificate trails remain acyclic. The group name is also the name of the identity parameters resident in every group host.</p>
+ <p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p>
<h4 id="cfg">Configuration</h4>
- <p>Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. The simplest configuration consists of a subnet with one or more servers at the same low stratum acting as trusted hosts and with dependent clients at higher strata and sharing a single secure group and identity scheme. Each trusted host generates a host key, trusted certificate and group key. Each client generates a host key, normal certificate and installs the group key of each trusted host using secure means and renames it as the name of the trusted host.</p>
- <p>For example, trusted host Alice generates keys using</p>
- <p><tt>ntp-keygen -H -T -I -p xyz</tt></p>
- <p>where H specifies a new host key, T the trusted certificate, I the IFF identity scheme and p the password used to encrypt the private key files. The group key file is <tt>ntpkey_IFFpar_alice.<i>filestamp</i></tt><i>, </i>where <i>filestamp </i>represents the NTP time in seconds when the file was generated.</p>
- <p>Host Bob generate keys using</p>
- <p><tt>ntp-keygen -H -p abc</tt></p>
- <p>where <tt>abc</tt> is different for each group host. The trusted host generates a password-protected group key using</p>
- <p><tt>ntp-keygen -q xyz -p abc -e ><i>temp</i></tt></p>
- <p>where <tt>xyz</tt> is the trusted host password, <tt>abc</tt> is the password supplied by the client and <i><tt>temp</tt></i> is a temporary file. This file is transmitted to Bob using secure means and renamed to the fully qualified host name for Alice preceded by the string <tt>ntpkey_iff_</tt>.</p>
+ <p>Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. The simplest scenario consists of a secure group with one or more trusted hosts at the same low stratum and with dependent clients at higher strata, all sharing the same group identity parameters.</p>
+ <p>On behalf of the group, a trusted host generates a host key, trusted certificate and identity parameters, all encrypted with a private password. Other hosts generate a host key encrypted with a private password and public nontrusted certificate. In the intended model, a host sends a mail message to a trusted host and requests the group identity parameters encrypted with a specified password. Note that, at least in the IFF scheme, the client parameters is a subset of the identity parameters, so hosts other than trusted hosts cannot masquerated as trusted.</p>
+ <p>The remaining group hosts are configured to provide an acyclic certificate trail ending at a trusted host. There is some art to this process, which may depend on anticipated failure scenarios where the trail might become discontinuous. In general, the trail should follow the expected stratum trail and provide redundancy.</p>
<h4>Operation</h4>
<p>A specific combination of authentication scheme (none, symmetric key, public key) and identity scheme is called a cryptotype, although not all combinations are compatible. There may be management configurations where the clients, servers and peers may not all support the same cryptotypes. A secure NTPv4 subnet can be configured in many ways while keeping in mind the principles explained above and in this section. Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice.</p>
- <p>The cryptotype of an association is determined at the time of mobilization, either at configuration time or some time later when a message of appropriate cryptotype arrives. When mobilized by a <tt>server</tt> or <tt>peer</tt> configuration command and no <tt>key</tt> or <tt>autokey</tt> subcommands are present, the association is not authenticated; if the <tt>key</tt> subcommand is present, the association is authenticated using the symmetric key ID specified; if the <tt>autokey</tt> subcommand is present, the association is authenticated using Autokey.</p>
- <h4 id="key">Key Management</h4>
- <p>The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program, including symmetric key, host key and public certificate files, as well as sign key, identity parameters and leapseconds files. Alternatively, host and sign keys and certificate files can be generated by the OpenSSL utilities and certificates can be imported from public certificate authorities. Note that symmetric keys are necessary for the <tt>ntpq</tt> and <tt>ntpdc</tt> utility programs. The remaining files are necessary only for the Autokey protocol.</p>
- <p>Certificates imported from OpenSSL or public certificate authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format used by OpenSSL. The overall length of the certificate encoded in ASN.1 must not exceed 1024 bytes. The subject distinguished name field (<tt>CN</tt>) is the fully qualified name of the host on which it is used; the remaining subject fields are ignored. The certificate extension fields must not contain either a subject key identifier or a issuer key identifier field; however, an extended key usage field for a trusted host must contain the value <tt>trustRoot</tt>;. Other extension fields are ignored.</p>
- <h4 id="cmd">Authentication Commands</h4>
+ <p>The cryptotype of an association is determined at the time of mobilization, either at configuration time or some time later when an NTP packet of appropriate cryptotype arrives. When mobilized by a <tt>server</tt> or <tt>peer</tt> configuration command and no <tt>key</tt> or <tt>autokey</tt> subcommands are present, the association is not authenticated. If the <tt>key</tt> subcommand is present, the association is authenticated using the symmetric key ID specified. If the <tt>autokey</tt> subcommand is present, the association is authenticated using Autokey.</p>
+ <p>With Autokey, the cryptotype of the association is determined by the set of files generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program. All configurations include a public/private host key and matching certificate. Absent identity parameters, this is a Trusted Certificate (TC) scheme. There are three identity schemse, IFF, GQ and MV destcribed on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page. Each is characterized by a set of private parameters that are distributed to each group host by secure means.</p>
+ <p>A group can operate where the cryptotype can be different for each client. One client can elect to use no authentication at all, another with the TC scheme and others with IFF, GQ and/or MV. However, a host cannot prove identity to a downstream client unless it has the corresponding identity parameters.</p>
+ <p>Examples</p>
+ <p>The figure shows what might be a typical scenario involving three secure groups called Alice, Helen and Carol. Alice has trusted hosts A and B and nontrusted hosts C and D. Helen has trusted host R and nontrusted host S. Carol has trusted host X and nontrusted hosts Y and Z. Trusted host X in Carol is a client of nontrusted host C in Alice and nontrusted host S in Helen. Assume the IFF identity scheme is used in Alice, the GQ identity scheme in Helen and the TC scheme in Carol. For clarity, assume the passwords for all hosts in a group is the group name.</p>
+ <p><img src="../pic/sgroup.gif" alt="gif"></p>
+ <p>Run the ntp-keygen program on the Alice hosts:</p>
+ <p>A: ntp-keygen -q alice -s alice -T -I<br>
+ B: ntp-keygen -q alice -s alice -T<br>
+ C and D: ntp-keygen -q alice -i alice</p>
+ <p>Copy the ntp_IFFpar_alice.fstamp file and ntp_iff_alice link from A to all group hosts B, C and D. Since the paswords are the same, it is not necessary to use the -p option.</p>
+ <p>In the NTP configuration files for Alice hosts:</p>
+ <p>A and B: crypto pw alice host alice<br>
+ C and D: crypto pw alice ident alice</p>
+ <p>Run the ntp-keygen program on Helen hosts:</p>
+ <p>R: ntp-keygen -q helen -s helen -T -G<br>
+ S: ntp-keygen -q helen -i helen</p>
+ <p>Copy the C</p>
+ <p>In the NTP configuration files for Alice hosts:</p>
+ <p>R: server (radio clock)<br>
+ crypto pw helen host helen<br>
+ S: server R<br>
+ crypto pw helen ident helen</p>
+ <p>Run the ntp-keygen on Carol hosts:</p>
+ <p>X: ntp-keygen pw carol host carol<br>
+ Y, Z: ntp-keygen -q carol -i carol</p>
+ <p>Since X is a client of both Alice and Helen, copy the ntp_IFFpar_alice.fstamp file and ntp_iff_alice link from A to X and the ntp_IFFpar_alice.fstamp file and ntp_iff_alice link from R to X. When X follows the certificate trail to either A or B, it will find the Alice self-signed certificate for Alice load the GQ identity scheme for Alice. A similar operation will occur for Helen.</p>
+ <p>Authentication Commands</p>
<dl>
<dt><tt>autokey [<i>logsec</i>]</tt>
<dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.
<dt><tt>controlkey <i>key</i></tt>
<dd>Specifies the key identifier to use with the <a href="ntpq.html"><tt>ntpq</tt></a> utility, which uses the standard protocol defined in RFC-1305. The <tt><i>key</i></tt> argument is the key identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive.
- <dt><tt>crypto [cert <i>file</i>] [leap <i>file</i>] [randfile <i>file</i>] [host <i>file</i>] [sign <i>file</i>] [ident <i>scheme</i>] [iffpar <i>file</i>] [gqpar <i>file</i>] [mvpar <i>file</i>] [pw <i>password</i>]</tt>
- <dd>This command requires the OpenSSL library. It activates public key cryptography, selects the message digest and signature encryption scheme and loads the required private and public values described above. If one or more files are left unspecified, the default names are used as described above. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the <tt>keysdir</tt> command or default <tt>/usr/local/etc</tt>. Following are the subcommands:
+ <dt><tt>crypto [cert <i>file</i>] [randfile <i>file</i>] [host <i>file</i>] [sign <i>file</i>] [ident <i>groupname</i>] [pw <i>password</i>]</tt>
+ <dd>This command requires the OpenSSL library. It activates public key cryptography and loads the required public/private encryption and sign kyes and public certificat. If one or more files are left unspecified, the default names are used as described below. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the <tt>keysdir</tt> command or default <tt>/usr/local/etc</tt>. Following are the subcommands:
<dl>
<dt><tt>cert <i>file</i></tt>
<dd>Specifies the location of the required host public certificate file. This overrides the link <tt>ntpkey_cert_<i>hostname</i></tt> in the keys directory.
- <dt><tt>gqpar <i>file</i></tt>
- <dd>Specifies the location of the client GQ parameters file. This overrides the link <tt>ntpkey_gq_<i>hostname</i></tt> in the keys directory.
<dt><tt>host <i>file</i></tt>
- <dd>Specifies the location of the required host key file. This overrides the link <tt>ntpkey_key_<i>hostname</i></tt> in the keys directory.
- <dt><tt>ident <i>scheme</i></tt>
- <dd>Requests the server identity <i><tt>scheme</tt></i>, which can be <tt>IFF</tt>, <tt>GQ</tt> or <tt>MV</tt>. This is used when the host will not be a server for a dependent client.<dt><tt>iffpar <i>file</i></tt>
- <dd>Specifies the location of the optional IFF parameters file.This overrides the link <tt>ntpkey_iff_<i>hostname</i></tt> in the keys directory.
- <dt><tt>leap <i>file</i></tt>
- <dd>Specifies the location of the client leapsecond file. This overrides the link <tt>ntpkey_leap</tt> in the keys directory.
- <dt><tt>mv</tt>
- <dd>Requests the MV server identity scheme.
- <dt><tt>mvpar <i>file</i></tt>
- <dd>Specifies the location of the client MV parameters file. This overrides the link <tt>ntpkey_mv_<i>hostname</i></tt> in the keys directory.
+ <dd>Specifies the location of the required host key file. This overrides the link <tt>ntpkey_host_<i>hostname</i></tt> in the keys directory.
+
<dt><tt>pw <i>password</i></tt>
- <dd>Specifies the password to decrypt files containing private keys and identity parameters. This is required only if these files have been encrypted.
- <dt><tt>randfile <i>file</i></tt>
- <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above.
- <dt><tt>sign <i>file</i></tt>
+ <dd>Specifies the password to decrypt files containing private keys and identity parameters.<dt><tt>randfile <i>file</i></tt>
+ <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the <a href="keygen.html"><tt>ntp-keygen</tt></a> page.<dt><tt>sign <i>file</i></tt>
<dd>Specifies the location of the optional sign key file. This overrides the link <tt>ntpkey_sign_<i>hostname</i></tt> in the keys directory. If this file is not found, the host key is also the sign key.
</dl>
<dt><tt>keys <i>keyfile</i></tt>
<dd>The old server certificate has expired.
</dl>
<h4 id="file">Files</h4>
- <p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page.</p>
- <h4 id="leap">Leapseconds Table</h4>
- <p>The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers using <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</p>
- <p>While not strictly a security function, the Autokey protocol provides means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the <tt>crypto</tt> command, with default <tt>ntpkey_leap</tt>, while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.</p>
+ <p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page. Note that provisions to load leap second values from the NIST files have been removed. These provisions are now available whether or not the OpenSSL library is available. However, the functions that can download these values from servers remains available.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<h3><tt>ntp-keygen</tt> - generate public and private keys</h3>
<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>Alice holds the key.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">22:32</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="294">Monday, November 07, 2005</csobj></p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">02:48</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="301">Monday, September 10, 2007</csobj></p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/links9.txt"></script>
<li class="inline"><a href="#synop">Synopsis</a>
<li class="inline"><a href="#descrip">Description</a>
<li class="inline"><a href="#run">Running the program</a>
- <li class="inline"><a href="#trust">Trusted Hosts and Groups</a>
- <li class="inline"><a href="#idexp">Identity Schemes</a>
- <li class="inline"><a href="#exam">Example</a>
+ <li class="inline"><a href="#trust">Trusted Hosts and Secure Groups</a>
+ <li class="inline"><a href="#ident">Identity Schemes</a>
<li class="inline"><a href="#cmd">Command Line Options</a>
<li class="inline"><a href="#rand">Random Seed File</a>
<li class="inline"><a href="#fmt">Cryptographic Data Files</a>
</ul>
<hr>
<h4 id="synop">Synopsis</h4>
- <p id="intro"><tt>ntp-keygen [ -deGgHIMnPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -i <i>name</i> ] [ -p <i>password</i> ] [ -S [ RSA | DSA ] ] [ -s <i>name</i> ] [ -v <i>nkeys</i> ]</tt></p>
+ <p id="intro"><tt>ntp-keygen [ -cdeMPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -H } [ -i <i>issuername</i> ] [ -p <i>passwd2</i> ] [ -q <i>passwd1</i> ] [ -S [ RSA | DSA ] ] [ -s <i>subjectame</i> ] [ -V <i>nkeys</i> ]</tt></p>
<h4 id="descrip">Description</h4>
- <p>This program generates cryptographic data files used by the NTPv4 authentication and identification schemes. It generates MD5 key files used in symmetric key cryptography. In addition, if the OpenSSL software library has been installed, it generates keys, certificate and identity files used in public key cryptography. These files are used for cookie encryption, digital signature and challenge/response identification algorithms compatible with the Internet standard security infrastructure.</p>
- <p>By default, files are not encrypted by <tt>ntp-keygen</tt>. The <tt>-p <i>password</i></tt> option specifies the write password and <tt>-q <i>password</i></tt> option the read password for previously encrypted files. The <tt>ntp-keygen</tt> program prompts for the password if it reads an encrypted file and the password is missing or incorrect. If an encrypted file is read successfully and no write password is specified, the read password is used as the write password by default.</p>
- <p>The <tt>ntpd</tt> configuration command <tt>crypto pw <i>password</i></tt> specifies the read password for previously encrypted files. The daemon expires on the spot if the password is missing or incorrect. For convenience, if a file has been previously encrypted, the default read password is the name of the host running the program. If the previous write password is specified as the host name, these files can be read by that host with no explicit password.</p>
- <p>All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. File names begin with the prefix <tt>ntpkey_</tt> and end with the postfix <tt><i>_hostname.filestamp</i></tt>, where <tt><i>hostname</i></tt> is usually the string returned by the Unix <tt>gethostname()</tt> routine, and <tt><i>filestamp</i></tt> is the NTP seconds when the file was generated, in decimal digits. This both guarantees uniqueness and simplifies maintenance procedures, since all files can be quickly removed by a <tt>rm ntpkey*</tt> command or all files generated at a specific time can be removed by a <tt>rm *<i>filestamp</i></tt> command. To further reduce the risk of misconfiguration, the first two lines of a file contain the file name and generation date and time as comments.</p>
- <p>All files are installed by default in the keys directory <tt>/usr/local/etc</tt>, which is normally in a shared filesystem in NFS-mounted networks. The actual location of the keys directory and each file can be overridden by configuration commands, but this is not recommended. Normally, the files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page.</p>
- <p>Normally, files containing private values, including the host key, sign key and identification parameters, are permitted root read/write-only; while others containing public values are permitted world readable. Alternatively, files containing private values can be encrypted and these files permitted world readable, which simplifies maintenance in shared file systems. Since uniqueness is insured by the hostname and file name extensions, the files for a NFS server and dependent clients can all be installed in the same shared directory.</p>
- <p>The recommended practice is to keep the file name extensions when installing a file and to install a soft link from the generic names specified elsewhere on this page to the generated files. This allows new file generations to be activated simply by changing the link. If a link is present, <tt>ntpd</tt> follows it to the file name to extract the filestamp. If a link is not present, <tt>ntpd</tt> extracts the filestamp from the file itself. This allows clients to verify that the file and generation times are always current. The <tt>ntp-keygen</tt> program uses the same extension for all files generated at one time, so each generation is distinct and can be readily recognized in monitoring data.</p>
- <h4 id="run">Running the program</h4>
- <p>The safest way to run the <tt>ntp-keygen</tt> program is logged in directly as root. The recommended procedure is change to the keys directory, usually <tt>/ust/local/etc</tt>, then run the program. When run for the first time, or if all <tt>ntpkey</tt> files have been removed, the program generates a RSA host key file and matching RSA-MD5 certificate file, which is all that is necessary in many cases. The program also generates soft links from the generic names to the respective files. If run again, the program uses the same host key file, but generates a new certificate file and link.</p>
- <p>The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. When necessary, a different sign key can be specified and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme specified in the certificate must be compatible with the sign key. Certificates using any digest algorithm are compatible with RSA sign keys; however, only SHA and SHA1 certificates are compatible with DSA sign keys.</p>
- <p>Private/public key files and certificates are compatible with other OpenSSL applications and very likely other libraries as well. Certificates or certificate requests derived from them should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identification parameter files, although encoded as the other files, are probably not compatible with anything other than Autokey.</p>
- <p>Running the program as other than root and using the Unix <tt>su</tt> command to assume root may not work properly, since by default the OpenSSL library looks for the random seed file <tt>.rnd</tt> in the user home directory. However, there should be only one <tt>.rnd</tt>, most conveniently in the root directory, so it is convenient to define the <tt>$RANDFILE</tt> environment variable used by the OpenSSL library as the path to <tt>/.rnd</tt>.</p>
- <p>Installing the keys as root might not work in NFS-mounted shared file systems, as NFS clients may not be able to write to the shared keys directory, even as root. In this case, NFS clients can specify the files in another directory such as <tt>/etc</tt> using the <tt>keysdir</tt> command. There is no need for one client to read the keys and certificates of other clients or servers, as these data are obtained automatically by the Autokey protocol.</p>
- <p>Ordinarily, cryptographic files are generated by the host that uses them, but it is possible for a trusted agent (TA) to generate these files for other hosts; however, in such cases files should always be encrypted. The subject name and trusted name default to the hostname of the host generating the files, but can be changed by command line options. It is convenient to designate the owner name and trusted name as the subject and issuer fields, respectively, of the certificate. The owner name is also used for the host and sign key files, while the trusted name is used for the identity files.</p>
- <h4 id="trust">Trusted Hosts and Groups</h4>
- <p>Each cryptographic configuration involves selection of a signature scheme and identification scheme, called a cryptotype, as explained in the <a href="authopt.html">Authentication Options</a> page. The default cryptotype uses RSA encryption, MD5 message digest and TC identification. First, configure a NTP subnet including one or more low-stratum trusted hosts from which all other hosts derive synchronization directly or indirectly. Trusted hosts have trusted certificates; all other hosts have nontrusted certificates. These hosts will automatically and dynamically build authoritative certificate trails to one or more trusted hosts. A trusted group is the set of all hosts that have, directly or indirectly, a certificate trail ending at a trusted host. The trail is defined by static configuration file entries or dynamic means described on the <a href="manyopt.html">Automatic NTP Configuration Options</a> page.</p>
- <p>On each trusted host as root, change to the keys directory. To insure a fresh fileset, remove all <tt>ntpkey</tt> files. Then run <tt>ntp-keygen -T</tt> to generate keys and a trusted certificate. On all other hosts do the same, but leave off the <tt>-T</tt> flag to generate keys and nontrusted certificates. When complete, start the NTP daemons beginning at the lowest stratum and working up the tree. It may take some time for Autokey to instantiate the certificate trails throughout the subnet, but setting up the environment is completely automatic.</p>
- <p>If it is necessary to use a different sign key or different digest/signature scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-S</tt><i><tt> type</tt></i> option, where <i><tt>type</tt></i> is either <tt>RSA</tt> or <tt>DSA</tt>. The most often need to do this is when a DSA-signed certificate is used. If it is necessary to use a different certificate scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-c <i>scheme</i></tt> option and selected <i><tt>scheme</tt></i> as needed. If <tt>ntp-keygen</tt> is run again without these options, it generates a new certificate using the same scheme and sign key.</p>
- <p>After setting up the environment it is advisable to update certificates from time to time, if only to extend the validity interval. Simply run <tt>ntp-keygen</tt> with the same flags as before to generate new certificates using existing keys. However, if the host or sign key is changed, <tt>ntpd</tt> should be restarted. When ntpd is restarted, it loads any new files and restarts the protocol. Other dependent hosts will continue as usual until signatures are refreshed, at which time the protocol is restarted.</p>
- <h4 id="idexp">Identity Schemes</h4>
- <p>As mentioned on the Autonomous Authentication page, the default TC identity scheme is vulnerable to a middleman attack. However, there are more secure identity schemes available, including PC, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/keygen.html">Identification Schemes</a> page. These schemes are based on a TA, one or more trusted hosts and some number of nontrusted hosts. Trusted hosts prove identity using values provided by the TA, while the remaining hosts prove identity using values provided by a trusted host and certificate trails that end on that host. The name of a trusted host is also the name of its sugroup and also the subject and issuer name on its trusted certificate. The TA is not necessarily a trusted host in this sense, but often is.</p>
- <p>In some schemes there are separate keys for servers and clients. A server can also be a client of another server, but a client can never be a server for another client. In general, trusted hosts and nontrusted hosts that operate as both server and client have parameter files that contain both server and client keys. Hosts that operate only as clients have key files that contain only client keys.</p>
- <p>The PC scheme supports only one trusted host in the group. On trusted host <i>alice</i> run <tt>ntp-keygen -P -p <i>password</i></tt> to generate the host key file <tt>ntpkey_RSAkey_<i>alice.filestamp</i></tt> and trusted private certificate file <tt>ntpkey_RSA-MD5_cert_<i>alice.filestamp</i></tt>. Copy both files to all group hosts; they replace the files which would be generated in other schemes. On each host <i>bob</i> install a soft link from the generic name <tt>ntpkey_host_<i>bob</i></tt> to the host key file and soft link <tt>ntpkey_cert_<i>bob</i></tt> to the private certificate file. Note the generic links are on <i>bob</i>, but point to files generated by trusted host <i>alice</i>. In this scheme it is not possible to refresh either the keys or certificates without copying them to all other hosts in the group.</p>
- <p>For the IFF scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-I -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_IFFpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts that operate as both servers and clients and install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. If there are no hosts restricted to operate only as clients, there is nothing further to do. As the IFF scheme is independent of keys and certificates, these files can be refreshed as needed.</p>
- <p>If a rogue client has the parameter file, it could masquerade as a legitimate server and present a middleman threat. To eliminate this threat, the client keys can be extracted from the parameter file and distributed to all restricted clients. After generating the parameter file, on <i>alice</i> run <tt>ntp-keygen</tt> <tt>-e</tt> and pipe the output to a file or mail program. Copy or mail this file to all restricted clients. On these clients install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. To further protect the integrity of the keys, each file can be encrypted with a secret password.</p>
- <p>For the GQ scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-G -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_GQpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts and install a soft link from the generic <tt>ntpkey_gq_<i>alice</i></tt> to this file. In addition, on each host <i>bob</i> install a soft link from generic <tt>ntpkey_gq_<i>bob</i></tt> to this file. As the GQ scheme updates the GQ parameters file and certificate at the same time, keys and certificates can be regenerated as needed.</p>
- <p>For the MV scheme, proceed as in the TC scheme to generate keys and certificates for all group hosts. For illustration assume <i>trish</i> is the TA, <i>alice</i> one of several trusted hosts and <i>bob</i> one of her clients. On TA <i>trish</i> run <tt>ntp-keygen </tt><tt>-V <i>n</i> -p <i>password</i></tt>, where <i>n</i> is the number of revokable keys (typically 5) to produce the parameter file <tt>ntpkeys_MVpar_<i>trish.filestamp </i></tt>and client key files <tt>ntpkeys_MVkey<i>d</i>_<i>trish.filestamp</i></tt> where <i><tt>d</tt></i> is the key number (0 < <i><tt>d</tt></i> < <i>n</i>). Copy the parameter file to <i>alice</i> and install a soft link from the generic <tt>ntpkey_mv_<i>alice</i></tt> to this file. Copy one of the client key files to <i>alice</i> for later distribution to her clients. It doesn't matter which client key file goes to <i>alice</i>, since they all work the same way. <i>Alice</i> copies the client key file to all of her cliens. On client <i>bob</i> install a soft link from generic <tt>ntpkey_mvkey_<i>bob </i></tt>to the client key file. As the MV scheme is independent of keys and certificates, these files can be refreshed as needed.</p>
+ <p>This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It generates MD5 key files used in symmetric key cryptography and, if the OpenSSL software library has been installed, it generates encryption keys, certificates and identity parameters used by the Autokey cryptographic algorithms. All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities.</p>
+ <p>Generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates or certificate requests generated by this or other programs should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity parameter files are probably not compatible with anything other than Autokey.</p>
+ <p>All files written by this program are encrypted using a private password. The <tt>-p <i>passwd2</i></tt> option specifies the write password and the <tt>-q <i>passwd2</i></tt> option the read password for previously encrypted files. If no read password is specified, the host name returned by the Unix <tt>gethostname()</tt> function is used. If no write password is specified, the read password is used as the write password.</p>
+ <p>The <tt>ntpd</tt> configuration command <tt>crypto pw <i>passwd</i></tt> specifies the read password for previously encrypted files. The daemon expires on the spot if a file fails to decrypt properly. For convenience, if the <tt>ntpd</tt> password is not specified, the host name returned by the Unix <tt>gethostname()</tt> function is used. Thus, if files are generated by this program without password, they can be read back by <tt>ntpd</tt> without password, but only on the same machine.</p>
+ <p>All files and links are installed by default in the keys directory <tt>/usr/local/etc</tt>, which is normally in a shared filesystem in NFS-mounted networks. The actual location of the keys directory can be changed by a configuration command. Normally, the files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page.</p>
+ <p>File and link names are in the form <tt>ntpkey_<i>key</i>_<i>name</i>.<i>fstamp</i></tt>, where <tt><i>key</i></tt> is the key type, <tt><i>name</i></tt> is the host or group name and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the file was created. The key type is a string defining the cryptographic function as described in the command line options below. The filestamp is not used in generated link names. Key types include <tt>host</tt>, <tt>sign</tt>, certificate <tt>cert</tt> and several challenge/response key types. By convention, files used for challenges have a <tt>par</tt> subtype, as in the IFF challenge <tt>iffpar</tt>, while files for responses have a <tt>key</tt> subtype, as in the GQ response <tt>gqkey</tt>.</p>
+ <h4 id="run">Running the Program</h4>
+ <p>For conciseness in the following discussion, only the key type portion of the name is used and the prefix and suffix are omitted. The safest way to run this program is log in as root and change to the keys directory, usually <tt>/usr/local/etc. </tt>When run for the first time, or if all <tt>ntpkey</tt> files have been removed, use the</p>
+ <p><tt>ntp-keygen -q <i>passwd1</i></tt></p>
+ <p>command, where <tt><i>passwd1</i></tt> is the password also used by <tt>ntpd</tt>. All <tt>ntp-keygen </tt>commands must include the <tt>-q <i>passwd1</i></tt> as the explicit read password and implicit write password.</p>
+ <p>The program generates an RSA host key file <tt>RSAkey </tt>and link <tt>host</tt>, and matching RSA-MD5 certificate file <tt>RSA-MD5cert</tt> and link <tt>cert</tt>. This is all that is necessary for the Trusted Certificate (TC) identity scheme, which does not use a challenge/response identity scheme. Identity schemes will be described later. If run again with the same command line, the program uses the same host key file, but generates a new certificate file and link. Include the <tt>-H </tt>option to generate all new files and links.</p>
+ <p>Run the command on as many machines as necessary. Designate one of them the trusted host and configure it to synchronize via reliable paths. Then configure the nontrusted servers to synchronize s to the trusted host directly or indirectly but avoid cyclic paths.</p>
+ <p>By default the name used in the host key and certificate file is the string returned by the Unix <tt>gethostname()</tt> function. A different name can be assigned using the <tt>-s <i>host</i></tt> option on the command line. The name must match the <tt>host</tt> name specified in the <tt>crypto</tt> command in the configuration file. The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. A different sign key file name can be assigned using the <tt>-S <i>sign</i></tt> option and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified.</p>
+ <h4 id="trust">Trusted Hosts and Secure Groups</h4>
+ <p>As described on the <a href="authopt.html">Authentication Options</a> page, an NTP secure group consists of one or more low-stratum trusted hosts as the root from which all other group hosts derive synchronization directly or indirectly via acyclic certificate trails. For cryptographic purposes all trusted hosts in a group have the same name, which is also the name of the group. Trusted hosts have trusted, self-signed certificates; all other hosts have nontrusted, self-signed certificates. A certificate trail is constructed by asking the immediately ascendant host toward the root to sign its certificate, which is then provided to the immediately descendant host on request.</p>
+ <p>It is convenient to nominate a single trusted host acting as a trusted authority (TA) to generate a set of files that are then copied intact to all other trusted hosts in the group, most conveniently as a tar archive. This means that it doesn't matter which certificate trail ends at which trusted host, since the rootcertificate and identity data are the same. To generate and install cryptographic media files on the TA as root, use the <tt>-s <i>host</i></tt> option to specify the host name and the <tt>-T</tt> option to specify a trusted certificate. If run again with the same command line, the program uses the same host key file, but generates a new certificate file and link. Include the <tt>-H </tt>option to generate all new files and links.</p>
+ <p>To generate and install cryptgrahic media files on nontrusted hosts as root, use the <tt>-i <i>group</i></tt> option to specify the group name and nontrusted certificate. This option has no effect unless one of the identity schemes described in the next section is used, but it does help to minimize errors when configuriong certificate trails.</p>
+ <h4 id="ident">Identity Schemes</h4>
+ <p>As described on the <a href="authopt.html">Authentication Options</a> page, there are five identity schemes, three of which, IFF, GQ and MV, have password protected identity files. A file specific to each scheme and group is generated by the TA and then copied to all trusted hosts. In the intended model a group host sends a mail request message to the TA including its private key. The TA encrypts the identity file with that key an returns it in a mail message. The attachment is then copied intact to the keys director and renamed as directed below.</p>
+ <p>Use the following procedure to produce IFF parameters for nontrusted group hosts. The procedure is similar for the GQ parameters. The TA uses the</p>
+ <p><tt>intp-keygen -q <i>passwd1</i> -p <i>passwd2 </i>-i <i>group</i></tt></p>
+ <p>command to generate IFF parameters, where <tt><i>passwd1</i></tt> is the trusted host password and <tt><i>passwd2</i></tt> is the intended recipient password and must be different from <tt><i>passwd1</i></tt>. The particular identity scheme selected and the parmeter file type will match the scheme selected by the TA when first generating its own files.</p>
+ <p>The group parameters are written to the standard output stream <tt>stdout<i> </i></tt>where they can be piped to an application that sends the contents to the intended recipient as a MIME attachment. The identity parameters are installed in the keys directory and renamed as in the first line of the file, but without the filestamp.</p>
+ <p>The NTP secure group rules require that a all hsts have the same name; however, a trusted host can be a client of one or more other groups operating at a lower stratum. The trusted host or hosts have identity keys for their group as well as identity parameters for each of the lower stratum groups. These parameters can be obtained from the TA of each group.</p>
+ <p>During the Autokey protocol with the selected lower stratum hosts, the trusted host hikes the certificate trail to obtain and install the trusted host certificate of the lower stratum group. The subject name on this certificate is used to load the identity parameters for that group.</p>
+ <p>In the IFF scheme the TA generates the IFF key file including a private key and the parameters needed to verify identity to a dependent client. The parameter file is normally a copy of this file; however, using the <tt>-e</tt> option on the <tt>ntp-keygen</tt> command line, the parameter file includes only the parameters and not the private key. A client without the private key cannot prove identity to dependent client.</p>
+ <p>In the GQ scheme the TA generates the key and parameter files in separate steps and provides only the parameter file to other group hosts. However, any host can use <tt>ntp-keygen</tt> to create a new GQ key file to prove identity to dependent client.</p>
<h4 id="cmd">Command Line Options</h4>
<dl>
<dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt>
- <dd>Select certificate message digest/signature encryption scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>.
+ <dd>Select certificate and message digest/signature encryption scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>.
<dt><tt>-d</tt>
- <dd>Enable debugging. This option displays the cryptographic data produced in eye-friendly billboards.
- <dt><tt>-e</tt>
- <dd>Write the IFF client keys to the standard output. This is intended for automatic key distribution by mail.
- <dt><tt>-G</tt>
- <dd>Generate parameters and keys for the GQ identification scheme, obsoleting any that may exist.
+ <dd>Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.<dt><tt>-e</tt>
+ <dd>Generate IFF parameter file <tt>IFFpar</tt> from an existing IFF key file <tt>IFFkey</tt>. This is commonly done to produce IFF parameters for hosts acting only as clients without revealing the private key. Note: This option is active only when the write password is different than the read password.<dt><tt>-G</tt>
+ <dd>Generate GQ key file <tt>GQkey </tt>and link <tt>gqkey </tt>for the Guillou-Quisquater (GQ) identity scheme, obsoleting any that may exist.
<dt><tt>-g</tt>
- <dd>Generate keys for the GQ identification scheme using the existing GQ parameters. If the GQ parameters do not yet exist, create them first.
+ <dd>Generate GQ parameter file <tt>GQpar </tt>for the Guillou-Quisquater (GQ) identity scheme, obsoleting any that may exist. This option is normally used when the read pasword and write password are different.
<dt><tt>-H</tt>
- <dd>Generate new host keys, obsoleting any that may exist.
- <dt><tt>-I</tt>
- <dd>Generate parameters for the IFF identification scheme, obsoleting any that may exist.
- <dt><tt>-i <i>name</i></tt>
- <dd>Set the suject name to <i>name</i>. This is used as the subject field in certificates and in the file name for host and sign keys.
- <dt><tt>-M</tt>
+ <dd>Generate public/private host keys <tt>RSAkey</tt>, and link <tt>host, </tt>obsoleting any that may exist.<dt><tt>-I</tt>
+ <dd>Generate parameters <tt>IFFpar </tt>and link <tt>iff </tt>for the Schnorr (IFF) identity scheme, obsoleting any that may exist.<dt><tt>-i <i>name</i></tt>
+ <dd>Set the group name to <tt><i>name</i></tt>. This is used as the file name for identity parameters. If this option is not present, the group name defaults to the host name.<dt><tt>-M</tt>
<dd>Generate MD5 keys, obsoleting any that may exist.
<dt><tt>-P</tt>
- <dd>Generate a private certificate. By default, the program generates public certificates.
- <dt><tt>-p <i>password</i></tt>
- <dd>Encrypt generated files containing private data with <tt><i>password</i></tt> and the DES-CBC algorithm.
- <dt><tt>-q</tt>
- <dd>Set the password for reading files to <tt><i>password</i></tt>.
+ <dd>Generate a private certificate used by the PC identity scheme. By default, the program generates public certificates.<dt><tt>-p <i>password</i></tt>
+ <dd>Set the password for writing encrypted files to <tt><i>password</i></tt>.<dt><tt>-q <i>password</i></tt>
+ <dd>Set the password for reading encrypted files to <tt><i>password</i></tt>.
<dt><tt>-S [ RSA | DSA ]</tt>
<dd>Generate a new sign key of the designated type, obsoleting any that may exist. By default, the program uses the host key as the sign key.
<dt><tt>-s <i>name</i></tt>
- <dd>Set the issuer name to <i>name</i>. This is used for the issuer field in certificates and in the file name for identity files.
- <dt><tt>-T</tt>
+ <dd>Set the host name to <tt><i>name</i></tt>. This is used for the host key as well as the subject and issuer names in certificates.<dt><tt>-T</tt>
<dd>Generate a trusted certificate. By default, the program generates a non-trusted certificate.
<dt><tt>-V <i>nkeys</i></tt>
- <dd>Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme.
- </dl>
+ <dd>Generate server parameters <tt>MV</tt> and <tt><i>nkeys</i></tt> client keys for the Mu-Varadharajan (MV) identity scheme. Note: support for this option should be considered a work in progress.</dl>
<h4 id="rand">Random Seed File</h4>
- <p>All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the library routines. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting the NTP daemon and <tt>ntp-keygen</tt> program. If a site supports OpenSSL or its companion OpenSSH, it is very likely that means to do this are already available.</p>
- <p>It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources. Suitable means are described in the OpenSSL software documentation, but are outside the scope of this page.</p>
- <p>The entropy seed used by the OpenSSL library is contained in a file, usually called <tt>.rnd</tt>, which must be available when starting the NTP daemon or the <tt>ntp-keygen</tt> program. The NTP daemon will first look for the file using the path specified by the <tt>randfile</tt> subcommand of the <tt>crypto</tt> configuration command. If not specified in this way, or when starting the <tt>ntp-keygen</tt> program, the OpenSSL library will look for the file using the path specified by the <tt>RANDFILE</tt> environment variable in the user home directory, whether root or some other user. If the <tt>RANDFILE</tt> environment variable is not present, the library will look for the <tt>.rnd</tt> file in the user home directory. If the file is not available or cannot be written, the daemon exits with a message to the system log and the program exits with a suitable error message.</p>
+ <p>All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the OpenSSL library routines. If a site supports <tt>ssh</tt>, it is very likely that means to do this are already available. The entropy seed used by the OpenSSL library is contained in a file, usually called <tt>.rnd</tt>, which must be available when starting the <tt>ntp-keygen</tt> program or <tt>ntpd</tt> daemon.</p>
+ <p>The OpenSSL library looks for the file using the path specified by the <tt>RANDFILE</tt> environment variable in the user home directory, whether root or some other user. If the <tt>RANDFILE</tt> environment variable is not present, the library looks for the <tt>.rnd</tt> file in the user home directory. Since both the <tt>ntp-keygen</tt> program and <tt>ntpd</tt> daemon must run as root, the logical place to put this file is in <tt>/.rnd</tt> or <tt>/root/.rnd</tt>. If the file is not available or cannot be written, the program exits with a message to the system log.</p>
<h4 id="priv">Cryptographic Data Files</h4>
- <p>All other file formats begin with two lines. The first contains the file name, including the generated host name and filestamp. The second contains the datestamp in conventional Unix <tt>date</tt> format. Lines beginning with <tt>#</tt> are considered comments and ignored by the <i><tt>ntp-keygen </tt></i>program and <tt>ntpd</tt> daemon. Cryptographic values are encoded first using ASN.1 rules, then encrypted if necessary, and finally written PEM-encoded printable ASCII format preceded and followed by MIME content identifier lines.</p>
- <p id="symkey">The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since DES-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Following hte heard the keys are entered one per line in the format</p>
+ <p>All file formats begin with two lines. The first line contains the file name, in the format <tt>ntpkey_<i>key</i>_<i>host</i>.<i>fstamp</i></tt>, where <tt><i>key</i></tt> is the key type, <tt><i>host</i></tt> is the group or host name and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the file was created. The second line contains the datestamp in conventional Unix <tt>date</tt> format. Lines beginning with <tt>#</tt> are ignored.</p>
+ <p>The remainder of the file contains cryptographic data encoded first using ASN.1 rules, then encrypted using the DES-CBC algorithm and given password and finally written in PEM-encoded printable ASCII text preceded and followed by MIME content identifier lines.</p>
+ <p id="symkey">The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since DES-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Following the header the keys are entered one per line in the format</p>
<p><i><tt>keyno type key</tt></i></p>
<p>where <i><tt>keyno</tt></i> is a positive integer in the range 1-65,535, <i><tt>type</tt></i> is the string <tt>MD5</tt> defining the key format and <i><tt>key</tt></i> is the key itself, which is a printable ASCII string 16 characters or less in length. Each character is chosen from the 93 printable characters in the range 0x21 through 0x7f excluding space and the '#' character.</p>
<p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in human readable ASCII format.</p>
projects / thirdparty / ntp.git / commitdiff
