<hr>
<h4>Access Control Support</h4>
-<tt>ntpd</tt> implements a general purpose address-and-mask based
-restriction list. The list is sorted by address and by mask, and
-the list is searched in this order for matches, with the last match
-found defining the restriction flags associated with the incoming
-packets. The source address of incoming packets is used for the
-match, with the 32- bit address being and'ed with the mask
-associated with the restriction entry and then compared with the
-entry's address (which has also been and'ed with the mask) to look
-for a match. Additional information and examples can be found in
-the <a href="notes.htm">Notes on Configuring NTP and Setting up a
-NTP Subnet</a> page.
+<tt>ntpd</tt> implements a general purpose address/mask based
+restriction list. The list contains address/match entries sorted
+first by increasing address values and and then by increasing mask
+values. A match occurs when the bitwise AND of the mask and the
+packet source address is equal to the bitwise AND of the mask and
+address in the list. The list is searched in order with the last
+match found defining the restriction flags associated with the
+entry. Additional information and examples can be found in the <a
+href="notes.htm">Notes on Configuring NTP and Setting up a NTP
+Subnet</a> page.
<p>The restriction facility was implemented in conformance with the
access policies for the original NSFnet backbone time servers.
-While this facility may be otherwise useful for keeping unwanted or
-broken remote time servers from affecting your own, it should not
-be considered an alternative to the standard NTP authentication
-facility. Source address based restrictions are easily circumvented
-by a determined cracker.</p>
+Later the facility was expanded to deflect cryptographic and
+clogging attacks. While this facility may be useful for keeping
+unwanted or broken or malicious clients from congesting innocent
+servers, it should not be considered an alternative to the NTP
+authentication facilities. Source address based restrictions are
+easily circumvented by a determined cracker.</p>
+
+<p>Clients can be denied service because they are explicitly
+included in the restrict list created by the <tt>restrict</tt>
+command or implicitly as the result of cryptographic or rate limit
+violations. Cryptographic violations include certificate or
+identity verification failure; rate limit violations generally
+result from multiple clients from the same network congesting the
+server . Cryptographic violations cause the single offender to be
+denied further access, while rate limit violations cause the entire
+network to be denied access. When a client or network is denied
+access for these reasons, the only way at present to remove the
+restrictions is by restarting the server.</p>
<h4>The Kiss-of-Death Packet</h4>
more proactive response is needed, such as a server message that
explicitly requests the client to stop sending and leave a message
for the system operator. A special packet format has been created
-for this purpose called the kiss-of-death packet. If the <tt>
-kod</tt> flag is set and either service is denied or the client
-limit is exceeded, the server it returns the packet and sets the
-leap bits unsynchronized, stratum zero and the ASCII string "DENY"
-in the reference source identifier field. If the <tt>kod</tt> flag
-is not set, the server simply drops the packet.</p>
-
-<p>A client or peer receiving a kiss-of-death packet performs a set
-of sanity checks to minimize security exposure. If this is the
-first packet received from the server, the client assumes an access
-denied condition at the server. It updates the stratum and
-reference identifier peer variables and sets the access denied
-(test 4) bit in the peer flash variable. If this bit is set, the
-client sends no packets to the server. If this is not the first
-packet, the client assumes a client limit condition at the server,
-but does not update the peer variables. In either case, a message
-is sent to the system log.</p>
+for this purpose called the "kiss-of-death" (KOD) packet. KOD
+packets have the leap bits set unsynchronized and stratum set to
+zero and the reference identifier field set to a four-byte ASCII
+code. If the <tt>noserve</tt> flag of the matching restrict list
+entry is set, the code is "DENY"; if the <tt>limited</tt> flag is
+set and the rate limit is exceeded, the code is "RATE". Finally, if
+a cryptographic violation occurs, the code is "CRYP".</p>
+
+<p>A client receiving a KOD performs a set of sanity checks to
+minimize security exposure, then updates the stratum and reference
+identifier peer variables, sets the access denied (TEST4) bit in
+the peer flash variable and sends a message to the log. As long as
+the TEST4 bit is set, the client will send no further packets to
+the server. The only way at present to recover from this condition
+is to restart the protocol at both the client and server. This
+happens automatically at the client when the association times out.
+It will happen at the server only if the server operator
+cooperates.</p>
<h4>Access Control Commands</h4>
[<i>flag</i>][...]</tt></dt>
<dd>The <i><tt>numeric_address</tt></i> argument, expressed in
-dotted- quad form, is the address of an host or network. The <i>
-<tt>mask</tt></i> argument, also expressed in dotted-quad form,
+dotted-quad form, is the address of a host or network. The <i><tt>
+mask</tt></i> argument, also expressed in dotted-quad form,
defaults to <tt>255.255.255.255</tt>, meaning that the <i><tt>
numeric_address</tt></i> is treated as the address of an individual
host. A default entry (address <tt>0.0.0.0</tt>, mask <tt>
<dl>
<dt><tt>kod</tt></dt>
-<dd>If access is denied, send a kiss-of-death packet.</dd>
+<dd>An access violation normally results in an automatic
+kiss-of-death (KOD) packet, after which the <tt>kod</tt> flag is
+seet to prevent further KOD packets. If the <tt>kod</tt> flag is
+set in the <tt>restrict</tt> command, a KOD packet will not be
+sent.</dd>
<dt><tt>ignore</tt></dt>
is enabled, the commands specify the message digest and signature
encryption scheme.</p>
-<p>Authentication is always enabled, although ineffective if no
-keys are configured as described below. If a NTP packet arrives
-including a message authentication code (MAC), only if it passes
-all cryptographic checks is it accepted for further processing. The
-checks require correct key ID, key value and message contents. 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.
+<p>Authentication is always enabled, although ineffective if not
+configured as described below. If a NTP packet arrives including a
+message authentication code (MAC), only if it passes all
+cryptographic checks is it accepted for further processing. 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 public key, verify its credentials
and compute a private session key.</p>
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 in another machine. If
-this flag is enabled, which is the default case, 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.</p>
-
-<p>It should be understood that operating with the <tt>auth</tt>
-disabled invites a significant vulnerability where a rogue hacker
-can 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 client and symmetric
-passive associations and remote configuration commands and, in
-particular, the flag has no effect on the authentication process
-itself.</p>
-
-<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 configuration 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 <tt>
-auth</tt>flag for name resolution and disabled it once the name
-resolution process is complete.</p>
+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 schemes. 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> disabled invites a significant vulnerability
+where a rogue hacker can 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>An attractive alternative where multicast support is available
is manycast mode, in which clients periodically troll for servers
as described in the <a href="assoc.htm">Association Management</a>
-page. Cryptographic authentication in this mode the Autokey
-protocol described below. The principle advantage of manycast mode
-is that potential servers need not be configured in advance, since
-the client finds them during regular operation, and the
-configuration files for all clients can be identical.</p>
+page. Either symmetric key or public key cryptographic
+authentication can be used in this mode. The principle advantage of
+manycast mode is that potential servers need not be configured in
+advance, since the client finds them during regular operation, and
+the configuration files for all clients can be identical.</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. 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 summarized below and
-detailed in the briefings, papers and reports at <a href=
-"http://www.ntp.org">www.ntp.org</a>.</p>
+distribution. Directions for doing that are on the <a href=
+"build.htm">Building and Installing the Distribution</a> page.</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>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 their messages.
+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 exchanged and stored using
-secure procedures 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.htm">
-ntpq</a></tt> and <tt><a href="ntpdc.htm">ntpdc</a></tt> utility
-programs.
+called <tt>ntp.keys</tt>, which must be distributed and stored
+using secure procedures 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.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
specified in the <tt>keys</tt> configuration command and installs
in RFC-1305 and in addition the Autokey protocol, which is based on
public key cryptography. The Autokey Version 2 protocol verifies
packet integrity using MD5 message digests and verifies the source
-with digital signatures and any of several digest/signature schemes
-available in the OpenSSL software library. 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.htm">Building and
-Installing the Distribution</a> page. Once installed, the configure
-and build process automatically detects the library and links the
-interface routines required.</p>
+with digital signatures and any of several digest/signature
+schemes. Optional identification schemes based on cryptographic
+challenge/response algorithms are also available. Using all of
+these schemes provides strong security against replay with or
+without modification, spoofing, masquerade and most forms of
+clogging attacks.</p>
+
+<p>The cryptographic means necessary for all Autokey operations
+provided by the OpenSSL software library. 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.htm">Building and Installing the Distribution</a> page. Once
+installed, the configure and build process automatically detects
+the library and links the interface routines required.</p>
<p>The Autokey protocol has several modes of operation
-corresponding to the various NTP modes supported. Digital
-signatures with any of several message digest and signature
-encryption schemes are used in all modes to verify that the server
-is authentic and not an intruder. 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=
+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/~mills/autokey.htm">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. This
-includes a host key file, certificate file and optional sign file
-and leapsecond file. The digest/signature scheme is specified in
-the X.509 certificate configured during installation 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. The schemes currently
-available are described in the <a href="genkeys.htm"><tt>
-ntp-genkeys</tt></a> page.</p>
+includes a required host key file, required certificate file and
+optional sign key file, leapsecond file and identification 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.
+The schemes currently available are described in the <a href=
+"genkeys.htm"><tt>ntp-keygen</tt></a> page.</p>
<p>The digest/signature scheme and certificate are provided to
dependent clients in the Autokey protocol. Different client or peer
explanation of the subprotocols, called dances, is beyond the scope
of this page. Detailed information and briefings can be found via
the NTP project page at <a href="html://www.ntp.org">
-www.ntp.org</a>. Briefly, the all dances start out with a client
-request for the server name and status word. The next step is to
-request the server host certificate and the third to request the
-certificate of the server that signed the first certificate. If the
-client verifies the server certificate signature, the server is
-pronounced authentic. The fourth step is to present a certificate
-to the server acting as certificate authority and request that it
-be signed and returned. This allows a client acting as a server for
-the next higher stratum to prove authenticity.</p>
+www.ntp.org</a>. Briefly, the dances start when a client requests
+the server name and status word. Next, the client requests the
+server host certificate used to verify the signature of subsequent
+data supplied by the server.</p>
+
+<p>Next comes the identification procedure which confirms the
+server group membership. There are four schemes to prove
+identification: one using private certificates (PC), a second using
+trusted certificates (TC), a third using a modified Schnorr
+algorithm (IFF aka Identify Friend or Foe) and the fourth using a
+modified Guillou-Quisquater (GQ) algorithm. The particular scheme
+and required parameters and certificates are selected during
+operation of the <tt>ntp-keygen</tt> utility.</p>
+
+<p>The PC scheme uses a private certificate as group key. The
+certificate is distributed to all other group members by secret
+means and never revealed outside the group. The TC scheme involves
+a conventional certificate trail and a sequence of certificates,
+each signed by an issuer one stratum level lower than the client
+and terminating on a self signed trusted certificate, as described
+in RFC-2510.</p>
+
+<p>The two remaining schemes involve a cryptographically strong
+challenge-response exchange. Both the IFF and GQ schemes start when
+the client sends a nonce to the server, which then rolls its own
+nonce, performs a mathematical operation and sends the results
+along with a message digest to the client. The client performs a
+second mathematical operation to produce a digest that must match
+the one included in the message.</p>
<p>The next steps retrieve the cryptographic values needed in the
particular dance, including the cookie, autokey values and
-leapsecond table. As one of these steps the client presents the
-server with its certificate and asks that it be signed using the
-server private key. The server response is saved for future
-dependent clients as proof that the client itself is a legitimate
-member of the community and not an intruder attempting to
-impersonate a legitimate member.</p>
+leapsecond table. As a required step in the TC identification
+scheme, the client presents the server with its certificate and
+asks that it be signed using the server private key. The server
+response is saved for future dependent clients to walk the
+certificate trail.</p>
+
+<h4>Interoperability</h4>
+
+<p>A specific combination of authentication scheme (none, symmetric
+key, public key) and identification scheme (PC, TC, IFF, GQ) is
+called a cryptotype, although not all combinations are legal. 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 several ways while keeping in mind the
+principles explained 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 given as argument; if the <tt>autokey</tt> subcommand is
+present, the association is authenticated using Autokey.</p>
+
+<p>When multiple identification schemes are supported in the
+Autokey protocol, the first message exchange determines which one
+is used. The client request message contains bits corresponding to
+which schemes it has available. The server response message
+contains bits corresponding to which schemes it has available. Both
+server and client match the received bits with their own and select
+the common scheme judged most secure. For this purpose the order
+from most secure to least is GC, IFF, TC. Note that PC does not
+interoperate with any of the rest, since they require the server
+certificate which a PC server will not reveal.</p>
+
+<p>Following the principle that time is a public value, a server
+responds to any client packet that matches its cryptotype
+capabilities. Thus, a server receiving an unauthenticated packet
+will respond with an unauthenticated packet, while the same server
+receiving a packet of a cryptotype it supports will respond with
+packets of that cryptotype. However, unconfigured broadcast or
+manycast client associations or symmetric passive associations will
+not be mobilized unless the server supports a cryptotype compatible
+with the first packet received. By default, unauthenticated
+associations will not be mobilized unless overridden in a decidedly
+dangerous way.</p>
+
+<p>Some examples may help to reduce confusion. Client Alice has no
+specific cryptotype selected. Server Bob has both a symmetric key
+file and minimal Autokey files. Alice's unauthenticated messages
+arrive at Bob, who replies with unauthenticated messages. Cathy has
+a copy of Bob's symmetric key file and has selected key ID 4 in
+messages to Bob. Bob verifies the message with his key ID 4. If
+it's the same key and the message is verified, Bob sends Cathy a
+reply authenticated with that key. If verification fails, Bob sends
+Cathy a thing called a crypto-NAK, which tells her something broke.
+She can see the evidence using the <tt>ntpq</tt> program.</p>
+
+<p>Denise has rolled her own host key and certificate. She also
+uses one of the identification schemes as Bob. She sends the first
+Autokey message to Bob and they both dance the protocol
+authentication and identification steps. If all comes out okay,
+Denise and Bob continue as described above and in the Internet
+Draft cited earlier.</p>
+
+<p>It should be clear from the above that Bob can support all the
+girls at the same time, as long as he has compatible authentication
+and identification credentials. Now, Bob can act just like the
+girls in his own choice of servers; he can run multiple configured
+associations with multiple different servers (or the same server,
+although that might not be useful). But, wise security policy might
+preclude some cryptotype combinations; for instance, running an
+identification scheme with one server and no authentication with
+another might not be wise.</p>
<h4>Key Management</h4>
<p>The cryptographic values used by the Autokey protocol are
incorporated as a set of files generated by the <a href=
-"genkeys.htm"><tt>ntp-genkeys</tt></a> utility program, including
-the required symmetric keys, host key pair and public certificate
-files and optional sign key and leapseconds files. The symmetric
-keys file is necessary for the <tt>ntpq</tt> and <tt>ntpdc</tt>
-utility programs. The remaining files are necessary for the Autokey
-protocol. The files incorporate cryptographic values generated by
-the OpenSSL library algorithms and are in printable PEM-encoded
-ASCII format. Further information about these files and how they
-are generated and installed is on the <tt>ntp-genkeys</tt>
-page.</p>
-
-<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 overridden by the <tt>keysdir</tt>
-configuration command. Ordinarily, the host keys are permitted root
-read-only; the others are public values permitted world readable.
-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 directory. This is different than the
-original Autokey version 1 support, which required the private key
-to be installed separately for each client.</p>
-
-<p>The recommended practice is to keep the file name extensions
-when installing a file and to install a soft link from the default
-name specified in the <tt>ntp-genkeys</tt> page to the actual file.
-This allows new file generations to be activated simply by changing
-the link. However, <tt>ntpd</tt> parses the link name when present
-to extract the filestamp and sends it along with the public key and
-host name when requested. This allows clients to verify that the
-file and generation time are always current. The actual location of
-each file can be overridden by the <tt>crypto</tt> configuration
-command, but this is not recommended.</p>
-
-<p>All cryptographic keys and related values should be regenerated
-on a periodic and automatic 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 in monitoring data. While a host key pair and
-certificate must be generated by every server and peer, the
-certificates do not need to be explicitly copied to all machines in
-the same security compartment, since they can be obtained
-automatically using the Autokey protocol.</p>
-
-<p>Servers and peers can make a new generation in the following
-way. All machines have loaded the current keys and certificate at
-startup. At designated intervals, each machine generates a new
-public/private key pair and certificate and makes links from the
-default file names to the new file names. The <tt>ntpd</tt> daemon
-is restarted after each new generation and load the new files. The
-Autokey protocol is designed so that 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 as
-before. If for some reason this does not happen, the <tt>ntpd</tt>
-daemon refreshes all crhyptographic values at intervals of about
-one day, so that the protocol is restarted for all client
-associations and results in the same actions.</p>
+"genkeys.htm"><tt>ntp-keygen</tt></a> utility program, including
+symmetric keys, required host key and public certificate files and
+optional sign key, identification parameters and leapseconds files.
+The symmetric keys file is necessary for the <tt>ntpq</tt> and <tt>
+ntpdc</tt> utility programs. The remaining files are necessary only
+for the Autokey protocol. The files incorporate cryptographic
+values generated by the OpenSSL library algorithms and are in
+printable PEM-encoded ASCII format. Further information about these
+files and how they are generated and installed is on the <tt>
+ntp-keygen</tt> page.</p>
<h4>Random Seed File</h4>
<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-genkeys</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> command. If
-not specified in this way, or when starting the <tt>
-ntp-genkeys</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 <tt>
-ntp-genkeys</tt> program exits with a suitable error message.</p>
+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> 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 <tt>ntp-keygen</tt> program exits
+with a suitable error message.</p>
<p>The daemon will occasionally add additional entropy and write to
the file when generating new keys and certificates, for example, so
-the file must be writable by root. If the <tt>ntp-genkeys</tt>
+the file must be writable by root. If the <tt>ntp-keygen</tt>
program is run by other than root, or if the Unix <tt>su</tt>
command is used to assume root, the home directory assumed by the
OpenSSL library might not be root. Probably the safest way to
generate keys is to log in as root, change to the keys directory
-and run the <tt>ntp-genkeys</tt> program from there</p>
+and run the <tt>ntp-keygen</tt> program from there</p>
<h4>Authentication Commands</h4>
<dd>
<dl>
-<dt><tt>certificate <i>file</i></tt></dt>
+<dt><tt>cert <i>file</i></tt></dt>
-<dd>Specifies the location of the public certificate file, which by
-default is linked from <tt>ntpkey_cert_<i>hostname</i></tt> in the
+<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.</dd>
+
+<dt><tt>gq <i>file</i></tt></dt>
+
+<dd>Specifies the location of the optional GQ keys file. This
+overrides the link <tt>ntpkey_gq_<i>hostname</i></tt> in the keys
+directory.</dd>
+
+<dt><tt>gqpar <i>file</i></tt></dt>
+
+<dd>Specifies the location of the optional GQ parameters file. This
+overrides the link <tt>ntpkey_gqpar_<i>hostname</i></tt> in the
keys directory.</dd>
-<dt><tt>leap <i>file</i></tt></dt>
+<dt><tt>host <i>file</i></tt></dt>
-<dd>Specifies the location of the optional leapsecond table file,
-which by default is linked from <tt>ntpkey_leap</tt> in the keys
+<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.</dd>
+<dt><tt>iff <i>file</i></tt></dt>
+
+<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.</dd>
+
+<dt><tt>leap <i>file</i></tt></dt>
+
+<dd>Specifies the location of the optional leapsecond file. This
+overrides the link <tt>ntpkey_leap</tt> in the keys directory.</dd>
+
<dt><tt>randfile <i>file</i></tt></dt>
<dd>Specifies the location of the random seed file used by the
OpenSSL library. The defaults are described in the main text
above.</dd>
-<dt><tt>rsakey <i>file</i></tt></dt>
-
-<dd>Specifies the location of the public/private key file, which by
-default is linked from <tt>ntpkey_key_<i>hostname</i></tt> in the
-keys directory.</dd>
-
-<dt><tt>signkey <i>file</i></tt></dt>
+<dt><tt>sign <i>file</i></tt></dt>
-<dd>Specifies the location of the optional sign key file used to
-construct digital signatures, which by default is linked from <tt>
-ntpkey_sign_<i>hostname</i></tt> in the keys directory. If this
-file is not present, the <tt>rsakey</tt> file is used.</dd>
+<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.</dd>
</dl>
</dd>
<dt><tt>keys <i>keyfile</i></tt></dt>
-<dd>Specifies the location of the MD5 symmetric key file containing
-the keys and key identifiers used by <tt>ntpd</tt>, <tt>ntpq</tt>
-and <tt>ntpdc</tt> when operating with symmetric key
-cryptography.</dd>
+<dd>Specifies the location of the MD5 key file containing the keys
+and key identifiers used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>
+ntpdc</tt> when operating with symmetric key cryptography.</dd>
<dt><tt>keysdir <i>path</i></tt></dt>
-<dd>This command requires the OpenSSL library. It specifies the
-default directory path for the cryptographic files generated by the
-<tt>ntp-genkeys</tt> program. The default is <tt>
-/usr/local/etc/</tt>.</dd>
+<dd>This command specifies the default directory path for
+cryptographic keys, parameters and certificates.. The default is
+<tt>/usr/local/etc/</tt>.</dd>
<dt><tt>requestkey <i>key</i></tt></dt>
<dd>The certificate is invalid or signed with the wrong key.</dd>
-<dt>110 (certificate expired)</dt>
+<dt>110 (certificate not verified)</dt>
-<dd>The certificate is not yet valid or has expired.</dd>
+<dd>The certificate is not yet valid or has expired or the
+signature could not be verified.</dd>
<dt>111 (bad or missing cookie)</dt>
-<dd>The cookie is corrupted or bogus.</dd>
+<dd>The cookie is missing, corrupted or bogus.</dd>
<dt>112 (bad or missing leapseconds table)</dt>
-<dd>The leapseconds file is corrupted or bogus.</dd>
+<dd>The leapseconds table is missing, corrupted or bogus.</dd>
<dt>113 (bad or missing certificate)</dt>
-<dd>The server does not have the requested certificate.</dd>
+<dd>The certificate is missing, corrupted or bogus.</dd>
+
+<dt>114 (bad or missing identification)</dt>
+
+<dd>The identification key is missing, corrupt or bogus.</dd>
</dl>
<h4>Files</h4>
-<p>See the <a href="genkeys.htm"><tt>ntp-genkeys</tt></a> page.</p>
+<p>See the <a href="genkeys.htm"><tt>ntp-keygen</tt></a> page.</p>
<hr>
<a href="index.htm"><img align="left" src="pic/home.gif" alt=
-<html><head><title>
-Configuration Options
-</title></head><body><h3>
-Configuration Options
-</h3>
-
-<img align=left src=pic/pogo3a.gif><a
-href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>,
-Walt Kelly</a>
-
-<p>Gnu autoconfigure tools are in the backpack.
-<br clear=left><hr>
-
-<H4>Basic Configuration Options - the <TT>configure</TT> utility</H4>
-
-The following options are for compiling and installing a working version
-of the NTP distribution. In most cases, the build process is completely
-automatic. In some cases where memory space is at a premium, or the
-binaries are to be installed in a different place, it is possible to
-tailor the configuration to remove such features as reference clock
-driver support, debugging support, and so forth.
-
-<P>Configuration options are specified as arguments to the
-<TT>configure</TT> script. Following is a summary of the current
-options, as of the 4.0.99m version:
-
-<P>Usage: <TT>configure [options] [host]</TT>
-<BR>Options: <TT>[defaults in brackets after descriptions]</TT>
-Configuration:
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<html>
+<head>
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Configuration Options</title>
+</head>
+<body>
+<h3>Configuration Options</h3>
+
+<img align="left" src="pic/pogo3a.gif"><a href=
+"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>,
+Walt Kelly</a>
+
+<p>Gnu autoconfigure tools are in the backpack.<br clear="left">
+</p>
+
+<hr>
+<h4>Basic Configuration Options - the <tt>configure</tt>
+utility</h4>
+
+The following options are for compiling and installing a working
+version of the NTP distribution. In most cases, the build process
+is completely automatic. In some cases where memory space is at a
+premium, or the binaries are to be installed in a different place,
+it is possible to tailor the configuration to remove such features
+as reference clock driver support, debugging support, and so forth.
+
+
+<p>Configuration options are specified as arguments to the <tt>
+configure</tt> script. Following is a summary of the current
+options, as of the 4.0.99m version:</p>
+
+<p>Usage: <tt>configure [options] [host]</tt><br>
+Options: <tt>[defaults in brackets after descriptions]</tt>
+Configuration:</p>
+
+<pre>
--cache-file=FILE cache test results in FILE
--help print this message
--no-create do not create output files
--quiet, --silent do not print `checking...' messages
--version print the version of autoconf that created
configure
-</PRE>
+</pre>
-Directory and file names:
+Directory and file names:
-<PRE>
+<pre>
--prefix=PREFIX install architecture-independent files in PREFIX
[/usr/local]
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
names
--program-transform-name=PROGRAM run sed PROGRAM on installed program
names
-</PRE>
+</pre>
-Host type:
+Host type:
-<PRE>
+<pre>
--build=BUILD configure for building on BUILD [BUILD=HOST]
--host=HOST configure for HOST [guessed]
--target=TARGET configure for TARGET [TARGET=HOST]
-</PRE>
+</pre>
-Optional packages:
+Optional packages:
-<PRE>
+<pre>
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
crypto=autokey Use autokey cryptography
crypto=rsaref Use the RSAREF library
electricfence Compile with ElectricFence malloc debugger
-</PRE>
+</pre>
-Optional features:
+Optional features:
-<PRE>
+<pre>
--disable-FEATURE do not include FEATURE (same as
--enable-FEATURE=no)
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
tick=VALUE Force a value for 'tick'
tickadj=VALUE Force a value for 'tickadj'
udp-wildcard Use UDP wildcard delivery
-</PRE>
+</pre>
Radio clocks (these are ordinarily enabled, if supported by the
-machine and operating system):
+machine and operating system):
-<PRE>
+<pre>
all-clocks Include drivers for all suitable non-PARSE
clocks [enable]
ACTS NIST dialup clock
ULINK Ultralink WWVB receiver
USNO US Naval Observatory dialup clock
WWV WWV audio receiver
-</PRE>
+</pre>
-PARSE Clocks:
+PARSE Clocks:
-<PRE>
+<pre>
parse-clocks Include drivers for all suitable PARSE clocks
[enable]
COMPUTIME Diem Computime Radio Clock
TRIMTSIP Trimble GPS/TSIP Protocol
VARITEXT VARITEXT clock
WHARTON Wharton 400A Series clock
-</PRE>
+</pre>
+
+<hr>
+<a href="index.htm"><img align="left" src="pic/home.gif"></a>
+<address><a href="mailto:mills@udel.edu">David L. Mills
+<mills@udel.edu></a></address>
+</body>
+</html>
-<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
-href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a>
-</address></a></body></html>
<p>The various modes are determined by the command keyword and the
type of the required IP address. Addresses are classed by type as
-(s) a remote server or peer (IP class A, B and C), (b) the
-broadcast address of a local interface, (m) a multicast address (IP
-class D), or (r) a reference clock address (127.127.x.x). Note that
-only those options applicable to each command are listed below. Use
-of options not listed may not be caught as an error, but may result
-in some weird and even destructive behavior.</p>
+(s) a remote server or peer (IPv4 class A, B and C), (b) the
+broadcast address of a local interface, (m) a multicast address
+(IPv4 class D), or (r) a reference clock address (127.127.x.x).
+Note that only those options applicable to each command are listed
+below. Use of options not listed may not be caught as an error, but
+may result in some weird and even destructive behavior.</p>
+
+<p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is
+detected, support for the IPv6 address family is generated in
+addition to the default support of the IPv4 address family. In a
+few cases, including the <tt>reslist</tt> billboard generated by
+<tt>ntpdc</tt>, IPv6 addresses are automatically generated. IPv6
+addresses can be identified by the presence of colons ":" in the
+address field. IPv6 addresses can be used almost everywhere where
+IPv4 addresses can be used, with the exception of reference clock
+addresses, which are always IPv4. DNS names will resolve with
+preference to IPv4 or IPv6 addresses depending on the host system's
+resolver library. See IPv6 references for the equivalent classes
+for that address family.</p>
<dl>
<dt><tt>server <i>address</i> [key <i>key</i> | autokey] [burst]
<dt><tt>burst</tt></dt>
<dd>When the server is reachable, send a burst of eight packets
-instead of the usual one. The packet spacing is about 2 s. This is
-designed to improve timekeeping quality with the <tt>server</tt>
-command and <tt>s</tt> addresses.</dd>
+instead of the usual one. The packet spacing is normally 2 s;
+however, the spacing between the first and second packets can be
+changed with the <tt>calldelay</tt> command to allow additional
+time for a modem or ISDN call to complete. This is designed to
+improve timekeeping quality with the <tt>server</tt> command and
+<tt>s</tt> addresses.</dd>
<dt><tt>iburst</tt></dt>
<dd>When the server is unreachable, send a burst of eight packets
-instead of the usual one. As long as the server is unreachable, the
-packet spacing is about 16s to allow a modem call to complete. Once
-the server is reachable, the packet spacing is about 2s. This is
-designed to speed the initial synchronization acquisition with the
-<tt>server</tt> command and <tt>s</tt> addresses and when <tt>
-ntpd</tt> is started with the <tt>-q</tt> option.</dd>
+instead of the usual one. The packet spacing is normally 2 s;
+however, the spacing between the first two packets can be changed
+with the <tt>calldelay</tt> command to allow additional time for a
+modem or ISDN call to complete. This is designed to speed the
+initial synchronization acquisition with the <tt>server</tt>
+command and <tt>s</tt> addresses and when <tt>ntpd</tt> is started
+with the <tt>-q</tt> option.</dd>
<dt><tt>key</tt> <i><tt>key</tt></i></dt>
<pre>
***********************************************************************
* *
-* Copyright (c) David L. Mills 1992-2001 *
+* Copyright (c) David L. Mills 1992-2002 *
* *
* Permission to use, copy, modify, and distribute this software and *
* its documentation for any purpose and without fee is hereby *
<li><A HREF="mailto: michael.barone@lmco.com">Michael Barone <michael,barone@lmco.com></a> GPSVME fixes</li>
+<li><a href="mailto: Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a>IPv6 support</li>
+
<li><A HREF="mailto: karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option</li>
<li><A HREF="mailto: greg.brackley@bigfoot.com">Greg Brackley <greg.brackley@bigfoot.com></a> Major rework of WINNT port. Clean up recvbuf and iosignal code into separate modules.</li>
<li><A HREF="mailto: dennis@mrbill.canet.ca">Dennis Ferguson
<dennis@mrbill.canet.ca></a> foundation code for NTP Version 2 as specified in RFC-1119</li>
+<li><A HREF="mailto: jhay@icomtek.csir.co.za">John Hay <jhay@@icomtek.csir.co.za></a> IPv6 support and testing</li>
+
<li><A HREF="mailto: glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver</li>
<li><A HREF="mailto: iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</li>
noise spikes, the second correction will not be done until after
the stepout threshold. When the frequency error is very large, it
may take a number of cycles like this until converging on the
-nominal frequency correction. After this, the correction is written
-to the <tt>ntp.drift</tt> file, which is read upon subsequent
-restarts, so the herky-jerky cycles should not recur.</p>
+nominal frequency correction. After this, and at one-hour
+intervals, the correction is written to the <tt>ntp.drift</tt>
+file, which is read upon subsequent restarts, so the herky-jerky
+cycles should not recur.</p>
<h4>Verifying Correct Operation</h4>
Note that in NTP Version 4 what used to be the <tt>dispersion</tt>
column has been replaced by the <tt>jitter</tt> column.</p>
+<p>As per the NTP specification RFC-1305, when the <tt>stratum</tt>
+is between 0 and 15 for a NTP server, the <tt>refid</tt> field
+shows the server DNS name or, if not found, the IP address in
+dotted-quad. When the <tt>stratum</tt> is any value for a reference
+clock, this field shows the identification string assigned to the
+clock. However, until the client has synchronized to a server, or
+when the <tt>stratum</tt> for a NTP server is 0 (appears as 16 in
+the billboards), the status cannot be determined. As a help in
+debugging, the <tt>refid</tt> field is set as follows.</p>
+
+<p>Peer Variables</p>
+
+<dl>
+<dt><tt>ACST</tt></dt>
+
+<dd>The association belongs to a anycast server.</dd>
+
+<dt><tt>AUTH</tt></dt>
+
+<dd>Server authentication failed. Please wait while the association
+is restarted.</dd>
+
+<dt><tt>AUTO</tt></dt>
+
+<dd>Autokey sequence failed. Please wait while the association is
+restarted.</dd>
+
+<dt><tt>BCST</tt></dt>
+
+<dd>The association belongs to a broadcast server.</dd>
+
+<dt><tt>CRYP</tt></dt>
+
+<dd>Cryptographic authentication or identification failed. The
+details should be in the system log file or the <tt>
+cryptostats</tt> statistics file, if configured. No further
+messages will be sent to the server.</dd>
+
+<dt><tt>DENY</tt></dt>
+
+<dd>Access denied by remote server. No further messages will be
+sent to the server.</dd>
+
+<dt><tt>DROP</tt></dt>
+
+<dd>Lost peer in symmetric mode. Please wait while the association
+is restarted.</dd>
+
+<dt><tt>RSTR</tt></dt>
+
+<dd>Access denied due to local policy. No further messages will be
+sent to the server.</dd>
+
+<dt><tt>INIT</tt></dt>
+
+<dd>The association has not yet synchronized for the first
+time.</dd>
+
+<dt><tt>MCST</tt></dt>
+
+<dd>The association belongs to a manycast server.</dd>
+
+<dt><tt>NKEY</tt></dt>
+
+<dd>No key found. Either the key was never installed or is not
+trusted.</dd>
+
+<dt><tt>RATE</tt></dt>
+
+<dd>Rate exceeded. The server has temporarily denied access because
+the client exceeded the rate threshold.</dd>
+
+<dt><tt>RMOT</tt></dt>
+
+<dd>Somebody is tinkering with the association from a remote host
+running <tt>ntpdc</tt>. Not to worry unless some rascal has stolen
+your keys.</dd>
+
+<dt><tt>STEP</tt></dt>
+
+<dd>A step change in system time has occured, but the association
+has not yet resynchronized.</dd>
+</dl>
+
+<p>System Variables</p>
+
+<dl>
+<dt><tt>INIT</tt></dt>
+
+<dd>The system clock has not yet synchronized for the first
+time.</dd>
+
+<dt><tt>STEP</tt></dt>
+
+<dd>A step change in system time has occured, but the system clock
+has not yet resynchronized.</dd>
+</dl>
+
<p>The tattletale symbol at the left margin displays the
synchronization status of each peer. The currently selected peer is
marked <tt>*</tt>, while additional peers designated acceptable for
filtdelay= 10.45 10.50 10.63 10.40 10.48 10.43 10.49 11.26,
filtoffset= -1.18 -1.26 -1.26 -1.35 -1.35 -1.42 -1.54 -1.81,
filtdisp= 0.51 1.47 2.46 3.45 4.40 5.34 6.33 7.28,
-hostname="miro.time.saic.com", publickey=3171359012, pcookie=0x6629adb2,
-hcookie=0x61f99cdb, initsequence=61, initkey=0x287b649c,
+hostname="miro.time.saic.com", signature=md5WithRSAEncryption, flags=0x83f01, initsequence=61, initkey=0x287b649c,
timestamp=3172053041
</pre>
<p>A detailed explanation of the fields in this billboard are
beyond the scope of this discussion; however, most variables
defined in the NTP Version 3 specification RFC-1305 are available
-along with others defined for NTP Version 4. This particular
-example was chosen to illustrate probably the most complex
-configuration involving symmetric modes and public-key
+along with others defined for NTPv4 on the <tt>ntpq</tt> page. This
+particular example was chosen to illustrate probably the most
+complex configuration involving symmetric modes and public-key
cryptography. As the result of debugging experience, the names and
-values of these variables may change from time to time. An
-explanation of the current set is on the <tt>ntpq</tt> page.</p>
+values of these variables may change from time to time.</p>
<p>A useful indicator of miscellaneous problems is the <tt>
flash</tt> value, which reveals the state of the various sanity
-tests on incoming packets. There are currently eleven bits, one for
+tests on incoming packets. There are currently 12 bits, one for
each test, numbered from the right, which is for test 1. If the
test fails, the corresponding bit is set to one and zero otherwise.
If any bit is set following each processing step, the packet is
reftime=bd11b220.ac89f40a Sat, Jul 8 2000 13:58:56.673, poll=6,
clock=bd11b225.ee201472 Sat, Jul 8 2000 13:59:01.930, state=4,
phase=0.179, frequency=44.298, jitter=0.022, stability=0.001,
-hostname="barnstable.udel.edu", publickey=3171372095, params=3171372095,
-refresh=3172016539
+hostname="barnstable.udel.edu", signature=md5WithRSAEncryption,
+flags=0x80011, hostkey=3171372095, refresh=3172016539
+cert="grundoon.udel.edu grundoon.udel.edu 0x3 3233600829"
+cert="whimsy.udel.edu whimsy.udel.edu 0x5 3233682156"
</pre>
<p>An explanation about most of these variables is in the RFC-1305
as errors due to confused radio clocks upon the epoch of a leap
second.</p>
-<h4>Special Problems</h4>
+<h4>Large Frequency Errors</h4>
<p>The frequency tolerance of computer clock oscillators can vary
widely, which can put a strain on the daemon's ability to
figure out an acceptable way to do this, there are many cases where
<tt>tickadj</tt> is incompatible with a running kernel.</p>
+<h4>Access Controls</h4>
+
<p>Provisions are included in <tt>ntpd</tt> for access controls
which deflect unwanted traffic from selected hosts or networks. The
controls described on the <a href="accopt.htm">Access Control
Options</a> include detailed packet filter operations based on
source address and address mask. Normally, filtered packets are
dropped without notice other than to increment tally counters.
-However, the server can configure to generate what is called a
-kiss-of-death (KOD) packet and send to the client. In case of
-outright access denied, the KOD is the response to the first client
-packet. In this case the client association is permanently disabled
-and the access denied bit (test 4) is set in the flash peer
-variable mentioned above and a message is sent to the system
+However, the server can be configured to send a "kiss-of-death"
+(KOD) packet to the client either when explicitly configured or
+when cryptographic authentication fails for some reason. The client
+association is permanently disabled, the access denied bit (TEST4)
+is set in the flash variable and a message is sent to the system
log.</p>
<p>The access control provisions include a limit on the packet rate
"accopt.htm">Access Control Options</a> page for further
informatin.</p>
+<h4>Large Delay Variations</h4>
+
<p>In some reported scenarios an access line may show low to
moderate network delays during some period of the day and moderate
to high delays during other periods. Often the delay on one
especially if the condition persists for greater than the stepout
threshold.</p>
-<p>The recommended approach in such scenarios is first to calibrate
-the local clock frequency error by running <tt>ntpd</tt> in
-continuous mode during the quiet interval and let it write the
+<p>Specific provisions have been built into <tt>ntpd</tt> to cope
+with these problems. The scheme is called "huff-'n-puff and is
+described on the <a href="miscopt.htm">Miscellaneous Options</a>
+page. An alternative approach in such scenarios is first to
+calibrate the local clock frequency error by running <tt>ntpd</tt>
+in continuous mode during the quiet interval and let it write the
frequency to the <tt>ntp.drift</tt> file. Then, run <tt>ntpd
-q</tt> from a cron job each day at some time in the quiet
interval. In systems with the nanokernel or microkernel performance
<p>Reliable source authentication requires the use of symmetric key
or public key cryptography, as described on the <a href=
"authopt.htm">Authentication Options</a> page. In symmetric key
-cryptography servers and clients share secret keys contained in a
-key file In public key cryptography, which requires the OpenSSL
-software library, the server has a private key, never shared, and a
-public key with unrestricted distribution. The cryptographic media
-required are produced by the <a href="genkeys.htm">
-,<tt>ntp-genkeys</tt></a> program.</p>
+cryptography servers and clients share session keys contained in a
+secret key file In public key cryptography, which requires the
+OpenSSL software library, the server has a private key, never
+shared, and a public key with unrestricted distribution. The
+cryptographic media required are produced by the <a href=
+"ntp-genkeys.htm"><tt>ntp-keygen</tt></a> program.</p>
<p>Problems with symmetric key authentication are usually due to
mismatched keys or improper use of the <tt>trustedkey</tt> command.
disabled is very dangerous, since an intruder can easily strike up
an association and inject false time values.</p>
-<p>Public key cryptography is supported in NTPv4 uses the Autokey
-protocol, which is described in an Internet Draft. Development of
-this protocol is ongoing and likely to evolve in various ways.
-However, Autokey version 2, which is the latest and current
-version, is a maturing product. Further details of the protocol are
-on the <a href="authopt.htm">Authentication Options</a> page.
-Common problems with configuration and key generation are
-mismatched key files, broken links and missing or broken random
-seed file.</p>
+<p>Public key cryptography is supported in NTPv4 using the Autokey
+protocol, which is described in briefings on the NTP Project page
+linked from www.ntp.org. Development of this protocol is nearing
+maturity and the <tt>ntpd</tt> implementation is basically
+complete. Autokey version 2, which is the latest and current
+version, includes provisions to walk certificate trails, operate as
+certificate authorities and verify identity using
+challenge/response identification schemes. Further details of the
+protocol are on the <a href="authopt.htm">Authentication
+Options</a> page. Common problems with configuration and key
+generation are mismatched key files, broken links and missing or
+broken random seed file.</p>
<p>As in the symmetric key cryptography case, the trace facility is
-a good way to verify correct operation. The daemon requires a
-random seed bile, correct public/private key file and a valid
-certificate file; otherwise it exits immediately with a message to
-the system log. As each file is loaded a trace message appears with
-its filestamp. There are a number of checks to insure that only
-consistent data are used and that the certificate is valid. When
-the protocol is in operation a number of checks are done to verify
-the server has the expected credentials and its filestamps and
-timestamps are consistent. Errors found are reported using NTP
-control and monitoring protocol traps with extended trap codes
-shown in the Authentication Options page.</p>
+a good way to verify correct operation. A statistics file <tt>
+cryptostats</tt> records protocol transactions and error messages.
+The daemon requires a random seed file, public/private key file and
+a valid certificate file; otherwise it exits immediately with a
+message to the system log. As each file is loaded a trace message
+appears with its filestamp. There are a number of checks to insure
+that only consistent data are used and that the certificate is
+valid. When the protocol is in operation a number of checks are
+done to verify the server has the expected credentials and its
+filestamps and timestamps are consistent. Errors found are reported
+using NTP control and monitoring protocol traps with extended trap
+codes shown in the Authentication Options page.</p>
<p>To assist debugging every NTP extension field is displayed in
the trace along with the Autokey operation code. Every extension
majority of truechimers among the server population.</li>
<li>If all else fails, see the FAQ and/or the discussion and
-briefings at <a href="http://www.eecis.udel.edu/~mills/ntp.htm">
-Network Time Synchronization Project.</a></li>
+briefings at the NTP Project page.</li>
</ol>
<hr>
Both receivers have the same output string. For more information about the\r
NeoClock4X receiver please visit <a\r
href="http://www.linum.com/redir/jump/id=neoclock4x&action=redir">http://www.linum.com/redir/jump/id=neoclock4x&action=redir</a>.\r
- \r
+ á
<hr width="100%" size="2"> \r
<h2>Fudge Factors</h2>\r
\r
<dl>\r
<dt> <b><a href="clockopt.htm">time1 time</a></b></dt>\r
<dd> Specifies the time offset calibration factor with the default value\r
- off 0.16958333 seconds. This offset is used to correct serial line and\r
+ off 0.16958333 seconds. This offset is usedá to correct serial line and
operating system delays incurred in capturing time stamps. If you want to\r
fudge the time1 offset <b>ALWAYS</b> add a value off 0.16958333. This is\r
neccessary to compensate to delay that is caused by transmit the timestamp\r
<html>
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
-<title>ntp-genkeys - generate public and private keys</title>
+<title>ntp-keygen - generate public and private keys</title>
</head>
<body>
-<h3><tt>ntp-genkeys</tt> - generate public and private keys</h3>
+<h3><tt>ntp-keygen</tt> - generate public and private keys</h3>
<img align="left" src="pic/alice23.gif" alt="gif"><a href=
"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's
<hr>
<h4>Synopsis</h4>
-<tt>ntp-genkeys</tt>
+<tt>ntp-keygen</tt>
<h4>Description</h4>
-<p>This program generates random keys used by either or both the
-NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey)
-cryptographic authentication schemes. By default the program
-generates a symmetric key file containing 16 random keys for the
-MD5 message digest algorithm. In addition, if the OpenSSL software
-library has been installed, the program generates cryptographic key
-files used by the Autokey protocol. These files contain the
-public/private key pair, certificate request, certificate and
-Diffie-Hellman parameters. While all available files are generated,
-the Autokey Version 2 protocol requires only the public/private key
-pair and certificate files. 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>This program generates cryptographic data files used by the
+NTPv4 authentication and identification schemes. It generates key
+files for the MD5 keyed message digest algorithm, which uses
+symmetric key cryptography. In addition, if the OpenSSL software
+library has been installed, the program generates key, certificate
+and parameter files for the Autokey protocol, which uses public key
+cryptography. These files are used for cookie encryption, digital
+signature and challenge/response identification algorithms, as well
+as for Internet standard security infrastructure applications.
+While a large number of authentication and identification scheme
+combinations are supported, the work of generating and maintaining
+the files is minimal, since the key generation and update process
+is largely automated.</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 the
+name 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 <tt>/usr/local/etc</tt>,
+which is normally in a shared filesystem in NFS-mounted networks.
+The default can be overridden by the <tt>keysdir</tt> configuration
+command. The actual location of each file can be overridden by the
+<tt>crypto</tt> configuration command, but this is not recommended.
+Normally, the files for each machine are generated by that machine
+and used only by that machine, although exceptions exist as
+documented on the <tt>ntp-keygen</tt> page. However, the files for
+a machine can be put in a more private place, such as <tt>/etc</tt>
+if necessary.</p>
+
+<p>Nornally the host key, sign key and identification parameters
+are permitted root read-only; the others are public values
+permitted world readable. 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 directory. This
+is different than the original Autokey Version 1 support, which
+required the private key to be installed separately for each
+client.</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 in the <tt>ntp-keygen</tt> page to the generated
+files. This allows new file generations to be activated simply by
+changing the link. However, <tt>ntpd</tt> parses the link name when
+present to extract the filestamp and sends it along with the public
+key and host name when requested. This allows clients to verify
+that the file and generation times are always current.</p>
+
+<p>All cryptographic keys and related values should be regenerated
+on a periodic and automatic basis, like once per month. The <tt>
+ntp-keygen</tt> program uses the same timestamp extension for all
+files generated at one time, so each generation is distinct and can
+be readily recognized in monitoring data. While a host key and
+certificate must be generated by every server and peer, the
+certificates do not need to be explicitly copied to all machines in
+the same security compartment, since they can be obtained
+automatically using the Autokey protocol.</p>
<p>As explained in the <a href="authopt.htm">Authentication
Options</a> page, all cryptographically sound key generation
schemes must have means to randomize the entropy seed used to
-initialize the internal random number generator. It is important to
-understand that entropy must be evolved for each file generation
-and agreement calculation, for otherwise the random number sequence
-would be predictable. 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-genkeys</tt> program.
-Directions for doing this are on the Authentication Options
-page.</p>
-
-<p>The safest way to run the <tt>ntp-genkeys</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, which in its present form has no command line options. The
-program generates key files for all message digest and signature
-encryption schemes supported by the OpenSSL library. The key files
-are guaranteed to be unique, so no existing key files will be
-overwritten. Then, using procedures described below, install soft
-links from the default file names used by the daemon to the
-selected file names.</p>
+initialize the internal random number generator. 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>
+
+<h4>Running the program</h4>
+
+<p>The NTP security model requires private cryptographic data used
+by a host to be generated only by that host, although exceptions
+exist as described later. 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 NTP 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.</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
.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>
+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 another client or the server, as these
-values are obtained by the Autokey protocol during operation.</p>
-
-<h4>File Naming Conventions</h4>
-
-<p>All file names include the <i>hostname</i> of the generating
-host together with the NTP <i>filestamp</i> of creation. This
-insures uniqueness for each generation of keys throughout the NTP
-subnet. The hostname is the node name of the generating host as
-returned by the Unix <tt>gethostname()</tt> library routine. The
-filestamp is the NTP seconds in decimal ASCII format. Both the <tt>
-ntp-genkeys</tt> program and the Autokey protocol use these names
-to insure the cryptographic data are consistent and to avoid replay
-attacks. Since the file data are derived from random values seeded
-by the system clock and the file name includes the filestamp, every
-generation produces a different file and different file name.
-However, the NTP daemon looks for the generic file names without
-the filestamp extension on the assumption that soft links are
-installed from the generic name to the particular file generation
-name.</p>
-
-<p>Files containing public-key cryptographic values depend upon
-selection of the message digest and signature encryption scheme.
-There are several schemes available in the OpenSSL software
-library, each identified by a specific string such as the default
-<tt>RSA_MD5</tt>, which stands for the MD5 message digest with RSA
-encryption scheme. The <tt>ntp-genkeys</tt> program can make
-public/private keys, certificates and certificate requests for all
-schemes supported by the OpenSSL library.</p>
-
-<p>In its present form, the <tt>ntp-genkeys</tt> program generates
-files for all digest/signature schemes supported by the OpenSSL
-library and NTP daemon. The recommended practice is to copy all of
-these files to the default directory <tt>/usr/local/etc</tt> and
-install links to select which ones to use according to the default
-file names listed below. At its present level of OpenSSL
-development, the message digest algorithm is specifically bound to
-the signature encryption algorithm, so only a limited number of
-combinations are available. Further details are in the OpenSSL
-documentation.</p>
+keys and certificates of other clients or servers, as these data
+are obtained automatically by the Autokey protocol.</p>
+
+<h4>Examples</h4>
+
+<p>Each cryptographic configuration involves selection of a
+signature scheme and identification scheme, called a cryptotype, as
+explained in the Authentication Options page. The default
+cryptotype uses RSA encryption, MD5 message digest and TC
+identification. First, configure a NTP subnet including a number of
+low-stratum time servers from which all other subnet members derive
+synchronization directly or indirectly. These servers are
+considered trusted and will have trusted certificates. All others
+will automatically and dynamically build authoritative certificate
+trails to these servers.</p>
+
+<p>On each trusted server 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 trusted certificates.
+On all other machines do the same, but leave off the <tt>-T</tt>
+flag to generate keys and nontrusted certificates. When complete,
+start <tt>ntpd</tt> starting from 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>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> without flags to generate
+new certificates using existing keys. The next time the daemon is
+started, it will load the new certificate and restart the protocol.
+Since the keys have not changed, other dependent machines will
+continue as usual until signatures are refreshed and the protocol
+is restarted, which occurs about once per day.</p>
+
+<p>As mentioned elsewhere, the TC identification scheme is
+vulnerable to a middleman attack. If this is of concern, select the
+PC, IFF or GQ schemes. These schemes all require at least one file
+to be securely distributed to all subnet machines. The PC scheme is
+set up as follows. On one subnet machine <i>alice</i> run <tt>
+ntp-keygen -p</tt> to generate the keys and private certificate.
+Then, using secure means, copy the host key file <tt>
+ntpkey_RSAkey_alice</tt> and certificate file <tt>
+ntpkey_RSA-MD5_cert_alice</tt> to all other subnet machines. On
+each machine <i>bob</i> install a soft link from the generic name
+<tt>ntpkey_host_bob</tt> to <tt>ntpkey_RSAkey_alice</tt> and soft
+link <tt>ntpkey_cert_bob</tt> to <tt>
+ntpkey_RSA-MD5_cert_alice</tt>. Note the generic links must match
+the host name, but point to a file generated by another host.
+Finally, proceed as in the TC scheme; however, it is not possible
+to change either the keys or certificates in any machine without
+refreshing the entire subnet.</p>
+
+<p>For the IFF scheme proceed as in the TC scheme, except use the
+<tt>-I</tt> flag instead of <tt>-P</tt>. Then, using secure means,
+copy the IFF parameter file <tt>ntpkeys_IFFpar_alice</tt> to all
+other subnet machines. On each machine <i>bob</i> install a soft
+link from the generic <tt>ntpkey_iffpar_bob</tt> to this file.
+Finally, proceed as in the TC scheme. As the IFF scheme does not
+use certificates, keys and certificates can be regenerated as
+needed.</p>
+
+<p>For the GQ scheme proceed as in the TC scheme, except use the
+<tt>-G</tt> flag instead of <tt>-P</tt>. Then, using secure means,
+copy the GQ parameters file <tt>ntpkeys_GQpar_alice</tt> to all
+other subnet machines. On each machine <i>bob</i> install a soft
+link from the generic <tt>ntpkey_gqpar_bob</tt> to this file. If
+the <tt>ntp-keygen</tt> program is run on <i>bob</i> before these
+steps are complete, then run the program again on <i>bob</i> to
+generate the GQ keys file <tt>ntpkeys_GQkey_bob</tt> and link
+unique to <i>bob</i>. Finally, proceed as in the TC scheme. As the
+GQ scheme generates both the GQ key file and certificate at the
+same time, but leaving the GQ parameter file intact, keys and
+certificates can be regenerated as needed.</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> option and either <tt>RSA</tt> or <tt>DSA</tt>
+argument as needed. The most often need to do this is when a
+DSA-signed certificate is used. If <tt>ntp-keygen</tt> is run again
+without the option, it will generate a new certificate using the
+existing sign key. If it is necessary to use a different
+certificate scheme than the default, run <tt>ntp-keygen</tt> with
+the <tt>-c</tt> option and selected scheme as needed. If <tt>
+ntp-keygen</tt> is run again without the option, it will generate a
+new certificate using the same scheme and existing sign key.</p>
+
+<h4>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></dt>
+
+<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>
+
+<dt><tt>-d</tt></dt>
+
+<dd>Enable debugging. This option displays the cryptographic data
+produced in eye-friendly billboards.</dd>
+
+<dt><tt>-e</tt></dt>
+
+<dd>Insert arbitrary X509v3 extension field. Not for amateurs.
+Usually produces a coredump.</dd>
+
+<dt><tt>-G</tt></dt>
+
+<dd>Generate parameters and keys for the GQ identification scheme,
+obsoleting any that may exist.</dd>
+
+<dt><tt>-g</tt></dt>
+
+<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>
+
+<dt><tt>-H</tt></dt>
+
+<dd>Generate new host keys, obsoleting any that may exist.</dd>
+
+<dt><tt>-I</tt></dt>
+
+<dd>Generate parameters for the IFF identification scheme,
+obsoleting any that may exist.</dd>
+
+<dt><tt>-M</tt></dt>
+
+<dd>Generate MD5 keys, obsoleting any that may exist.</dd>
+
+<dt><tt>-p</tt></dt>
+
+<dd>Generate a private certificate. By default, the program
+generates public certificates.</dd>
+
+<dt><tt>-S [ RSA | DSA ]</tt></dt>
+
+<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.</dd>
+
+<dt><tt>-t</tt></dt>
+
+<dd>Generate a trusted certificate. By default, the program
+generates a non-trusted certificate.</dd>
+</dl>
<h4>Symmetric Key File</h4>
-<p>The <tt>ntp-genkeys</tt> program generates MD5 symmetric keys in
-a file named <tt>
-ntpkey_MD5key_<i>hostname</i>.<i>filestamp</i></tt>. Since the file
-contains private shared values, it should be visible only to root
-and distributed by secure means to other servers and clients
-sharing the same security compartment. The NTP daemon expects this
-file with name <tt>ntp.keys</tt>, so a soft link is needed to
-direct this name to the particular file name generated. While this
-file is not used with the Autokey Version 2 protocol, it is needed
-
to authenticate some remote configuration commands used by the <a
+<p>The <tt>ntp-keygen</tt> program generates a MD5 symmetric keys
+file <tt>ntpkey_MD5key_<i>hostname.filestamp</i></tt>. Since the
+file contains private shared keys, it should be visible only to
+root and distributed by secure means to other subnet machines. The
+NTP daemon loads the file <tt>ntp.keys</tt>, so <tt>ntp-keygen</tt>
+installs a soft link from this name to the generated file.
+Subsequently, similar soft links must be installed by manual or
+automated means on the other subnet machines. While this file is
+not used with the Autokey Version 2 protocol, it is needed to
+authenticate some remote configuration commands used by the <a
href="ntpdc.htm"><tt>ntpq</tt></a> and <a href="ntpq.htm"><tt>
ntpdc</tt></a> utilities.</p>
<p>The symmetric key file contains 16 MD5 keys. Each key consists
-of 16 characters randomized over a ASCII 93-character printing
+of 16 characters randomized over the ASCII 93-character printing
subset. The file is read by the daemon at the location specified by
the <tt>keys</tt> configuration file command. Additional keys
consisting of easily remembered passwords should be added by hand
for use with the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. While
-the key identifiers for MD5 keys must be in the range 1-65,534,
-inclusive, the <tt>ntp-genkeys</tt> program uses only the
+the key identifiers for MD5 keys must be in the range 1-65,535,
+inclusive, the <tt>ntp-keygen</tt> program uses only the
identifiers from 1 to 16. The key identifier for each association
-is specified as the key argument in the <tt>server</tt> or peer
-configuration command.</p>
+is specified as the <tt>key</tt> subcommand with the <tt>
+server</tt> or <tt>peer</tt> configuration command.</p>
-<h4>Public/Private Key Files</h4>
+<h4>Private Key Files</h4>
<p>The Autokey protocol requires every host to have a
-public/private host key pair and an optional public/private sign
-key pair. The <tt>ntp-genkeys</tt> program generates a
-public/private key pair in a file named <tt>
-ntpkey_<i>keyname</i>key_<i>hostname</i>.<i>filestamp</i></tt>,
-where <i>keyname</i> is the name of the public key algorithm.
-Currently, the program generates public/private key files for both
-RSA and DSA algorithms. Since the host key is used to encrypt some
-data, it must be an RSA type. The sign key file can be a DSA type
-or the same or different RSA type. Since these files contains
-private unshared values that are useful only to the machine that
-generated them, they should be visible only to root and never
-shared with any other system or application program. The NTP daemon
-expects the host key file with name <tt>
-ntpkey_key_<i>hostname</i></tt> and the sign key file with name
-<tt>ntpkey_sign_<i>hostname</i></tt>, so soft links are needed to
-direct these names to the particular file name generated.</p>
-
-<p>The <tt>ntp-genkeys</tt> program generates the Diffie-Hellman
-parameters in a file named <tt>
-ntpkey_dh_<i>hostname</i>.<i>filestamp</i></tt>. This file is not
-used by the current Autokey version, but might be useful in related
-applications. The file contains only public values and can be
-freely transmitted and stored anywhere without further
-cryptographic protection. A number of hosts can use the same file
-in a shared directory.</p>
-
-<h4>Public Certificates</h4>
-
-<p>The Autokey protocol requires every host to have a digitally
-signed public certificate. Security procedures require the public
-key and host credentials, such as host name, responsible person,
-mail address, etc., to be provided in the form of a X.509
+private/public host key pair and an optional private/public sign
+key pair. The <tt>ntp-keygen</tt> program generates a private key
+file <tt>ntpkey_<i>keyname</i>key_<i>hostname.filestamp</i></tt>,
+where <i>keyname</i> is the name of the public key algorithm type,
+either <tt>RSA</tt> or <tt>DSA</tt>. Since the host key is used to
+encrypt some data, it must be RSA type; the sign key file can be a
+RSA or DSA type. Since these files contain both the private
+unshared key and public shared key, they are useful only to the
+machine that generates them, so should be visible only to root and
+never shared with any other system or application program. The NTP
+daemon loads the host key file <tt>ntpkey_host_<i>hostname</i></tt>
+and the sign key file <tt>ntpkey_sign_<i>hostname</i></tt>, so <tt>
+ntp-keygen</tt> installs soft links to direct these names to the
+generated files.</p>
+
+<h4>Identification Parameter Files</h4>
+
+<p>Of the four identification schemes implemented in Autokey, the
+IFF and GQ schemes require special parameters used as group keys,
+while the GQ scheme requires in addition a private/public key pair
+as well as a special certificate with the public key included in an
+X509v3 extension field. In both schemes parameter filess are
+generated once only on a designated subnet machine, then securely
+distributed to all other subnet machines. On Unix machines, a
+convenient way to do this might be the <tt>sdist</tt> facility
+often used to update the latest software within the administrative
+domain.</p>
+
+<p>The <tt>ntp-keygen</tt> program with the <tt>-I</tt> flag
+generates an IFF parameter file <tt>
+ntpkey_IFFpar_<i>hostname.filestamp</i></tt> and with the <tt>
+-G</tt> flag generates a GQ parameter file <tt>
+ntpkey_GQpar_<i>hostname.filestamp</i></tt>. The NTP daemon loads
+the IFF parameter file <tt>ntpkey_IFFpar_<i>hostname</i></tt> and
+the GQ parameter file <tt>ntpkey_GQpar_<i>hostname</i></tt>, so
+<tt>ntp-keygen</tt> installs soft links to direct these names to
+the generated files. Subsequently, similar soft links must be
+installed by manual or automated means on the other subnet
+machines.</p>
+
+<p>When a certificate is generated for the GQ scheme, the <tt>
+ntp-keygen</tt> also generates a GQ key file <tt>
+ntpkey_GQkey_<i>hostname.filestamp</i></tt>. The NTP daemon loads
+the GQ key file <tt>ntpkey_gq_<i>hostname</i></tt>, so the program
+installs a soft link to direct this name to the generated file. At
+the same time the program generates a special certificate with the
+public key component saved in the "X509v3 Subject Key Identifier"
+extension field. It is important to note that the GQ keys and
+certificates are generated at the same time and that they can be
+regenerated from time to time without requiring new GQ
+parameters.</p>
+
+<p>Identification schemes are selected during operation depending
+on the presence or absence of the respective files. The default
+when no files are present is TC; if the IFF parameter file is
+present, then that scheme is used; if the GQ parameter file is
+present, then that scheme is used; if both are present, the GQ
+scheme is used.</p>
+
+<h4>Certificates</h4>
+
+<p>The Internet security infrastructure requires every host to have
+a digitally signed public certificate. Security procedures require
+the public key and host credentials, such as host name, responsible
+person, mail address, etc., to be provided in the form of a X.509
certificate request to a trusted certificate authority or CA. The
CA attaches a digital signature to the request and returns the
-certificate itself to the requesting party. The integrity of these
-procedures depend on the certificate trail that ultimately must end
-on a self-signed certificate provided by the ultimate CA. The
+certificate with signature to the requesting party. The integrity
+of these procedures depend on the certificate trail that ultimately
+must end on a self-signed certificate provided by a trusted CA. The
OpenSSL software library provides routines that can automate this
-process. The reader is referred to the OpenSSL documentation for
-further details.</p>
-
-<p>The <tt>ntp-genkeys</tt> program generates a X.509 Version 3
-public certificate in a file named <tt>
-ntpkey_<i>digestname</i>cert_<i>hostname</i>.<i>filestamp</i></tt>,
-where <i>digestname</i> is the name of the digest/signature scheme.
-The file contains only public values and can be freely transmitted
-and stored anywhere without further cryptographic protection. The
-NTP daemon expects this file with name <tt>
-ntpkey_cert_<i>hostname</i></tt>, so a soft link is needed to
-direct this name to the particular file name generated. The Autokey
-protocol includes provisions to retrieve the server certificate and
-to have the server sign and return the client certificate. Where
-security considerations require, certificates can be transmitted to
-a trusted certificate authority (CA) and returned as a signed
-public certificate for use in the Autokey protocol.</p>
+process.</p>
+
+<p>Normally, the <tt>ntp-keygen</tt> program generates certificates
+which contain only public values, so they can be transmitted and
+stored without cryptographic protection. With the <tt>-p</tt>
+option the program generates a certificate including a "X509v3
+"Extended Key Usage" extension field with value <tt>private</tt>.
+The intent when this field is present is never to disclose the
+certificate outside the machine on which it is installed.
+Certificates generated without this option do not contain this
+field and are by default public.</p>
+
+<p>The Autokey TC identification scheme automates the certificate
+trail construction and verification process with each server at
+stratum <i>n</i> operating as a CA for clients at stratum <i>n</i>
++ 1. The <tt>ntp-keygen</tt> program generates a self-signed
+X.509v3 public certificate <tt>
+ntpkey_<i>digestname</i>cert_<i>hostnamefilestamp</i></tt>, where
+<i>digestname</i> is the name of the digest/signature scheme. The
+NTP daemon loads the certificate <tt>
+ntpkey_cert_<i>hostname</i></tt>, so <tt>ntp-keygen</tt> installs
+soft links to direct this name to the generated file. The
+ntp-keygen program with he <tt>-T</tt> flag generates a trusted
+certificate including a "X509v3 Extended Key Usage" extension field
+with value <tt>trustRoot</tt>. Certificates generated without this
+option do not contain this field and are by default
+non-trusted.</p>
+
+<p>Public certificates contain only public values and can be freely
+transmitted and stored anywhere without further cryptographic
+protection, although this is rarely necessary. The Autokey protocol
+retrieves the server certificate and requests the server sign and
+return the client certificate. Where security considerations
+require, certificates can be transmitted to an outside trusted
+certificate authority (CA) and returned as a signed public
+certificate for use in the Autokey protocol.</p>
<p>The Autokey protocol supports all digest/signature schemes
available in the OpenSSL library, including those using the MD2,
<h4>File Formats</h4>
-<p>The file formats begin with two lines, the first containing the
-actual file name, including the generated hostname and filestamp.
-The second line contains the datestamp in conventional format.
-Lines beginning with <tt>#</tt> are considered comments and ignored
-by the daemon. In the <tt>ntp.keys</tt> file, the next 16 lines
-contain the MD5 keys. If necessary, this file can be further
+<p>The file formats begin with two lines. The first contains the
+file name, including the generated hostname 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 daemon. In the <tt>ntp.keys</tt> file, the next 16
+lines contain the MD5 keys. If necessary, this file can be further
customized using an ordinary text editor. The format is described
-below. For all other files the actual cryptographic value is
-encoded in PEM-encoded printable ASCII format preceded and followed
-by MIME content identifier lines. Some values such as certificates
-and Diffied-Hellman parameters are encoded using ASN.1 encoding
-rules.</p>
+below. For all other files the cryptographic values are encoded
+first using ASN.1 encoding rules and then in PEM-encoded printable
+ASCII format preceded and followed by MIME content identifier
+lines.</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>The format of the symmetric keys file is somewhat different than
the other files in the interest of backward compatibility. Since
(UTC) via a Global Positioning Service (GPS) receiver, for example.
Typical NTP configurations utilize multiple redundant servers and
diverse network paths in order to achieve high accuracy and
-reliability. Some configurations include cryptographic
-authentication to prevent accidental or malicious protocol attacks
-and some provide automatic server discovery using IP multicast.</p>
+reliability.</p>
+
+<p>This software release implements NTP Version 4 (NTPv4), but is
+in general backwards compatible with previous versions, except NTP
+Version 1, support for which is no longer viable. NTPv4 includes
+support for both symmetric key and public key cryptography to
+prevent accidental or malicious protocol attacks, as well as
+automatic server discovery using IP multicast means. This release
+includes full support for the IPv6 address family, where the
+operating system sypports it, as well as the default IPv4 address
+family. Either or both families can be used at the same time on the
+same machine.</p>
<p>Background information on computer network time synchronization
can be found on the <a href="exec.htm">Executive Summary - Computer
number between 0.003 and 0.007 seconds is appropriate. The default
when this command is not used is 0.004 seconds.</dd>
+<dt><tt>calldelay <i>delay</i></tt></dt>
+
+<dd>This option controls the delay in seconds between the first and
+second packets sent in burst or iburst mode to allow additional
+time for a modem or ISDN call to complete.</dd>
+
<dt><tt>driftfile <i>driftfile</i></tt></dt>
<dd>This command specifies the name of the file used to record the
<dd>Specify the name and path of the configuration file. (Disable
netinfo?)</dd>
+
+
<dt><tt>-d</tt></dt>
<dd>Specify debugging mode. This flag may occur multiple times,
<dd>Don't fork.</dd>
-<dt><tt>-N <i>priority</i></tt></dt>
+<dt><tt>-N</tt></dt>
<dd>To the extent permitted by the operating system, run the <tt>
-ntpd</tt> at a high priority.</dd>
+ntpd</tt> at the highest priority.</dd>
<dt><tt>-p <i>pidfile</i></tt></dt>
<dd>Specify the name and path to record the <tt>ntpd</tt>'s process
ID.</dd>
-<dt><tt>-P</tt></dt>
+<dt><tt>-P <i>priority</i></tt></dt>
-<dd>Override the priority limit set by the operating system. Not
-recommended for sissies.</dd>
+<dd>To the extent permitted by the operating system, run the <tt>
+ntpd</tt> at priority <i>priority</i>.</dd>
<dt><tt>-q</tt></dt>
<h4>Description</h4>
-The <tt>ntpq</tt> utility program is used to query NTP servers
-which implement the recommended NTP mode 6 control message format
-about current state and to request changes in that state. The
-program may be run either in interactive mode or controlled using
-command line arguments. Requests to read and write arbitrary
+<p>The <tt>ntpq</tt> utility program is used to monitor NTP daemon
+<tt>ntpd</tt> operations and determine performance. It uses the
+standard NTP mode 6 control message formats defined in Appendix B
+of the NTPv3 specification RFC1305. The same formats are used in
+NTPv4, although some of the variables have changed and new ones
+added. The description on this page is for the NTPv4 variables.</p>
+
+<p>The program can be run either in interactive mode or controlled
+using command line arguments. Requests to read and write arbitrary
variables can be assembled, with raw and pretty-printed output
-options being available. <tt>ntpq</tt> can also obtain and print a
-list of peers in a common format by sending multiple queries to the
-server.
+options being available. The <tt>ntpq</tt> can also obtain and
+print a list of peers in a common format by sending multiple
+queries to the server.</p>
<p>If one or more request options is included on the command line
when <tt>ntpq</tt> is executed, each of the requests will be sent
while the <tt>clearlist</tt> command removes all variables from the
list.</dd>
-<dt><tt>authenticate yes | no</tt></dt>
-
-<dd>Normally <tt>ntpq</tt> does not authenticate requests unless
-they are write requests. The command <tt>authenticate yes</tt>
-causes <tt>ntpq</tt> to send authentication with all requests it
-makes. Authenticated requests causes some servers to handle
-requests slightly differently, and can occasionally melt the CPU in
-fuzzballs if you turn authentication on before doing a <tt>
-peer</tt> display. [I didn't know that - Ed.]</dd>
-
<dt><tt>cooked</tt></dt>
<dd>Causes output from query commands to be "cooked", so that
<dt><tt>keyid <i>keyid</i></tt></dt>
-<dd>This command allows the specification of a key number to be
-used to authenticate configuration requests. This must correspond
-to a key number the server has been configured to use for this
-purpose.</dd>
+<dd>This command specifies the key number to be used to
+authenticate configuration requests. This must correspond to a key
+number the server has been configured to use for this purpose.</dd>
<dt><tt>ntpversion 1 | 2 | 3 | 4</tt></dt>
<dd>Sets the NTP version number which <tt>ntpq</tt> claims in
packets. Defaults to 3, Note that mode 6 control messages (and
-modes, for that matter) didn't exist in NTP version 1. There appear
-to be no servers left which demand version 1.</dd>
+modes, for that matter) didn't exist in NTP version 1.</dd>
<dt><tt>passwd</tt></dt>
-<dd>This command prompts you to type in a password (which will not
-be echoed) which will be used to authenticate configuration
-requests. The password must correspond to the key configured for
-use by the NTP server for this purpose if such requests are to be
-successful.</dd>
+<dd>This command prompts for a password (which will not be echoed)
+which will be used to authenticate configuration requests. The
+password must correspond to the key configured for NTP server for
+this purpose.</dd>
<dt><tt>quit</tt></dt>
<h4>Control Message Commands</h4>
-<p>Each peer known to an NTP server has a 16 bit integer
-association identifier assigned to it. NTP control messages which
-carry peer variables must identify the peer the values correspond
-to by including its association ID. An association ID of 0 is
-special, and indicates the variables are system variables, whose
-names are drawn from a separate name space.</p>
+<p>Each association known to an NTP server has a 16 bit integer
+association identifier. NTP control messages which carry peer
+variables must identify the peer the values correspond to by
+including its association ID. An association ID of 0 is special,
+and indicates the variables are system variables, whose names are
+drawn from a separate name space.</p>
<p>Control message commands result in one or more NTP mode 6
messages being sent to the server, and cause the data returned to
via kernel interface.</dd>
</dl>
-<h4>NTPv4 Additional Variables</h4>
+<h4>System Variables</h4>
-<p>Additional variables displayed in the system variables list
-returned by the readvariables command include the following.</p>
+<p>The <tt>status, leap, stratum, precision, rootdelay,
+rootdispersion, refid, reftime, poll, offset, and frequency</tt>
+variables are described in RFC-1305 specification. Additional NTPv4
+system variables include the following.</p>
<dl>
-<dt><tt>state <i>state</i></tt></dt>
+<dt><tt>version</tt></dt>
-<dd>Shows the state of the clock discipline state machine.</dd>
+<dd>Everything you might need to know about the software version
+and generation time.</dd>
-<dt><tt>jitter <i>value</i></tt></dt>
+<dt><tt>processor</tt></dt>
-<dd>Shows the estimated time error of the system clock measured as
-an exponential average of RMS time differences.</dd>
+<dd>The processor and kernel identification string.</dd>
-<dt><tt>stability <i>value</i></tt></dt>
+<dt><tt>system</tt></dt>
-<dd>Shows the estimated frequency stability of the system clock
-measured as an exponential average of RMS frequency
-differences.</dd>
-</dl>
+<dd>The operating system version and release identifier.</dd>
-<p>When the NTPv4 daemon is compiled with the OpenSSL software
-library, additional system variables are displayed, including the
-following:</p>
+<dt><tt>state</tt></dt>
-<dl>
-<dt><tt>certificate <i>filestamp</i></tt></dt>
+<dd>The state of the clock discipline state machine. The values are
+described in the architecture briefing on the NTP Project page
+linked from www.ntp.org.</dd>
-<dd>Shows the NTP seconds when the certificate file was
-created.</dd>
+<dt><tt>peer</tt></dt>
-<dt><tt>hostname <i>host</i></tt></dt>
+<dd>The internal integer used to identify the association currently
+designated the system peer.</dd>
-<dd>Shows the name of the host as returned by the Unix <tt>
-gethostname()</tt> library function.</dd>
+<dt><tt>jitter</tt></dt>
+
+<dd>The estimated time error of the system clock measured as an
+exponential average of RMS time differences.</dd>
-<dt><tt>flags <i>hex</i></tt></dt>
+<dt><tt>stability</tt></dt>
-<dd>Shows the current flags word bits and message digest algorithm
-identifier (NID) in hex format. The flag high order two bytes of
-the four-byte flag word contain the NID encoded as in the OpenSSL
-software ligrary, while the low-order bits are interpreted as
-follows:</dd>
+<dd>The estimated frequency stability of the system clock measured
+as an exponential average of RMS frequency differences.</dd>
+</dl>
+
+<p>When the NTPv4 daemon is compiled with the OpenSSL software
+library, additional system variables are displayed, including some
+or all of the following, depending on the particular dance:</p>
+
+<dl>
+<dt><tt>flags</tt></dt>
+
+<dd>The current flags word bits and message digest algorithm
+identifier (NID) in hex format. The high order 16 bits of the
+four-byte word contain the NID from the OpenSSL ligrary, while the
+low-order bits are interpreted as follows:</dd>
<dd>
<dl>
<dt><tt>0x02</tt></dt>
-<dd>Public/private key file loaded</dd>
+<dd>NIST leapseconds file loaded</dd>
-<dt><tt>0x04</tt></dt>
+<dt><tt>0x10</tt></dt>
-<dd>X.509 certificate file loaded</dd>
+<dd>PC identity scheme</dd>
-<dt><tt>0x08</tt></dt>
+<dt><tt>0x20</tt></dt>
-<dd>Diffie-Hellman parameters file loaded</dd>
+<dd>IFF identity scheme</dd>
-<dt><tt>0x10</tt></dt>
+<dt><tt>0x40</tt></dt>
-<dd>NIST leapseconds table file loaded</dd>
+<dd>GQ identity scheme</dd>
</dl>
</dd>
-<dt><tt>hostkey <i>filestamp</i></tt></dt>
+<dt><tt>hostname</tt></dt>
-<dd>Shows the NTP seconds when the public/private key file was
-created.</dd>
+<dd>The name of the host as returned by the Unix <tt>
+gethostname()</tt> library function.</dd>
-<dt><tt>hostname <i>hostname</i></tt></dt>
+<dt><tt>hostkey</tt></dt>
-<dd>Shows the node name of the host.</dd>
+<dd>The NTP filestamp of the host key file.</dd>
-<dt><tt>leapseconds <i>filestamp</i></tt></dt>
+<dt><tt>cert</tt></dt>
-<dd>Shows the NTP seconds when the NIST leapseconds table file was
-created.</dd>
+<dd>A list of certificates held by the host. Each entry includes
+the subject, issuer, flags and NTP filestamp in order. The bits are
+interpreted as follows:</dd>
-<dt><tt>params <i>filestamp</i></tt></dt>
+<dd>
+<dl>
+<dt><tt>0x01</tt></dt>
-<dd>Shows the NTP seconds when the Diffie-Hellman agreement
-parameter file was created.</dd>
+<dd>certificate has been signed by the server</dd>
-<dt><tt>refresh <i>timestamp</i></tt></dt>
+<dt><tt>0x02</tt></dt>
+
+<dd>certificate is trusted</dd>
+
+<dt><tt>0x04</tt></dt>
+
+<dd>certificate is private</dd>
+
+<dt><tt>0x08</tt></dt>
+
+<dd>certificate contains errors and should not be trusted</dd>
+</dl>
+</dd>
+
+<dt><tt>leapseconds</tt></dt>
-<dd>Shows the NTP seconds when the host public cryptographic values
+<dd>The NTP filestamp of the NIST leapseconds file.</dd>
+
+<dt><tt>refresh</tt></dt>
+
+<dd>The NTP timestamp when the host public cryptographic values
were refreshed and signed.</dd>
-<dt><tt>signature <i>scheme</i></tt></dt>
+<dt><tt>signature</tt></dt>
-<dd>Shows the host message digest and digital signature scheme, as
-encoded by the OpenSSL software library.</dd>
+<dd>The host digest/signature scheme name from the OpenSSL
+library.</dd>
-<dt><tt>tai <i>offset</i></tt></dt>
+<dt><tt>tai</tt></dt>
-<dd>Shows the TAI-UTC offset in seconds obtained from the NIST
+<dd>The TAI-UTC offset in seconds obtained from the NIST
leapseconds table.</dd>
</dl>
-<p>Additional variables displayed in the peer variables list
-returned by the readvariables command include the following.</p>
+<h4>Peer Variables</h4>
+
+<p>The <tt>status, srcadr, srcport, dstadr, dstport, leap, stratum,
+precision, rootdelay, rootdispersion, readh, hmode, pmode, hpoll,
+ppoll, offset, delay, dspersion, reftime</tt> variables are
+described in the RFC-1305 specification, as are the timestamps <tt>
+org, rec and xmt</tt>. Additional NTPv4 system variables include
+the following.</p>
<dl>
-<dt><tt>flash <i>flashcode</i></tt></dt>
+<dt><tt>flash</tt></dt>
-<dd>Shows the flash code for the most recent packet received. The
+<dd>The flash code for the most recent packet received. The
encoding and meaning of these codes is given later in this
page.</dd>
-<dt><tt>jitter <i>value</i></tt></dt>
+<dt><tt>jitter</tt></dt>
-<dd>Shows the estimated time error of the peer clock measured as an
+<dd>The estimated time error of the peer clock measured as an
exponential average of RMS time differences.</dd>
-<dt><tt>unreach <i>count</i></tt></dt>
+<dt><tt>unreach</tt></dt>
-<dd>Shows the value of the counter which records the number of poll
+<dd>The value of the counter which records the number of poll
intervals since the last valid packet was received.</dd>
</dl>
following:</p>
<dl>
-<dt><tt>certificate <i>filestamp</i></tt></dt>
-
-<dd>Shows the NTP seconds when the server certificate file was
-created.</dd>
-
-<dt><tt>flags <i>hex</i></tt></dt>
-
-<dd>Shows the current flag bits. See the source code for the bit
-encodeing.</dd>
+<dt><tt>flags</tt></dt>
-<dt><tt>hcookie <i>hex</i></tt></dt>
+<dd>The current flag bits. This word is the server host status word
+with additional bits used by the Autokey state machine. See the
+source code for the bit encoding.</dd>
-<dd>Shows the host cookie used in the key agreement algorithm.</dd>
+<dt><tt>hostname</tt></dt>
-<dt><tt>hostname <i>hostname</i></tt></dt>
-
-<dd>Shows the node name of the server.</dd>
+<dd>The server host name.</dd>
<dt><tt>initkey <i>key</i></tt></dt>
-<dd>Shows the initial key used by the key list generator in the
-autokey protocol.</dd>
+<dd>The initial key used by the key list generator in the Autokey
+protocol.</dd>
<dt><tt>initsequence <i>index</i></tt></dt>
-<dd>Shows the initial index used by the key list generator in the
-autokey protocol.</dd>
-
-<dt><tt>pcookie <i>hex</i></tt></dt>
+<dd>The initial index used by the key list generator in the Autokey
+protocol.</dd>
-<dd>Specifies the peer cookie used in the key agreement
-algorithm.</dd>
+<dt><tt>signature</tt></dt>
-<dt><tt>signature <i>scheme</i></tt></dt>
-
-<dd>Shows the server message digest and digital signature scheme,
-as encoded by the OpenSSL software library.</dd>
+<dd>The server message digest/signature scheme name from the
+OpenSSL software library.</dd>
<dt><tt>timestamp <i>time</i></tt></dt>
-<dd>Shows the NTP seconds when the last autokey key list was
-generated and signed.</dd>
+<dd>The NTP timestamp when the last Autokey key list was generated
+and signed.</dd>
</dl>
<h4>Flash Codes</h4>
<p>The <tt>flash</tt> code is a valuable debugging aid displayed in
the peer variables list. It shows the results of the original
sanity checks defined in the NTP specification RFC-1305 and
-additional ones added in NTP Version 4. There are 12 tests
-designated <tt>TEST1</tt> through <tt>TEST12</tt>. The tests are
-performed in a certain order designed to gain maximum diagnostic
-information while protecting against accidental or malicious
-errors. The <tt>flash</tt> variable is first initialized to zero.
-If after each set of tests one or more bits are set, the packet is
-discarded.</p>
-
-<p>Tests <tt>TEST4</tt> and <tt>TEST5</tt> check the access
-permissions and cryptographic message digest. If any bits are set
-after that, the packet is discarded. Tests <tt>TEST10</tt> and <tt>
-TEST11</tt> check the authentication state using Autokey public-key
-cryptography, as described in the <a href="authopt.htm">
-Authentication Options</a> page. If any bits are set and the
-association has previously been marked reachable, the packet is
-discarded; otherwise, the originate and receive timestamps are
-saved, as required by the NTP protocol, and processing
-continues.</p>
+additional ones added in NTPv4. There are 12 tests designated <tt>
+TEST1</tt> through <tt>TEST12</tt>. The tests are performed in a
+certain order designed to gain maximum diagnostic information while
+protecting against accidental or malicious errors. The <tt>
+flash</tt> variable is initialized to zero as each packet is
+received. If after each set of tests one or more bits are set, the
+packet is discarded.</p>
<p>Tests <tt>TEST1</tt> through <tt>TEST3</tt> check the packet
timestamps from which the offset and delay are calculated. If any
bits are set, the packet is discarded; otherwise, the packet header
-variables are saved. Tests <tt>TEST6</tt> through <tt>TEST8</tt>
-check the health of the server. If any bits are set, the packet is
-discarded; otherwise, the offset and delay relative to the server
-are calculated and saved. Test <tt>TEST9</tt> checks the health of
-the association itself. If any bits are set, the packet is
-discarded; otherwise, the saved variables are passed to the clock
-filter and mitigation algorithms.</p>
-
-<p>The <tt>flash</tt> bits for each test read in increasing order
-from the least significant bit are defined as follows.</p>
+variables are saved. <tt>TEST4</tt> and <tt>TEST5</tt> are
+associated with access control and cryptographic authentication. If
+any bits are set, the packet is discarded immediately with nothing
+changed.</p>
+
+<p>Tests <tt>TEST6</tt> through <tt>TEST8</tt> check the health of
+the server. If any bits are set, the packet is discarded;
+otherwise, the offset and delay relative to the server are
+calculated and saved. <tt>TEST9</tt> checks the health of the
+association itself. If any bits are set, the packet is discarded;
+otherwise, the saved variables are passed to the clock filter and
+mitigation algorithms.</p>
+
+<p>Tests <tt>TEST10</tt> through <tt>TEST12</tt> check the
+authentication state using Autokey public-key cryptography, as
+described in the <a href="authopt.htm">Authentication Options</a>
+page. If any bits are set and the association has previously been
+marked reachable, the packet is discarded; otherwise, the originate
+and receive timestamps are saved, as required by the NTP protocol,
+and processing continues.</p>
+
+
+<p>The <tt>flash</tt> bits for each test are defined as
+follows.</p>
<dl>
-<dt><tt>TEST1</tt></dt>
+<dt><tt>0x001 TEST1</tt></dt>
<dd>Duplicate packet. The packet is at best a casual retransmission
and at worst a malicious replay.</dd>
-<dt><tt>TEST2</tt></dt>
+<dt><tt>0x002 TEST2</tt></dt>
<dd>Bogus packet. The packet is not a reply to a message previously
sent. This can happen when the NTP daemon is restarted and before
somebody else notices.</dd>
-<dt><tt>TEST3</tt></dt>
+<dt><tt>0x004 TEST3</tt></dt>
<dd>Unsynchronized. One or more timestamp fields are invalid. This
normally happens when the first packet from a peer is
received.</dd>
-<dt><tt>TEST4</tt></dt>
+<dt><tt>0x008 TEST4</tt></dt>
<dd>Access is denied. See the <a href="accopt.htm">Access Control
Options</a> page.</dd>
-<dt><tt>TEST5</tt></dt>
+<dt><tt>0x010 TEST5</tt></dt>
<dd>Cryptographic authentication fails. See the <a href=
"authopt.htm">Authentication Options</a> page.</dd>
-<dt><tt>TEST6</tt></dt>
+<dt><tt>0x020TEST6</tt></dt>
<dd>The server is unsynchronized. Wind up its clock first.</dd>
-<dt><tt>TEST7</tt></dt>
+<dt><tt>0x040 TEST7</tt></dt>
<dd>The server stratum is at the maximum than 15. It is probably
unsynchronized and its clock needs to be wound up.</dd>
-<dt><tt>TEST8</tt></dt>
+<dt><tt>0x080 TEST8</tt></dt>
<dd>Either the root delay or dispersion is greater than one second,
which is highly unlikely unless the peer is unsynchronized to
Mars.</dd>
-<dt><tt>TEST9</tt></dt>
+<dt><tt>0x100 TEST9</tt></dt>
<dd>Either the peer delay or dispersion is greater than one second,
which is higly unlikely unless the peer is on Mars.</dd>
-<dt><tt>TEST10</tt></dt>
+<dt><tt>0x200 TEST10</tt></dt>
<dd>The autokey protocol has detected an authentication failure.
See the <a href="authopt.htm">Authentication Options</a> page.</dd>
-<dt><tt>TEST11</tt></dt>
+<dt><tt>0x400 TEST11</tt></dt>
<dd>The autokey protocol has not verified the server or peer is
proventic and has valid public key credentials. See the <a href=
"authopt.htm">Authentication Options</a> page.</dd>
-<dt><tt>TEST12</tt></dt>
+<dt><tt>0x800 TEST12</tt></dt>
<dd>A protocol or configuration error has occured in the public key
algorithms or a possible intrusion event has been detected. See the
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
-
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Reference Clock Drivers</title>
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Reference Clock Drivers</title>
</head>
- <body>
-
+<body>
<h3>Reference Clock Drivers</h3>
- <img align="left" src="pic/stack1a.jpg" alt="gif">
-Master Time Facility at the <a
- href="http://www.eecis.udel.edu/%7Emills/lab.htm"> UDel Internet Research
-Laboratory</a>: <br clear="left">
-
-<hr>
-<p>Support for most of the commonly available radio and modem reference clocks
-is included in the default configuration of the NTP daemon for Unix <tt>ntpd</tt>.
-Individual clocks can be activated by configuration file commands, specifically
-the <tt> server</tt> and <tt>fudge</tt> commands described in the <a
- href="ntpd.htm"><tt>ntpd</tt> program manual page</a>. The following discussion
-presents Information on how to select and configure the device drivers in
-a running Unix system.</p>
-
-<p>Many radio reference clocks can be set to display local time as adjusted
-for timezone and daylight saving mode. For use with NTP the clock must be
-set for Coordinated Universal Time (UTC) only. Ordinarily, these adjustments
-are performed by the kernel, so the fact that the clock runs on UTC will
-be transparent to the user.</p>
-
-<p>Radio and modem clocks by convention have addresses in the form 127.127.<i>t.u</i>,
-where <i>t</i> is the clock type and <i>u</i> is a unit number in the range
-0-3 used to distinguish multiple instances of clocks of the same type. Most
-of these clocks require support in the form of a serial port or special bus
-peripheral, but some can work directly from the audio codec found in some
-workstations. The particular device is normally specified by adding a soft
-link <tt>/dev/device<i>u</i></tt> to the particular hardware device involved,
-where <i><tt>u</tt></i> correspond to the unit number above.</p>
-
-<p>Most clock drivers communicate with the reference clock using a serial
-port, usually at 9600 bps. There are several application program interfaces
-(API) used in the various Unix and NT systems, most of which can be detected
-at configuration time. Thus, it is important that the NTP daemon and utilities
-be compiled on the target system or clone. In some cases special features
-are available, such as timestamping in the kernel or pulse-per-second (PPS)
-interface. In most cases these features can be detected at configuration
-time as well; however, the kernel may have to be recompiled in order for
-them to work.</p>
-
-<p>The audio drivers are a special case. These include support for the NIST
-time/frequency stations WWV and WWVH, the Canadian time/frequency station
-CHU and generic IRIG signals. Currently, support for the Solaris and SunOS
-audio API is included in the distribution. It is left to the volunteer corps
-to extend this support to other systems. Further information on hookup, debugging
-and monitoring is given in the <a href="audio.htm">Audio Drivers</a> page.</p>
-
-<p>The local clock driver is also a special case. A server configured with
-this driver can operate as a primary server to synchronize other clients
-when no other external synchronization sources are available. If the server
-is connected directly or indirectly to the public Internet, there is some
-danger that it can adversely affect the operation of unrelated clients. Carefully
-read the <a href="driver1.htm">Undisciplined Local Clock</a> page and respect
-the stratum limit.</p>
-
-<p>The local clock driver also supports an external synchronization source
-such as a high resolution counter disciplined by a GPS receiver, for example.
-Further information is on the <a href="extern.htm">External Clock Discipline
-and the Local Clock Driver</a> page.</p>
-
+
+<img align="left" src="pic/stack1a.jpg" alt="gif">Master Time
+Facility at the <a href="http://www.eecis.udel.edu/~mills/lab.htm">
+UDel Internet Research Laboratory</a>: <br clear="left">
+<hr>
+<p>Support for most of the commonly available radio and modem
+reference clocks is included in the default configuration of the
+NTP daemon for Unix <tt>ntpd</tt>. Individual clocks can be
+activated by configuration file commands, specifically the <tt>
+server</tt> and <tt>fudge</tt> commands described in the <a href=
+"ntpd.htm"><tt>ntpd</tt> program manual page</a>. The following
+discussion presents Information on how to select and configure the
+device drivers in a running Unix system.</p>
+
+<p>Many radio reference clocks can be set to display local time as
+adjusted for timezone and daylight saving mode. For use with NTP
+the clock must be set for Coordinated Universal Time (UTC) only.
+Ordinarily, these adjustments are performed by the kernel, so the
+fact that the clock runs on UTC will be transparent to the
+user.</p>
+
+<p>Radio and modem clocks by convention have addresses in the form
+127.127.<i>t.u</i>, where <i>t</i> is the clock type and <i>u</i>
+is a unit number in the range 0-3 used to distinguish multiple
+instances of clocks of the same type. Most of these clocks require
+support in the form of a serial port or special bus peripheral, but
+some can work directly from the audio codec found in some
+workstations. The particular device is normally specified by adding
+a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware
+device involved, where <i><tt>u</tt></i> correspond to the unit
+number above.</p>
+
+<p>Most clock drivers communicate with the reference clock using a
+serial port, usually at 9600 bps. There are several application
+program interfaces (API) used in the various Unix and NT systems,
+most of which can be detected at configuration time. Thus, it is
+important that the NTP daemon and utilities be compiled on the
+target system or clone. In some cases special features are
+available, such as timestamping in the kernel or pulse-per-second
+(PPS) interface. In most cases these features can be detected at
+configuration time as well; however, the kernel may have to be
+recompiled in order for them to work.</p>
+
+<p>The audio drivers are a special case. These include support for
+the NIST time/frequency stations WWV and WWVH, the Canadian
+time/frequency station CHU and generic IRIG signals. Currently,
+support for the Solaris and SunOS audio API is included in the
+distribution. It is left to the volunteer corps to extend this
+support to other systems. Further information on hookup, debugging
+and monitoring is given in the <a href="audio.htm">Audio
+Drivers</a> page.</p>
+
+<p>The local clock driver is also a special case. A server
+configured with this driver can operate as a primary server to
+synchronize other clients when no other external synchronization
+sources are available. If the server is connected directly or
+indirectly to the public Internet, there is some danger that it can
+adversely affect the operation of unrelated clients. Carefully read
+the <a href="driver1.htm">Undisciplined Local Clock</a> page and
+respect the stratum limit.</p>
+
+<p>The local clock driver also supports an external synchronization
+source such as a high resolution counter disciplined by a GPS
+receiver, for example. Further information is on the <a href=
+"extern.htm">External Clock Discipline and the Local Clock
+Driver</a> page.</p>
+
<h4>Driver Calibration</h4>
-
-<p>Some drivers depending on longwave and shortwave radio services need to
-know the radio propagation time from the transmitter to the receiver, which
-can amount to some tens of milliseconds. This must be calculated for each
-specific receiver location and requires the geographic coordinates of both
-the transmitter and receiver. The transmitter coordinates for various radio
-services are given in the <a href="qth.htm">Stations, Frequencies and Geographic
-Coordinates</a> page. Receiver coordinates can be obtained or estimated from
-various sources. The actual calculations are beyond the scope of this document.</p>
-
-<p>When more than one clock driver is supported, it is often the case that
-each shows small systematic offset differences relative to the rest. To reduce
-the effects of jitter when switching from one driver to the another, it is
-useful to calibrate the drivers to a common ensemble offset. The <tt>enable
-calibrate</tt> configuration command in the <a href="miscopt.htm">Miscellaneous
-Options</a> page is useful for this purpose. The calibration function can
-also be enabled and disabled using the <tt>ntpdc</tt> program utility.</p>
-
-<p>Most clock drivers use the <tt>time1</tt> value specified in the <tt>fudge</tt>
-configuration command to provide the calibration correction when this cannot
-be provided by the clock or interface. When the calibration function is enabled,
-the <tt>time1</tt> value is automatically adjusted to match the offset of
-the remote server or local clock driver selected for synchronization. Ordinarily,
-the NTP selection algorithm chooses the best from among all sources, usually
-the best radio clock determined on the basis of stratum, synchronization
-distance and jitter. The calibration function adjusts the <tt>time1</tt>
-values for all clock drivers except this source so that their indicated offsets
-tend to zero. If the selected source is the kernel PPS discipline, the <tt>fudge
+
+<p>Some drivers depending on longwave and shortwave radio services
+need to know the radio propagation time from the transmitter to the
+receiver, which can amount to some tens of milliseconds. This must
+be calculated for each specific receiver location and requires the
+geographic coordinates of both the transmitter and receiver. The
+transmitter coordinates for various radio services are given in the
+<a href="qth.htm">Stations, Frequencies and Geographic
+Coordinates</a> page. Receiver coordinates can be obtained or
+estimated from various sources. The actual calculations are beyond
+the scope of this document.</p>
+
+<p>When more than one clock driver is supported, it is often the
+case that each shows small systematic offset differences relative
+to the rest. To reduce the effects of jitter when switching from
+one driver to the another, it is useful to calibrate the drivers to
+a common ensemble offset. The <tt>enable calibrate</tt>
+configuration command in the <a href="miscopt.htm">Miscellaneous
+Options</a> page is useful for this purpose. The calibration
+function can also be enabled and disabled using the <tt>ntpdc</tt>
+program utility.</p>
+
+<p>Most clock drivers use the <tt>time1</tt> value specified in the
+<tt>fudge</tt> configuration command to provide the calibration
+correction when this cannot be provided by the clock or interface.
+When the calibration function is enabled, the <tt>time1</tt> value
+is automatically adjusted to match the offset of the remote server
+or local clock driver selected for synchronization. Ordinarily, the
+NTP selection algorithm chooses the best from among all sources,
+usually the best radio clock determined on the basis of stratum,
+synchronization distance and jitter. The calibration function
+adjusts the <tt>time1</tt> values for all clock drivers except this
+source so that their indicated offsets tend to zero. If the
+selected source is the kernel PPS discipline, the <tt>fudge
time1</tt> values for all clock drivers are adjusted.</p>
-
-<p>The adjustment function is an exponential average designed to improve
-accuracy, so the function takes some time to converge. The recommended procedure
-is to enable the function, let it run for an hour or so, then edit the configuration
-file using the <tt> time1</tt> values displayed by the <tt>ntpq</tt> utility
-and <tt> clockvar</tt> command. Finally, disable the calibration function
-to avoid possible future disruptions due to misbehaving clocks or drivers.</p>
-
+
+<p>The adjustment function is an exponential average designed to
+improve accuracy, so the function takes some time to converge. The
+recommended procedure is to enable the function, let it run for an
+hour or so, then edit the configuration file using the <tt>
+time1</tt> values displayed by the <tt>ntpq</tt> utility and <tt>
+clockvar</tt> command. Finally, disable the calibration function to
+avoid possible future disruptions due to misbehaving clocks or
+drivers.</p>
+
<h4>Performance Enhancements</h4>
-
-<p>In general, performance can be improved, especially when more than one
-clock driver is supported, to use the prefer peer function described in the
-<a href="prefer.htm">Mitigation Rules and the <tt> prefer</tt> Keyword</a>
-page. The prefer peer is ordinarily designated the remote peer or local clock
-driver which provides the best quality time. All other things equal, only
-the prefer peer source is used to discipline the system clock and jitter-producing
-"clockhopping" between sources is avoided. This is valuable when more than
-one clock driver is present and especially valuable when the PPS clock driver
-(type 22) is used. Support for PPS signals is summarized in the <a
- href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a> page.</p>
-
-<p>Where the highest performance is required, generally better than one millisecond,
-additional hardware and/or software functions may be required. Kernel modifications
-for precision time are described in the <a href="kern.htm">A Kernel Model
-for Precision Timekeeping</a> page. Special line discipline and streams modules
+
+<p>In general, performance can be improved, especially when more
+than one clock driver is supported, to use the prefer peer function
+described in the <a href="prefer.htm">Mitigation Rules and the <tt>
+prefer</tt> Keyword</a> page. The prefer peer is ordinarily
+designated the remote peer or local clock driver which provides the
+best quality time. All other things equal, only the prefer peer
+source is used to discipline the system clock and jitter-producing
+"clockhopping" between sources is avoided. This is valuable when
+more than one clock driver is present and especially valuable when
+the PPS clock driver (type 22) is used. Support for PPS signals is
+summarized in the <a href="pps.htm">Pulse-per-second (PPS) Signal
+Interfacing</a> page.</p>
+
+<p>Where the highest performance is required, generally better than
+one millisecond, additional hardware and/or software functions may
+be required. Kernel modifications for precision time are described
+in the <a href="kern.htm">A Kernel Model for Precision
+Timekeeping</a> page. Special line discipline and streams modules
for use in capturing precision timestamps are described in the <a
- href="ldisc.htm">Line Disciplines and Streams Drivers</a> page.</p>
-
+href="ldisc.htm">Line Disciplines and Streams Drivers</a> page.</p>
+
<h4>Comprehensive List of Clock Drivers</h4>
-
-<p>Following is a list showing the type and title of each driver currently
-implemented. The compile-time identifier for each is shown in parentheses.
-Click on a selected type for specific description and configuration documentation,
-including the clock address, reference ID, driver ID, device name and serial
-line speed, and features (line disciplines, etc.). For those drivers without
-specific documentation, please contact the author listed in the <a
- href="copyright.htm">Copyright Notice</a> page.</p>
-
-<p><a href="driver1.htm">Type 1</a> Undisciplined Local Clock (<tt>LOCAL</tt>)<br>
- <a href="driver2.htm">Type 2</a> Trak 8820 GPS Receiver (<tt>GPS_TRAK</tt>)<br>
- <a href="driver3.htm">Type 3</a> PSTI/Traconex 1020 WWV/WWVH Receiver (<tt>WWV_PST</tt>)<br>
- <a href="driver4.htm">Type 4</a> Spectracom WWVB and GPS Receivers (<tt>WWVB_SPEC</tt>)<br>
- <a href="driver5.htm">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers (<tt>TRUETIME</tt>)<br>
- <a href="driver6.htm">Type 6</a> IRIG Audio Decoder (<tt>IRIG_AUDIO</tt>)<br>
- <a href="driver7.htm">Type 7</a> Radio CHU Audio Demodulator/Decoder (<tt>CHU</tt>)<br>
- <a href="driver8.htm">Type 8</a> Generic Reference Driver (<tt>PARSE</tt>)<br>
- <a href="driver9.htm">Type 9</a> Magnavox MX4200 GPS Receiver (<tt>GPS_MX4200</tt>)<br>
- <a href="driver10.htm">Type 10</a> Austron 2200A/2201A GPS Receivers (<tt>GPS_AS2201</tt>)<br>
- <a href="driver11.htm">Type 11</a> Arbiter 1088A/B GPS Receiver (<tt>GPS_ARBITER</tt>)<br>
- <a href="driver12.htm">Type 12</a> KSI/Odetics TPRO/S IRIG Interface (<tt>IRIG_TPRO</tt>)<br>
- Type 13 Leitch CSD 5300 Master Clock Controller (<tt>ATOM_LEITCH</tt>)<br>
- Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)<br>
- <a href="driver5.htm">Type 15</a> * TrueTime generic receivers<br>
- <a href="driver16">Type 16</a> Bancomm GPS/IRIG Receiver (<tt>GPS_BANCOMM</tt>)<br>
- Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)<br>
- <a href="driver18.htm">Type 18</a> NIST Modem Time Service (<tt>ACTS_NIST</tt>)<br>
- <a href="driver19.htm">Type 19</a> Heath WWV/WWVH Receiver (<tt>WWV_HEATH</tt>)<br>
- <a href="driver20.htm">Type 20</a> Generic NMEA GPS Receiver (<tt>NMEA</tt>)<br>
- Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)<br>
- <a href="driver22.htm">Type 22</a> PPS Clock Discipline (<tt>PPS</tt>)<br>
- <a href="driver23.htm">Type 23</a> PTB Modem Time Service (<tt>ACTS_PTB</tt>)<br>
- <a href="driver24.htm">Type 24</a> USNO Modem Time Service (<tt>ACTS_USNO</tt>)<br>
- <a href="driver5.htm">Type 25</a> * TrueTime generic receivers<br>
- <a href="driver26.htm">Type 26</a> Hewlett Packard 58503A GPS Receiver (<tt>GPS_HP</tt>)<br>
- <a href="driver27.htm">Type 27</a> Arcron MSF Receiver (<tt>MSF_ARCRON</tt>)<br>
- <a href="driver28.htm">Type 28</a> Shared Memory Driver (<tt>SHM</tt>)<br>
- <a href="driver29.htm">Type 29</a> Trimble Navigation Palisade GPS (<tt>GPS_PALISADE</tt>)<br>
- <a href="driver30.htm">Type 30</a> Motorola UT Oncore GPS (<tt>GPS_ONCORE</tt>)<br>
- Type 31 Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)<br>
- <a href="driver32.htm">Type 32</a> Chrono-log K-series WWVB receiver (<tt>CHRONOLOG</tt>)<br>
- <a href="driver33.htm">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>)<br>
- <a href="driver34.htm">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>)<br>
- <a href="driver35.htm">Type 35</a> Conrad Parallel Port Radio Clock (<tt>PCF</tt>)<br>
- <a href="driver36.htm">Type 36</a> Radio WWV/H Audio Demodulator/Decoder
-(<tt>WWV</tt>)<br>
- <a href="driver37.htm">Type 37</a> Forum Graphic GPS Dating station (<tt>FG</tt>)<br>
- <a href="driver38.htm">Type 38</a> hopf GPS/DCF77 6021/komp for Serial Line
-(<tt>HOPF_S</tt>)<br>
- <a href="driver39.htm">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus (<tt>HOPF_P</tt>)<br>
- <a href="driver40.htm">Type 40</a> JJY Receivers (<tt>JJY</tt>)<br>
-<a href="driver44.htm">Type 44</a> NeoClock4X DCF77 / TDF receiver<br>
- </p>
-
-<p>* All TrueTime receivers are now supported by one driver, type 5. Types
-15 and 25 will be retained only for a limited time and may be reassigned
-in future.</p>
-
+
+<p>Following is a list showing the type and title of each driver
+currently implemented. The compile-time identifier for each is
+shown in parentheses. Click on a selected type for specific
+description and configuration documentation, including the clock
+address, reference ID, driver ID, device name and serial line
+speed, and features (line disciplines, etc.). For those drivers
+without specific documentation, please contact the author listed in
+the <a href="copyright.htm">Copyright Notice</a> page.</p>
+
+<p><a href="driver1.htm">Type 1</a> Undisciplined Local Clock
+(<tt>LOCAL</tt>)<br>
+<a href="driver2.htm">Type 2</a> Trak 8820 GPS Receiver
+(<tt>GPS_TRAK</tt>)<br>
+<a href="driver3.htm">Type 3</a> PSTI/Traconex 1020 WWV/WWVH
+Receiver (<tt>WWV_PST</tt>)<br>
+<a href="driver4.htm">Type 4</a> Spectracom WWVB and GPS Receivers
+(<tt>WWVB_SPEC</tt>)<br>
+<a href="driver5.htm">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers
+(<tt>TRUETIME</tt>)<br>
+<a href="driver6.htm">Type 6</a> IRIG Audio Decoder
+(<tt>IRIG_AUDIO</tt>)<br>
+<a href="driver7.htm">Type 7</a> Radio CHU Audio
+Demodulator/Decoder (<tt>CHU</tt>)<br>
+<a href="driver8.htm">Type 8</a> Generic Reference Driver
+(<tt>PARSE</tt>)<br>
+<a href="driver9.htm">Type 9</a> Magnavox MX4200 GPS Receiver
+(<tt>GPS_MX4200</tt>)<br>
+<a href="driver10.htm">Type 10</a> Austron 2200A/2201A GPS
+Receivers (<tt>GPS_AS2201</tt>)<br>
+<a href="driver11.htm">Type 11</a> Arbiter 1088A/B GPS Receiver
+(<tt>GPS_ARBITER</tt>)<br>
+<a href="driver12.htm">Type 12</a> KSI/Odetics TPRO/S IRIG
+Interface (<tt>IRIG_TPRO</tt>)<br>
+Type 13 Leitch CSD 5300 Master Clock Controller
+(<tt>ATOM_LEITCH</tt>)<br>
+Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)<br>
+<a href="driver5.htm">Type 15</a> * TrueTime generic receivers<br>
+<a href="driver16">Type 16</a> Bancomm GPS/IRIG Receiver
+(<tt>GPS_BANCOMM</tt>)<br>
+Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)<br>
+<a href="driver18.htm">Type 18</a> NIST Modem Time Service
+(<tt>ACTS_NIST</tt>)<br>
+<a href="driver19.htm">Type 19</a> Heath WWV/WWVH Receiver
+(<tt>WWV_HEATH</tt>)<br>
+<a href="driver20.htm">Type 20</a> Generic NMEA GPS Receiver
+(<tt>NMEA</tt>)<br>
+Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)<br>
+<a href="driver22.htm">Type 22</a> PPS Clock Discipline
+(<tt>PPS</tt>)<br>
+<a href="driver23.htm">Type 23</a> PTB Modem Time Service
+(<tt>ACTS_PTB</tt>)<br>
+<a href="driver24.htm">Type 24</a> USNO Modem Time Service
+(<tt>ACTS_USNO</tt>)<br>
+<a href="driver5.htm">Type 25</a> * TrueTime generic receivers<br>
+<a href="driver26.htm">Type 26</a> Hewlett Packard 58503A GPS
+Receiver (<tt>GPS_HP</tt>)<br>
+<a href="driver27.htm">Type 27</a> Arcron MSF Receiver
+(<tt>MSF_ARCRON</tt>)<br>
+<a href="driver28.htm">Type 28</a> Shared Memory Driver
+(<tt>SHM</tt>)<br>
+<a href="driver29.htm">Type 29</a> Trimble Navigation Palisade GPS
+(<tt>GPS_PALISADE</tt>)<br>
+<a href="driver30.htm">Type 30</a> Motorola UT Oncore GPS
+(<tt>GPS_ONCORE</tt>)<br>
+Type 31 Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)<br>
+<a href="driver32.htm">Type 32</a> Chrono-log K-series WWVB
+receiver (<tt>CHRONOLOG</tt>)<br>
+<a href="driver33.htm">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>)<br>
+<a href="driver34.htm">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>)<br>
+<a href="driver35.htm">Type 35</a> Conrad Parallel Port Radio Clock
+(<tt>PCF</tt>)<br>
+<a href="driver36.htm">Type 36</a> Radio WWV/H Audio
+Demodulator/Decoder (<tt>WWV</tt>)<br>
+<a href="driver37.htm">Type 37</a> Forum Graphic GPS Dating station
+(<tt>FG</tt>)<br>
+<a href="driver38.htm">Type 38</a> hopf GPS/DCF77 6021/komp for
+Serial Line (<tt>HOPF_S</tt>)<br>
+<a href="driver39.htm">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus
+(<tt>HOPF_P</tt>)<br>
+<a href="driver40.htm">Type 40</a> JJY Receivers (<tt>JJY</tt>)<br>
+Type 41 TrueTime 560 IRIG-B Decoder <br>
+<a href="driver42.htm">Type 42</a> Zyfer GPStarplus Receiver)
+</p>
+
+
+<p>* All TrueTime receivers are now supported by one driver, type
+5. Types 15 and 25 will be retained only for a limited time and may
+be reassigned in future.</p>
+
<p>Additional Information</p>
-
-<p><a href="prefer.htm">Mitigation Rules and the <tt>prefer</tt> Keyword</a><br>
- <a href="rdebug.htm">Debugging Hints for Reference Clock Drivers</a><br>
- <a href="kern.htm">A Kernel Model for Precision Timekeeping</a><br>
- <a href="ldisc.htm">Line Disciplines and Streams Drivers</a><br>
- <a href="audio.htm">Reference Clock Audio Drivers</a><br>
- <a href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a><br>
- <a href="howto.htm">How To Write a Reference Clock Driver</a></p>
-
-<hr> <a href="index.htm"><img align="left" src="pic/home.gif" alt="gif">
-</a>
-<address><a href="mailto:mills@udel.edu">David L. Mills <mills@udel.edu></a></address>
- <br>
+
+<p><a href="prefer.htm">Mitigation Rules and the <tt>prefer</tt>
+Keyword</a><br>
+<a href="rdebug.htm">Debugging Hints for Reference Clock
+Drivers</a><br>
+<a href="kern.htm">A Kernel Model for Precision Timekeeping</a><br>
+<a href="ldisc.htm">Line Disciplines and Streams Drivers</a><br>
+<a href="audio.htm">Reference Clock Audio Drivers</a><br>
+<a href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a><br>
+<a href="howto.htm">How To Write a Reference Clock Driver</a></p>
+
+<hr>
+<a href="index.htm"><img align="left" src="pic/home.gif" alt=
+"gif"></a>
+
+<address><a href="mailto:mills@udel.edu">David L. Mills
+<mills@udel.edu></a></address>
</body>
</html>
</p>
<hr>
-<p>This document was last updated 31 December 2001</p>
+<p>This document was last updated 25 July 2002</p>
<h4>NTP Version 4 Release Notes</h4>
<p>This release of the NTP Version 4 (NTPv4) daemon for Unix, VMS
-and Windows (NT4 and 2000) incorporates new features and
-refinements to the NTP Version 3 (NTPv3) algorithms. However, it
-continues the tradition of retaining backwards compatibility with
-older versions, including NTPv3 and NTPv2, but not NTPv1. Support
-for NTPv1 has been discontinued because of certain security
-vulnerabilities. The NTPv4 version has been under development for
-quite a while and isn't finished yet. In fact, quite a number of
-NTPv4 features have already been retrofitted in the older NTPv3,
-although this version is not actively maintained by the NTPv4
-developer's group.</p>
-
-<p>The code compiles and runs properly in the test host
-configuration available to the developer corps, including Sun
+and Windows incorporates new features and refinements to the NTP
+Version 3 (NTPv3) algorithms. However, it continues the tradition
+of retaining backwards compatibility with older versions, including
+NTPv3 and NTPv2, but not NTPv1. Support for NTPv1 has been
+discontinued because of certain security vulnerabilities. The NTPv4
+version has been under development for quite a while and isn't
+finished yet. In fact, quite a number of NTPv4 features have
+already been retrofitted in the older NTPv3, although this version
+is not actively maintained by the NTPv4 developer corps.</p>
+
+<p>The code compiles and runs properly in all test host
+configurations available to the developer corps, including Sun
Microsystems, Digital/Compaq, Hewlett Packard, FreeBSD and Linux.
-Other volunteers have verified it works in IRIX, Windows NT and
-several others. We invite comments and corrections about the
-various architectures, operating systems and hardware complement
-that can't be verified by the developer corps. Of particular
-interest are Windows 2000, VMS and various reference clock drivers.
-As always, corrections and bugfixes are warmly received, especially
-in the form of context diffs sent to <a href="mailto:bugs@ntp.org">
-<bugs@ntp.org></a><.</p>
+Other volunteers have verified it works in IRIX and certain
+versions of Windows NT and several others. We invite comments and
+corrections about the various architectures, operating systems and
+hardware complement that can't be verified by the developer corps.
+Of particular interest are Windows, VMS and various reference clock
+drivers. As always, corrections and bugfixes are warmly received,
+especially in the form of context diffs sent to <a href=
+"mailto:bugs@ntp.org"><bugs@ntp.org>></a>.</p>
<p>This release has been compiled and tested on many systems,
-including SunOS 4.1.3, Solaris 2.5.1-2.8, Alpha Tru64 4.0, Ultrix
-4.4, Linux 2.4.2, FreeBSD 4.3 and HP-UX 10.02. It has been compiled
-and tested on Windows NT, but not yet on any other Windows version
-or for VMS. There are several new features apparently incompatible
-with Linux systems, including some modes used with the Autokey
-protocol. The developers corps looks for help elsewhere to resolve
-these differences. We are relying on the NTP volunteer corps to do
-that.</p>
+including SunOS 4.1.3, Solaris 2.5.1-2.8, Alpha Tru64 4.0-5.1,
+Ultrix 4.4, Linux 2.4.2, FreeBSD 4.5 and HP-UX 10.02. It has been
+compiled and tested by others on Windows NT4, 2000 and XP, but not
+yet on other Windows versions or for VMS. There are several new
+features apparently incompatible with Linux systems, including some
+modes used with the Autokey protocol. The developers corps looks
+for help elsewhere to resolve these differences. We are relying on
+the NTP volunteer corps to do that.</p>
<p>This note summarizes the differences between this software
release of NTPv4, called ntp-4.x.x, and the previous NTPv3 version,
<h4>New Features</h4>
<ol>
+<li>
+<p>Support for the IPv6 addressing family is included in this
+distribution. If the Basic Socket Interface Extensions for IPv6
+(RFC-2553) is detected, support for the IPv6 address family is
+generated in addition to the default support for the IPv4 address
+family. Combination IPv6 and IPv4 configurations have been
+successfully tested in all protocol modes supported by NTP and
+using both symmetric and public key (Autokey) cryptography.
+However, users should note that IPv6 support is new and we have not
+had a lot of experience with it in various operational scenarios
+and local infrastructure environments. As always, feedback is
+welcome.</p>
+</li>
+
<li>
<p>Most calculations are now done using 64-bit floating double
format, rather than 64-bit fixed point format. The motivation for
<li>
<p>This release includes support for the <a href=
-"http://www.eecis.udel.edu/~mills/resource.htm"><i>
+"ftp://ftp.udel.edu/usa/ftp/pub/ntp/software/"><i>
nanokernel</i></a> precision time kernel support, which is now in
stock Linux and FreeBSD kernels. If a precision time source such as
a GPS timing receiver or cesium clock is available, kernel
timekeeping can be improved to the order of one microsecond. The
-older precision time kernel for the Digital Tru64 and Ultrix, as
-well as Sun Microsystems SunOS and Solaris, continues to be
-supported.</p>
+older <i>microtime</i> kernel for Digital/Compaq/HP Tru64, Digital
+Ultrix, as well as Sun Microsystems SunOS and Solaris, continues to
+be supported.</p>
</li>
<li>
<p>This release includes support for Autokey public-key
cryptography, which is the preferred scheme for authenticating
-servers to clients. It uses NTP header extensions fields based on:
-Mills, D.L. Public-Key cryptography for the Network Time Protocol.
-Internet Draft draft-ietf-stime-ntpauth-01.txt, University of
-Delaware, April 2001, 45 pp. <a href=
-"http://www.eecis.udel.edu/~mills/database/memos/draft-ietf-stime-ntpauth-01.txt">
-(ASCII)</a>. However, this release implements Version 2 of the
-Autokey protocol, which includes support for additional message
-digest and digital signature schemes supported by the OpenSSL
-software library. The new design greatly simplifies key generation
-and distribution and provides orderly key refreshment. Security
-procedures and media formats are consistent with industry standard
-X.509 certificates and authority procedures. Specific improvements
-to the protocol include a reduction in the number of messages
-required and a method to protect the cookie used in client/server
-mode against disclosure. Additional information about Autokey
-cryptography is contained in the <a href="authopt.htm">
-Authentication Options</a> page and links from there. See also the
-new <tt>cryptostats</tt> monitoring statistics file in the <a
-monopt.htm="">Monitoring Options</a> page.</p>
+servers to clients. Autokey Version 2 uses NTP header extension
+fields and protocols as described on the NTP project page linked
+from www.ntp.org. This release includes support for additional
+message digest and digital signature schemes supported by the
+OpenSSL software library, as well as new identity schemes based on
+cryptographic challenge/responce algorithms. The new design greatly
+simplifies key generation and distribution and provides orderly key
+refreshment. Security procedures and media formats are consistent
+with industry standard X.509 Version 3 certificates and authority
+procedures. Specific improvements to the protocol include a
+reduction in the number of messages required and a method to
+protect the cookie used in client/server mode against disclosure.
+Additional information about Autokey cryptography is contained in
+the <a href="authopt.htm">Authentication Options</a> page and links
+from there. See also the new <tt>cryptostats</tt> monitoring
+statistics file in the <a monopt.htm="">Monitoring Options</a>
+page.</p>
</li>
<li>
authentication of servers and clients without identifying servers
or clients in advance. In multicast mode a server sends a message
at fixed intervals using specified multicast group addresses, while
-clients listen on these addresses. Upon receiving the message, a
-client exchanges several messages with the server in order to
-calibrate the multicast propagation delay between the client and
-server. In manycast mode a client sends a message to a specified
-multicast group address and expects one or more servers to reply.
-Using engineered algorithms, the client selects an appropriate
-subset of servers from the messages received and continues an
-ordinary client/server campaign. The manycast scheme can provide
-somewhat better accuracy than the multicast scheme at the price of
-additional network overhead. See the <a href="manyopt.htm">
-Automatic NTP Configuration Options</a> page for further
-information.</p>
+clients listen on these addresses.</p>
+
+<p>Upon receiving the the first message, a client exchanges several
+messages with the server in order to calibrate the multicast
+propagation delay between the client and server and run the
+authentication protocol. In manycast mode a client sends a message
+to a specified multicast group address and expects one or more
+servers to reply. Using engineered algorithms, the client selects
+an appropriate subset of servers from the messages received and
+continues an ordinary client/server campaign. The manycast scheme
+can provide somewhat better accuracy than the multicast scheme at
+the price of additional network overhead. See the <a href=
+"manyopt.htm">Automatic NTP Configuration Options</a> page for
+further information.</p>
</li>
<li>
been extended to all drivers as an intrinsic function. Most of the
drivers in NTPv3 have been converted to the NTPv4 interface and
continue to operate as before. New drivers have been added for
-several GPS receivers now on the market for a total of 39 drivers.
-Drivers for the Canadian standard time and frequency station CHU,
-the US standard time and frequency stations WWV/H and for IRIG
+several GPS receivers now on the market for a total of 44 drivers.
+Audio drivers for the Canadian standard time and frequency station
+CHU, the US standard time and frequency stations WWV/H and for IRIG
signals have been updated and capabilities added to allow direct
-connection of these signals to the Sun audio port <tt>
-/dev/audio</tt>. See the <a href="audio.htm">Reference Clock Audio
-Drivers</a> page for further information.</p>
+connection of these signals to a Sun or FreeBSD audio port. See the
+<a href="audio.htm">Reference Clock Audio Drivers</a> page for
+further information.</p>
</li>
<li>
automake</tt>, which should greatly ease the task of porting to new
and different programming environments, as well as reduce the
incidence of bugs due to improper handling of idiosyncratic kernel
-functions.</p>
+functions. Version control is provided by <tt>Bitkeeper</tt> using
+an online repository at www.ntp.org.</p>
</li>
<li>
things to worry about:</p>
<ol>
+<li>
+<p>When both IPv4 and IPv6 address families are in use, the host's
+resolver library may not choose the intended address family if a
+server has an IPv4 and IPv6 address associated with the same DNS
+name. The solution is to use the IPv4 or IPv6 address directly in
+such cases or use another DNS name that only resolves to the
+intended address. Older versions of <tt>ntpdc</tt> will only show
+the IPv4 associations with the <tt>peers</tt> and other simular
+commands. Older versions of <tt>ntpq</tt> will show 0.0.0.0 for
+IPv6 associations with the <tt>peers</tt> and other simular
+commands.</p>
+</li>
+
+<li>
+<p>There is a minor change to the reference ID field of the NTP
+packet header when operating with IPv6 associations. In IPv4
+associations this field contains the 32-bit IPv4 address of the
+server, in order to detect and avoid loops. In IPv6 associations
+this field contains the first 32-bits of a MD5 hash formed from the
+address (IPv4 or IPv6) each of the configured associations.
+Normally, this detail would not be of concern; however, the <tt>
+ntptrace</tt> program originally depended on that field in order to
+display a server traceback to the primary reference source. This
+program has now been replaced by a script that does the same
+function, but does not depend on the reference ID field. The <tt>
+ntpdc</tt> utility now uses a special version number to communicate
+with the <tt>ntpd</tt> server. The server uses this version number
+to select which address family to used in reply packets. The <tt>
+ntpdc</tt> program falls back to the older version behavior when
+communicating with older NTP versions.</p>
+</li>
+
<li>
<p>As required by Defense Trade Regulations (DTR), the
cryptographic routines supporting the Data Encryption Standard
NTPv4 a new interface has been implemented for the OpenSSL
cryptographic library, which is widely available on the web at
www.openssl.org. This library replaces the library formerly
-available from RSA Laboratories.. Besides being somewhat faster and
-widely available, the OpenSSL library supports many additional
+available from RSA Laboratories. Besides being somewhat faster and
+more widely available, the OpenSSL library supports many additional
cryptographic algorithms, which are now selectable at run time.
Directions for using OpenSSL are in the <a href="build.htm">
Building and Installing the Distribution</a> page.</p>
distrbution.</p>
</li>
-<li>
-<p>This version implements Version 2 of the Autokey protocol, which
-uses packet formats based on the encoding rules of ASN.1.
-Therefore, it is not backwards comaptible with previous versions of
-the Autokey protocol. The new version uses standard cryptographic
-keys and X.509 certificates produced by NTP utility programs, the
-OpenSSL support services and commercial certificate authorities. In
-addition, this version provides additional security protection for
-the cookies used in client/server modes.</p>
-</li>
-
<li>
<p>The NTPv4 enable and disable commands have a few changes in the
arguments. See the <tt>ntpd</tt> <a href="miscopt.htm">
projects / thirdparty / ntp.git / commitdiff
