Authentication Options
</h3><hr>
-<H4>Authentication Support</H4>
-
-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 an scheme which provides cryptographic authentication
-of received NTP packets. Originally, this was done using the Data
-Encryption Standard (DES) operating in Cipher Block Chaining (CBC) mode,
-commonly called DES-CBC. Subsequently, this was augmented by the RSA
-Message Digest 5 (MD5) 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>NTPv4 retains the NTPv3 schemes and, in addition, provides a new
-<I>autokey</I> scheme based on reverse hashing and public key
-cryptography. Authentication can be configured separately for each
-association using the <TT>key</TT> or <TT>autokey</TT> subcommands on
-the <TT>peer</TT>, <TT>server</TT>, <TT>broadcast</TT> and
-<TT>manycastclient</TT> commands as described in the <A
-HREF="config.htm">Configuration Options</A> page.
-
-<P>The authentication options specify the suite of keys, select the key
-for each configured association and manage the configuration operations,
-as described below. The <TT>auth</TT> flag which controls these
-functions can be set or reset by the <TT>enable</TT> and
-<TT>disable</TT> configuration commands and also by remote configuration
-commands sent by a <TT>ntpdc</TT> program running in another machine. If
-this flag is set, persistent peer associations and remote configuration
-commands are effective only if cryptographically authenticated. If this
-flag is disabled, these operations are effective even if not
-cryptographic authenticated. It should be understood that operating in
-the latter mode invites a significant vulnerability where a rogue hacker
-can seriously disrupt client timekeeping.
-
-<P>The <TT>auth</TT> flag affects all authentication procedures
-described below; however, it operates differently if cryptographic
-support (<tt>AUTOKEY</tt>) is compiled in the distribution, which is
-normally the case. If this support is available and the flag is enabled,
-then persistent associations are mobilized in multicast client and
-symmetric passive modes and remote configuration commands are effective
-only if successfully authenticated. If the support is unavailable and
-the flag is enabled, then it is not possible under any conditions to
-mobilize persistent associations or respond to remote configuration
-commands. The <TT>auth</TT> flag normally defaults to set if
-cryptographic support is available and to reset otherwise.
-
-<P>With the above vulnerabilities in mind, it is desirable to set the
-<tt>auth</TT> flag in all cases. One aspect which is often confusing is
-the name resolution process which maps server names in the configuration
-file to IP addresses. In order to protect against bogus name server
-messages, this process is authenticated using an internally generated
-key which is normally invisible to the user. However, if cryptographic
-support is unavailable and the <TT>auth</TT> flag is enabled, the name
-resolution process will fail. This can be avoided either by specifying
-IP addresses instead of host names, which is generally inadvisable, or
-by leaving the flag disabled and enabling it once the name resolution
+<h4>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 an 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
+augmented 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>NTPv4 retains the NTPv3 schemes, properly described as symmetric-key
+cryptography and, in addition, provides a new <i>autokey</i> 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 server
+and never revealed. With autokey all key distribution and management
+functions involve only public values, which considerably simplifies key
+distribution and storage.
+
+<p>Authentication is configured separately for each association using
+the <tt>key</tt> or <tt>autokey</tt> subcommands on the <tt>peer</tt>,
+<tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> commands
+as described in the <A HREF="config.htm">Configuration Options</A> page.
+The authentication options described below specify the suite of keys,
+select the key for each configured association and manage the
+configuration operations.
+
+<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>
+configuration commands and also by remote configuration commands sent by
+a <tt>ntpdc</tt> program running in another machine. If this flag is
+enabled, new broadcast client and symmetric passive associations and
+remote configuration commands must be cryptographically authenticated
+using either symmetric-key or public-key schemes. If this flag is
+disabled, these operations are effective even if not cryptographic
+authenticated. It should be understood that operating in the latter mode
+invites a significant vulnerability where a rogue hacker can seriously
+disrupt client timekeeping.
+
+<p>In networks with firewalls and large numbers of broadcast clients it
+may be acceptable to disable authentication, since that avoids key
+distribution and simplifies network maintenance. However, when the
+configuration file contains host names, or when a server or client is
+configured remotely, host names are resolved using the DNS and a
+separate name resolution process. In order to protect against bogus name
+server messages, name resolution messages are authenticated using an
+internally generated key which is normally invisible to the user.
+However, if cryptographic support is disabled, the name resolution
+process will fail. This can be avoided either by specifying IP addresses
+instead of host names, which is generally inadvisable, or by enabling
+the flag for name resolution and disabled it once the name resolution
process is complete.
-<H4>Private Key Scheme</H4>
+<p>In addition to the default symmetric-key cryptographic support,
+support for public-key cryptography is available if the requisite
+<tt>rsaref20</tt> software distribution has been installed before
+building the distribution. Public-key cryptography provides secure
+authentication of servers without compromising accuracy and stability.
+The security model and protocol schemes for both symmetric-key and
+public-key cryptography are described below.
+
+<h4>Symmetric-Key Scheme</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 involved must agree on the key and key
identifier to authenticate their messages. Keys and related information
-are specified in a key file, usually called <TT>ntp.keys</TT>, which
+are specified in a key file, usually called <tt>ntp.keys</tt>, which
should be exchanged and stored using secure procedures beyond the scope
of the NTP protocol itself. Besides the keys used for ordinary NTP
-associations, additional
ones can be used as passwords for the <TT><A
-HREF="ntpq.htm">ntpq</A></TT> and <TT><A HREF="ntpdc.htm">ntpdc</A></TT>
+associations, additional
keys can be used as passwords for the <tt><A
+HREF="ntpq.htm">ntpq</A></tt> and <tt><A HREF="ntpdc.htm">ntpdc</A></tt>
utility programs.
-<P>When <TT>ntpd</TT> is first started, it reads the key file and
+<p>When <tt>ntpd</tt> is first started, it reads the key file and
installs the keys in the key cache. However, the keys must be activated
-before they can be used with the <TT>trusted</TT> command. This allows,
+before they can be used with the <tt>trusted</tt> command. 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.
+<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.
-<H4>Autokey Schemes</H4>
+<h4>Public-Key Scheme</h4>
The original NTPv3 authentication scheme described in RFC-1305 continues
to be supported; however, in NTPv4 an additional authentication scheme
-called <I>autokey</I> is available. It uses MD5 message digest, RSA
-public-key signature and Diffie-Hellman key agreement algorithms
-available from several sources, but not included in the NTPv4 software
-distribution. In order to be effective, the <tt>rsaref20</tt> package
-must be installed as described in the <tt>README.rsa</tt> file. Once
-installed, the configure and build process automatically detects it and
+called autokey is available. It uses MD5 message digest, RSA public-key
+signature and Diffie-Hellman key agreement algorithms available from
+several sources, but not included in the NTPv4 software distribution. In
+order to be effective, the <tt>rsaref20</tt> package must be installed
+as described in the <tt>README.rsa</tt> file. Once installed, the
+configure and build process automatically detects it and
compiles the routines required.
-The scheme has several modes of operation corresponding to the various
-NTP modes supported. RSA signatures and timestamps are used in all modes
-to verify the source of cryptographic values. All modes use a special
-cookie which can be computed independently by the client and server. In
-symmetric modes the cookie is constructed using the Diffie-Hellman key
-agreement algorithm. In other modes the cookie is constructed from the
-IP addresses and a private value known only to the server. Multicast and
-symmetric 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
+The autokey scheme has several modes of operation corresponding to the
+various NTP modes supported. RSA signatures with timestamps are used in
+all modes to verify the source of cryptographic values. All modes use a
+special cookie which can be computed independently by the client and
+server. In symmetric modes the cookie is constructed using the
+Diffie-Hellman key agreement algorithm. In other modes the cookie is
+constructed from the IP addresses and a private value known only to the
+server. Multicast and symmetric 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/~mills/autokey.htm>Autonomous
Authentication</a> page.
-<p>The cryptographic values used by the <tt>autokey</tt> scheme are
-
incorporated as a set of files generated by the <a
+<p>The cryptographic values used by the autokey scheme are incorporated
+as a set of files generated by the <a
href=genkeys.htm><tt>ntp_genkeys</tt></a> program, including the DES/MD5
private keys, RSA public/private key pair, and the Diffie-Hellman
parameters. See the <tt>ntp_genkeys</tt> page for a description of the
-format and use of these files. They contain cryptographic values
-generated by the algorithms of the <tt>rsaref20</tt> package and are in
-printable ASCII format. Since the algorithms are seeded by the system
-clock, each run of this program will produce a different outcome.
+formats of these files. They contain cryptographic values generated by
+the algorithms of the <tt>rsaref20</tt> package and are in printable
+ASCII format. All file names include the timestamp, in NTP seconds,
+following the default names given below. Since the file data are derived
+from random values seeded by the system clock and the file name includes
+the timestamp, every generation produces a different file.
<p>The <tt>ntp.keys</tt> file contains the private DES/MD5 keys. It must
be distributed by secure means to other servers and clients sharing the
<tt>server</tt> or <tt>peer</tt> association requires the public key
file associated with the particular server or peer to be installed at a
default location or as specified by the commands below. In addition,
-public key files are required for associations that might be mobilized
-by multicast or symmetric servers. These files can be widely distributed
-and stored using insecure means, since the data are public values.
+public key files are required for all configured associations, including
+those that might be mobilized by multicast servers or symmetric peers.
+These files can be widely distributed and stored using insecure means,
+since the data are public values.
<p>Due to the widespread use of interface-specific naming, the host
names used in configured and mobilized associations are determined by
-different rules. The <tt>ntp_genkeys</tt> program uses the name returned
-by the Unix <tt>gethostname()</tt> library routine and this is the name
-normally used when installing the file on some other host. However, the
-default name used when configuring an association at run time is the
-canonical name returned by the DNS resolver, and this might not be the
-same name. The preferred workaround on the host installing the file is
-to use the Unix <tt>nslookup</tt> command to determined the canonical
-name and install a link from that name to the actual name.
-Alternatively, the default can be overriden with by the
-<tt>publickey</tt> subcommand of the <tt>server</tt> or <tt>peer</tt>
-configuration command.
-
-<p>For other than configured associations that might be mobilized by
-multicast servers or symmetric peers, the name is determined directly
-from the server or peer as part of the protocol dance that authenticates
-the source. The server or peer uses the same <tt>gethostname()</tt>
-library routine as the <tt>ntp_genkeys</tt> program, so there is no
-confusion.
+the Unix <tt>gethostname()</tt> library routine. Both the
+<tt>ntp_genkeys</tt> program and the run-time protocol derive the name
+of the public key file using the name returned by this routine. While it
+is usually necessary to configure the private key file name and
+timestamp, the server and peer public file names are normally obtained
+directly from the server or peer.
+
+<h4>Key Management</h4>
<p>All key files are installed by default in <tt>/usr/local/etc</tt>,
which is normally in a shared filesystem in NFS-mounted networks and
avoids installing them in each machine separately. The default can be
-overriden by the <tt>keysdir</tt> configuration file command. However,
-this is not a good place to install the private key file, since each
-machine needs its own file. A suitable place to install it is
-<tt>/etc</tt>, which is normally not in a shared filesystem. The default
-can be overriden by the <tt>subcommand</tt> of the <tt>crypto</tt>
-configuration command.
+overridden by the <tt>keysdir</tt> configuration command. However, this
+is not a good place to install the private key file, since each machine
+needs its own file. A suitable place to install it is <tt>/etc</tt>,
+which is normally not in a shared filesystem. The location can be
+overridden by the <tt>crypto</tt> configuration command.
+
+<p>All cryptographic keys and parameters should be regenerated on a
+periodic basis, like once per month. The <tt>ntp_genkeys</tt> program uses the same timestamp extension for all files generated at one time, so each generation is distinct and can be readily recognized. However, by default the file names expected by <tt>ntpd</tt> are without the timestamp extension. A simple approach to key maintenance is to distribute newly generated public files without the extension and install them in each server and client while in normal operation. This avoids the need to edit the NTP configuration file for each new generation.
+
+<p>A server and its clients load a new key generation in the following way. The server and its clients have loaded the old generation at startup and are operating normally. The new generation is installed at the server and its clients while the old generation is running. The server then restarts <tt>ntpd</tt> and loads the new generation, with result the clients no longer can authenticate. After a few minutes the clients time out and restart the protocol from the beginning, with result the new generation is loaded and operation continues normally.
-<H4>Authentication Commands</H4>
+<p>Key distribution can be done semi-automatically using a set of shell scripts and the Unix <tt>rdist</tt> utility. Each server runs the <tt>ntp_genkeys</tt> program from a <tt>cron</tt> job, and uploads the relevant public files to a common location accessible to the <tt>rdist</tt> utility. At that location a script selects one of the Diffie-Hellman files and bundles it along with the latest generation of public-key files for <tt>rdist</tt>, which downloads them to all servers and clients.
-<DL>
+<h4>Authentication Commands</h4>
+
+<dl>
<dt><tt>autokey [<i>logsec</i>]</tt>
<dd>Specifies the interval between regenerations of the session key list
above the specified interval, a session key list with a single entry
will be regenerated for every message sent.</dd>
-<DT><TT>controlkey <I>key</I></TT></DT>
-<DD>Specifies the key identifier to use with the <TT>ntpq</TT> program,
+<dt><tt>controlkey <i>key</i></tt></dt>
+<dd>Specifies the key identifier to use with the <tt>ntpq</tt> program,
which uses the standard protocol defined in RFC-1305. This program is
-useful to diagnose and repair problems that affect <TT>ntpd</TT>
-operation. The <TT><I>key</I></TT> argument to this command is a key
+useful to diagnose and repair problems that affect <tt>ntpd</tt>
+operation. The <tt><i>key</i></tt> argument to this command is a key
identifier for a trusted key, where the value can be in the range 1 to
-65534, inclusive.</DD>
+65534, inclusive.</dd>
-<DT><TT>crypto [privatekey <i>file</i>] [publickey <i>file</i>] [dhparms
-<i>file</i>] </TT></DT>
-<DD>This command requires the NTP daemon build process be configured
+<dt><tt>crypto [privatekey <i>file</i>] [publickey <i>file</i>] [dhparms
+<i>file</i>] </tt></dt>
+<dd>This command requires the NTP daemon build process be configured
with the RSA library. The presence of this command causes the daemon to
load the host RSA private key file, public key file and Diffie-Hellman
parameter file. If one or more files are left unspecified, the default
-names are used as described above. Following are the subcommands:</DD>
+names are used as described above. Following are the subcommands:</dd>
<dl>
<dt><tt>privatekey <i>file</tt></i>
<dd>Specifies the directory for the RSA private key file, which
-otherwise defaults to <tt>/usr/local/etc<tt>.</dd>
+otherwise defaults to <tt>/usr/local/etc</tt>.</dd>
<dt><tt>publickey <i>file</tt></i>
<dd>Specifies the directory for the RSA public key file, which otherwise
-defaults to <tt>/usr/local/etc<tt>.</dd>
+defaults to <tt>/usr/local/etc</tt>.</dd>
<dt><tt>dhparms <i>file</tt></i>
<dd>Specifies the directory for the Diffie-Hellman parameters file,
-which otherwise defaults to <tt>/usr/local/etc<tt>.</dd>
+which otherwise defaults to <tt>/usr/local/etc</tt>.</dd>
</dl>
-<DT><TT>keys <I>keyfile</I></TT></DT>
-<DD>Specifies the file name containing the private encryption keys and
-key identifiers used by <TT>ntpd</TT>, <TT>ntpq</TT> and <TT>ntpdc</TT>
-when operating in authenticated mode.</DD>
+<dt><tt>keys <i>keyfile</i></tt></dt>
+<dd>Specifies the file name containing the private encryption keys and
+key identifiers used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt>
+when operating in authenticated mode.</dd>
-<DT><TT>keysdir <I>path</I></TT></DT>
-<DD>This command requires the NTP daemon build process be configured
+<dt><tt>keysdir <i>path</i></tt></dt>
+<dd>This command requires the NTP daemon build process be configured
with the RSA library. It specifies the default directory path for the
private key file, parameters file and one or more public key files. The
default when this command does not appear in the configuration file is
<tt>/usr/local/etc/</tt>.</dd>
-<DT><TT>requestkey <I>key</I></TT></DT>
-<DD>Specifies the key identifier to use with the <TT>ntpdc</TT> utility
+<dt><tt>requestkey <i>key</i></tt></dt>
+<dd>Specifies the key identifier to use with the <tt>ntpdc</tt> utility
program, which uses a proprietary protocol specific to this
-implementation of <TT>ntpd</TT>. This program is useful to diagnose and
-repair problems that affect <TT>ntpd</TT> operation. The
-<TT><I>key</I></TT> argument to this command is a key identifier for a
+implementation of <tt>ntpd</tt>. This program is useful to diagnose and
+repair problems that affect <tt>ntpd</tt> operation. The
+<tt><i>key</i></tt> argument to this command is a key identifier for a
trusted key, where the value can be in the range 1 to 65534, inclusive.
-</DD>
+</dd>
<dt><tt>revoke [<i>logsec</i>]</tt>
<dd>Specifies the interval between re-randomization of certain
16 (65,536 s or about 18 hours). For poll intervals above the specified
interval, the values will be updated for every message sent.</dd>
-<DT><TT>trustedkey <I>key</I> [...]</TT></DT>
-<DD>Specifies the encryption key identifiers which are trusted for the
+<dt><tt>trustedkey <i>key</i> [...]</tt></dt>
+<dd>Specifies the encryption key identifiers which are trusted for the
purposes of authenticating peers suitable for synchronization, as well
-as keys used by the <TT>ntpq</TT> and <TT>ntpdc</TT> programs. The
+as keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. The
authentication procedures require that both the local and remote servers
share the same key and key identifier for this purpose, although
different keys can be used with different servers. The
-<TT><I>key</I></TT> arguments are 32-bit unsigned integers with values
-from 1 to 65,534.</DD>
+<tt><i>key</i></tt> arguments are 32-bit unsigned integers with values
+from 1 to 65,534.</dd>
-</DL>
+</dl>
<h4>Files</h4>
+
<tt>ntp.keys</tt> private MD5 keys
<br><tt>ntpkey</tt> RSA private key
<br><tt>ntpkey_<i>host</i></tt> RSA public key
projects / thirdparty / ntp.git / commitdiff
