NetBSD/dist/ntp/html/authopt.htm

279 lines
14 KiB
HTML

<html><head><title>
Authentication Options
</title></head><body><h3>
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
process is complete.
<H4>Private 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
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>
utility programs.
<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,
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.
<H4>Autokey Schemes</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
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
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
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.
<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
same security compartment and made visible only to root. The
<tt>ntpkey</tt> file contains the RSA private key. It is useful only to
the machine that generated it and never shared with any other daemon or
application program, so must be made visible only to root. The
<tt>ntp_dh</tt> file contains the Diffie-Hellman parameters. It is
necessary that all servers and clients of a security compartment share a
single <tt>ntp_dh</tt> file, but it does not matter which one. This file
can be distributed using insecure means, since the data are public
values.
<p>The <tt>ntpkey_<i>host</i></tt> file contains the RSA public key,
where <tt><i>host</i></tt> is the name of the host. Each configured
<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.
<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.
<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.
<H4>Authentication Commands</H4>
<DL>
<dt><tt>autokey [<i>logsec</i>]</tt>
<dd>Specifies the interval between regenerations of the session key list
used with the autokey feature. 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.</dd>
<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
identifier for a trusted key, where the value can be in the range 1 to
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
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>
<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>
<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>
<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>
</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>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
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
trusted key, where the value can be in the range 1 to 65534, inclusive.
</DD>
<dt><tt>revoke [<i>logsec</i>]</tt>
<dd>Specifies the interval between re-randomization of certain
cryptographic values used by the autokey scheme, as a power of 2 in
seconds. These values need to be updated frequently in order to deflect
brute-force attacks on the algorithms of the scheme; however, updating
some values is a relatively expensive operation. The default interval is
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
purposes of authenticating peers suitable for synchronization, as well
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>
</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
<br><tt>ntp_dh</tt> Diffie-Hellman parameters
<h4>Bugs</h4>
The <tt>ntpkey_<i>host</i></tt> files are really digital certificates.
These should be obtained via secure directory services when they become
universally available.
<hr><a href=index.htm>Home</a><address><a
href=mailto:mills@udel.edu> David L. Mills &lt;mills@udel.edu&gt;</a>
</address></a></body></html>