-Configuration Options -

From: Harlan Stenn Date: Thu, 15 Aug 2002 06:33:39 +0000 (-0400) Subject: HTML updates from Dave Mills. X-Git-Tag: NTP_4_1_73~77 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1a0566da95d43b32af242f8bbc35d7be1507aa09;p=thirdparty%2Fntp.git HTML updates from Dave Mills. bk: 3d5b4b43S4PbQe0xR9EV3k7nhWnutw --- diff --git a/html/accopt.htm b/html/accopt.htm index b0f5a9db95..db38b2b427 100644 --- a/html/accopt.htm +++ b/html/accopt.htm @@ -17,25 +17,37 @@ Walt Kelly

Access Control Support

-ntpd 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 Notes on Configuring NTP and Setting up a -NTP Subnet page. +ntpd 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 Notes on Configuring NTP and Setting up a NTP +Subnet page.

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.

+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.

+ +

Clients can be denied service because they are explicitly +included in the restrict list created by the restrict +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.

The Kiss-of-Death Packet

@@ -44,23 +56,24 @@ further action except incrementing statistics counters. Sometimes a 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 -kod 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 kod flag -is not set, the server simply drops the packet.

- -

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.

+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 noserve flag of the matching restrict list +entry is set, the code is "DENY"; if the limited flag is +set and the rate limit is exceeded, the code is "RATE". Finally, if +a cryptographic violation occurs, the code is "CRYP".

+ +

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.

Access Control Commands

@@ -69,8 +82,8 @@ is sent to the system log.

[flag][...]

The numeric_address argument, expressed in -dotted- quad form, is the address of an host or network. The -mask argument, also expressed in dotted-quad form, +dotted-quad form, is the address of a host or network. The +mask argument, also expressed in dotted-quad form, defaults to 255.255.255.255, meaning that the numeric_address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask @@ -94,7 +107,11 @@ may be specified:

kod -If access is denied, send a kiss-of-death packet. +An access violation normally results in an automatic +kiss-of-death (KOD) packet, after which the kod flag is +seet to prevent further KOD packets. If the kod flag is +set in the restrict command, a KOD packet will not be +sent. ignore diff --git a/html/authopt.htm b/html/authopt.htm index 0f5bfc0915..5e1e945ec7 100644 --- a/html/authopt.htm +++ b/html/authopt.htm @@ -54,13 +54,13 @@ configuration operations. In addition, if public key cryptography is enabled, the commands specify the message digest and signature encryption scheme. -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. + 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. @@ -70,69 +70,53 @@ remote configuration commands require cryptographic authentication. This flag can be set or reset by the enable and disable commands and also by remote configuration commands sent by a ntpdc 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. - -It should be understood that operating with the auth -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. - -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 -authflag for name resolution and disabled it once the name -resolution process is complete. +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 auth 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. An attractive alternative where multicast support is available is manycast mode, in which clients periodically troll for servers as described in the Association Management -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. +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. 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 www.ntp.org. +distribution. Directions for doing that are on the Building and Installing the Distribution page. + +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 www.ntp.org. Symmetric Key Cryptography 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 ntp.keys, 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 -ntpq and ntpdc utility -programs. +called ntp.keys, 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 ntpq and ntpdc +utility programs. When ntpd is first started, it reads the key file specified in the keys configuration command and installs @@ -153,42 +137,45 @@ utility. 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 -http://www.openssl.org and can be installed using the -procedures outlined in the Building and -Installing the Distribution page. Once installed, the configure -and build process automatically detects the library and links the -interface routines required. +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. + +The cryptographic means necessary for all Autokey operations +provided by the OpenSSL software library. This library is available +from http://www.openssl.org +and can be installed using the procedures outlined in the Building and Installing the Distribution page. Once +installed, the configure and build process automatically detects +the library and links the interface routines required. 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 Autonomous Authentication page. 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 md5WithRSAEncryption, 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 -ntp-genkeys page. +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 md5WithRSAEncryption, 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 ntp-keygen page. The digest/signature scheme and certificate are provided to dependent clients in the Autokey protocol. Different client or peer @@ -205,86 +192,131 @@ algorithm specified in the certificate. 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 -www.ntp.org. 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. +www.ntp.org. 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. + +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 ntp-keygen utility. + +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. + +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. 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. +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. + +Interoperability + +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. + +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 +server or peer configuration command and no +key or autokey subcommands are present, the +association is not authenticated; if the key subcommand is +present, the association is authenticated using the symmetric key +ID given as argument; if the autokey subcommand is +present, the association is authenticated using Autokey. + +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. + +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. + +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 ntpq program. + +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. + +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. Key Management The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the ntp-genkeys 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 ntpq and ntpdc -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 ntp-genkeys -page. - -All key files are installed by default in -/usr/local/etc, 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 keysdir -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. - -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 ntp-genkeys page to the actual file. -This allows new file generations to be activated simply by changing -the link. However, ntpd 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 crypto configuration -command, but this is not recommended. - -All cryptographic keys and related values should be regenerated -on a periodic and automatic basis, like once per month. The -ntp-genkeys 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. - -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 ntpd 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 ntpd -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. +"genkeys.htm">ntp-keygen 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 ntpq and +ntpdc 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 +ntp-keygen page. Random Seed File @@ -301,27 +333,27 @@ page. The entropy seed used by the OpenSSL library is contained in a file, usually called .rnd, which must be available when -starting the NTP daemon or the ntp-genkeys program. The -NTP daemon will first look for the file using the path specified by -the randfile subcommand of the crypto command. If -not specified in this way, or when starting the -ntp-genkeys program, the OpenSSL library will look for the -file using the path specified by the RANDFILE environment -variable in the user home directory, whether root or some other -user. If the RANDFILE environment variable is not present, -the library will look for the .rnd 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 -ntp-genkeys program exits with a suitable error message. +starting the NTP daemon or the ntp-keygen program. The NTP +daemon will first look for the file using the path specified by the +randfile subcommand of the crypto command. If not +specified in this way, or when starting the ntp-keygen +program, the OpenSSL library will look for the file using the path +specified by the RANDFILE environment variable in the user +home directory, whether root or some other user. If the +RANDFILE environment variable is not present, the library will +look for the .rnd 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 ntp-keygen program exits +with a suitable error message. 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 ntp-genkeys +the file must be writable by root. If the ntp-keygen program is run by other than root, or if the Unix su 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 ntp-genkeys program from there +and run the ntp-keygen program from there Authentication Commands @@ -357,52 +389,67 @@ subcommands: -certificate file +cert file -Specifies the location of the public certificate file, which by -default is linked from ntpkey_cert_hostname in the + Specifies the location of the required host public certificate +file. This overrides the link ntpkey_cert_hostname +in the keys directory. + +gq file + +Specifies the location of the optional GQ keys file. This +overrides the link ntpkey_gq_hostname in the keys +directory. + +gqpar file + +Specifies the location of the optional GQ parameters file. This +overrides the link ntpkey_gqpar_hostname in the keys directory. -leap file +host file -Specifies the location of the optional leapsecond table file, -which by default is linked from ntpkey_leap in the keys + Specifies the location of the required host key file. This +overrides the link ntpkey_key_hostname in the keys directory. +iff file + +Specifies the location of the optional IFF parameters file. +This overrides the link ntpkey_iff_hostname in the +keys directory. + +leap file + +Specifies the location of the optional leapsecond file. This +overrides the link ntpkey_leap in the keys directory. + randfile file Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above. -rsakey file - -Specifies the location of the public/private key file, which by -default is linked from ntpkey_key_hostname in the -keys directory. - -signkey file +sign file -Specifies the location of the optional sign key file used to -construct digital signatures, which by default is linked from -ntpkey_sign_hostname in the keys directory. If this -file is not present, the rsakey file is used. +Specifies the location of the optional sign key file. This +overrides the link ntpkey_sign_hostname in the keys +directory. If this file is not found, the host key is also the sign +key. keys keyfile -Specifies the location of the MD5 symmetric key file containing -the keys and key identifiers used by ntpd, ntpq -and ntpdc when operating with symmetric key -cryptography. +Specifies the location of the MD5 key file containing the keys +and key identifiers used by ntpd, ntpq and +ntpdc when operating with symmetric key cryptography. keysdir path -This command requires the OpenSSL library. It specifies the -default directory path for the cryptographic files generated by the -ntp-genkeys program. The default is -/usr/local/etc/. +This command specifies the default directory path for +cryptographic keys, parameters and certificates.. The default is +/usr/local/etc/. requestkey key @@ -486,26 +533,31 @@ signed by a different private key. The certificate is invalid or signed with the wrong key. -110 (certificate expired) +110 (certificate not verified) -The certificate is not yet valid or has expired. +The certificate is not yet valid or has expired or the +signature could not be verified. 111 (bad or missing cookie) -The cookie is corrupted or bogus. +The cookie is missing, corrupted or bogus. 112 (bad or missing leapseconds table) -The leapseconds file is corrupted or bogus. +The leapseconds table is missing, corrupted or bogus. 113 (bad or missing certificate) -The server does not have the requested certificate. +The certificate is missing, corrupted or bogus. + +114 (bad or missing identification) + +The identification key is missing, corrupt or bogus. Files -See the ntp-genkeys page. +See the ntp-keygen page. -Configuration Options - -Configuration Options - - -from Pogo, -Walt Kelly - -Gnu autoconfigure tools are in the backpack. - - -Basic Configuration Options - the configure utility - -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. - -Configuration options are specified as arguments to the -configure script. Following is a summary of the current -options, as of the 4.0.99m version: - - Usage: configure [options] [host] - Options: [defaults in brackets after descriptions] -Configuration: - + + + + +Configuration Options + + +Configuration Options + +from Pogo, +Walt Kelly + +Gnu autoconfigure tools are in the backpack. + + + +Basic Configuration Options - the configure +utility + +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. + + +Configuration options are specified as arguments to the +configure script. Following is a summary of the current +options, as of the 4.0.99m version: + +Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +Configuration: + + --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 - + -Directory and file names: +Directory and file names: -+ --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local] --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX @@ -68,19 +75,19 @@ names names --program-transform-name=PROGRAM run sed PROGRAM on installed program names - + -Host type: +Host type: -+ --build=BUILD configure for building on BUILD [BUILD=HOST] --host=HOST configure for HOST [guessed] --target=TARGET configure for TARGET [TARGET=HOST] - + -Optional packages: +Optional packages: -+ --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) @@ -91,11 +98,11 @@ Optional packages: crypto=autokey Use autokey cryptography crypto=rsaref Use the RSAREF library electricfence Compile with ElectricFence malloc debugger - + -Optional features: +Optional features: -+ --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] @@ -115,12 +122,12 @@ Optional features: tick=VALUE Force a value for 'tick' tickadj=VALUE Force a value for 'tickadj' udp-wildcard Use UDP wildcard delivery - + Radio clocks (these are ordinarily enabled, if supported by the -machine and operating system): +machine and operating system): -+ all-clocks Include drivers for all suitable non-PARSE clocks [enable] ACTS NIST dialup clock @@ -163,11 +170,11 @@ clocks [enable] ULINK Ultralink WWVB receiver USNO US Naval Observatory dialup clock WWV WWV audio receiver - + -PARSE Clocks: +PARSE Clocks: -+ parse-clocks Include drivers for all suitable PARSE clocks [enable] COMPUTIME Diem Computime Radio Clock @@ -181,8 +188,12 @@ PARSE Clocks: TRIMTSIP Trimble GPS/TSIP Protocol VARITEXT VARITEXT clock WHARTON Wharton 400A Series clock - + + + + +David L. Mills +<mills@udel.edu> + + - David L. Mills <mills@udel.edu> - diff --git a/html/confopt.htm b/html/confopt.htm index 269b717195..f4f141b56a 100644 --- a/html/confopt.htm +++ b/html/confopt.htm @@ -29,12 +29,25 @@ that control various related operations. 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. +(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. + +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 reslist billboard generated by +ntpdc, 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. server address [key key | autokey] [burst] @@ -135,19 +148,23 @@ page. burst 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 server -command and s addresses. +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 calldelay command to allow additional +time for a modem or ISDN call to complete. This is designed to +improve timekeeping quality with the server command and +s addresses. iburst 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 -server command and s addresses and when -ntpd is started with the -q option. +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 calldelay command to allow additional time for a +modem or ISDN call to complete. This is designed to speed the +initial synchronization acquisition with the server +command and s addresses and when ntpd is started +with the -q option. key key diff --git a/html/copyright.htm b/html/copyright.htm index 2f052a7e2f..d152194a27 100644 --- a/html/copyright.htm +++ b/html/copyright.htm @@ -14,7 +14,7 @@ Copyright Notice *********************************************************************** * * -* 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 * @@ -45,6 +45,8 @@ kirkwood@striderfm.intel.com">Clayton Kirkwood Michael Barone <michael,barone@lmco.com> GPSVME fixes +Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca>IPv6 support + Karl Berry <karl@owl.HQ.ileaf.com> syslog to file option Greg Brackley <greg.brackley@bigfoot.com> Major rework of WINNT port. Clean up recvbuf and iosignal code into separate modules. @@ -68,6 +70,8 @@ kirkwood@striderfm.intel.com">Clayton Kirkwood Dennis Ferguson <dennis@mrbill.canet.ca> foundation code for NTP Version 2 as specified in RFC-1119 +John Hay <jhay@@icomtek.csir.co.za> IPv6 support and testing + Glenn Hollinger <glenn@herald.usask.ca> GOES clock driver Mike Iglesias <iglesias@uci.edu> DEC Alpha port diff --git a/html/debug.htm b/html/debug.htm index 26b40d1558..c674ba335c 100644 --- a/html/debug.htm +++ b/html/debug.htm @@ -125,9 +125,10 @@ correction. However, due to provisions that reduce vulnerability to 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 ntp.drift file, which is read upon subsequent -restarts, so the herky-jerky cycles should not recur. +nominal frequency correction. After this, and at one-hour +intervals, the correction is written to the ntp.drift +file, which is read upon subsequent restarts, so the herky-jerky +cycles should not recur. Verifying Correct Operation @@ -163,6 +164,104 @@ entries show the latest delay, offset and jitter in milliseconds. Note that in NTP Version 4 what used to be the dispersion column has been replaced by the jitter column. +As per the NTP specification RFC-1305, when the stratum +is between 0 and 15 for a NTP server, the refid field +shows the server DNS name or, if not found, the IP address in +dotted-quad. When the stratum 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 stratum for a NTP server is 0 (appears as 16 in +the billboards), the status cannot be determined. As a help in +debugging, the refid field is set as follows. + +Peer Variables + + +ACST + +The association belongs to a anycast server. + +AUTH + +Server authentication failed. Please wait while the association +is restarted. + +AUTO + +Autokey sequence failed. Please wait while the association is +restarted. + +BCST + +The association belongs to a broadcast server. + +CRYP + +Cryptographic authentication or identification failed. The +details should be in the system log file or the +cryptostats statistics file, if configured. No further +messages will be sent to the server. + +DENY + +Access denied by remote server. No further messages will be +sent to the server. + +DROP + +Lost peer in symmetric mode. Please wait while the association +is restarted. + +RSTR + +Access denied due to local policy. No further messages will be +sent to the server. + +INIT + +The association has not yet synchronized for the first +time. + +MCST + +The association belongs to a manycast server. + +NKEY + +No key found. Either the key was never installed or is not +trusted. + +RATE + +Rate exceeded. The server has temporarily denied access because +the client exceeded the rate threshold. + +RMOT + +Somebody is tinkering with the association from a remote host +running ntpdc. Not to worry unless some rascal has stolen +your keys. + +STEP + +A step change in system time has occured, but the association +has not yet resynchronized. + + +System Variables + + +INIT + +The system clock has not yet synchronized for the first +time. + +STEP + +A step change in system time has occured, but the system clock +has not yet resynchronized. + + The tattletale symbol at the left margin displays the synchronization status of each peer. The currently selected peer is marked *, while additional peers designated acceptable for @@ -209,24 +308,22 @@ xmt=bd11b21a.ac34c1a8 Sat, Jul 8 2000 13:58:50.672, 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 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 ntpq 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 ntpq page. +values of these variables may change from time to time. A useful indicator of miscellaneous problems is the flash 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 @@ -270,8 +367,10 @@ refid=pogo.udel.edu, 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" An explanation about most of these variables is in the RFC-1305 @@ -322,7 +421,7 @@ to resist errors due to severely congested network paths, as well as errors due to confused radio clocks upon the epoch of a leap second. -Special Problems +Large Frequency Errors The frequency tolerance of computer clock oscillators can vary widely, which can put a strain on the daemon's ability to @@ -358,18 +457,19 @@ alters certain kernel variables and, while the utility attempts to figure out an acceptable way to do this, there are many cases where tickadj is incompatible with a running kernel. +Access Controls + Provisions are included in ntpd for access controls which deflect unwanted traffic from selected hosts or networks. The controls described on the Access Control Options 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. The access control provisions include a limit on the packet rate @@ -380,6 +480,8 @@ disabled, but a message is sent to the system log. See the Access Control Options page for further informatin. +Large Delay Variations + 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 @@ -390,9 +492,12 @@ such scenarios, since this could result in several time steps, especially if the condition persists for greater than the stepout threshold. -The recommended approach in such scenarios is first to calibrate -the local clock frequency error by running ntpd in -continuous mode during the quiet interval and let it write the + Specific provisions have been built into ntpd to cope +with these problems. The scheme is called "huff-'n-puff and is +described on the Miscellaneous Options +page. An alternative approach in such scenarios is first to +calibrate the local clock frequency error by running ntpd +in continuous mode during the quiet interval and let it write the frequency to the ntp.drift file. Then, run ntpd -q from a cron job each day at some time in the quiet interval. In systems with the nanokernel or microkernel performance @@ -406,12 +511,12 @@ milliseconds. Reliable source authentication requires the use of symmetric key or public key cryptography, as described on the Authentication Options 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 -,ntp-genkeys program. +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 ntp-keygen program. Problems with symmetric key authentication are usually due to mismatched keys or improper use of the trustedkey command. @@ -433,28 +538,32 @@ authenticated. Users are cautioned that running with authentication disabled is very dangerous, since an intruder can easily strike up an association and inject false time values. -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 Authentication Options page. -Common problems with configuration and key generation are -mismatched key files, broken links and missing or broken random -seed file. +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 ntpd 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 Authentication +Options page. Common problems with configuration and key +generation are mismatched key files, broken links and missing or +broken random seed file. 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. +a good way to verify correct operation. A statistics file +cryptostats 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. To assist debugging every NTP extension field is displayed in the trace along with the Autokey operation code. Every extension @@ -514,8 +623,7 @@ the servers as truechimers or falsetickers, may be unable to find a majority of truechimers among the server population. If all else fails, see the FAQ and/or the discussion and -briefings at -Network Time Synchronization Project. +briefings at the NTP Project page. diff --git a/html/driver44.htm b/html/driver44.htm index 0d2938426b..600d9dc814 100755 --- a/html/driver44.htm +++ b/html/driver44.htm @@ -67,14 +67,14 @@ Both receivers have the same output string. For more information about the NeoClock4X receiver please visit http://www.linum.com/redir/jump/id=neoclock4x&action=redir. - + á Fudge Factors time1 time Specifies the time offset calibration factor with the default value - off 0.16958333 seconds. This offset is used to correct serial line and + 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 fudge the time1 offset ALWAYS add a value off 0.16958333. This is neccessary to compensate to delay that is caused by transmit the timestamp diff --git a/html/genkeys.htm b/html/genkeys.htm index cd1edd9342..64aea60843 100644 --- a/html/genkeys.htm +++ b/html/genkeys.htm @@ -2,10 +2,10 @@ -ntp-genkeys - generate public and private keys +ntp-keygen - generate public and private keys -ntp-genkeys - generate public and private keys +ntp-keygen - generate public and private keys from Alice's @@ -17,46 +17,110 @@ Adventures in Wonderland, Lewis Carroll Synopsis -ntp-genkeys +ntp-keygen Description -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. +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. + +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 +ntpkey_ and end with the postfix +hostname.filestamp, where hostname is the +name returned by the Unix gethostname() routine and +filestamp 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 rm ntpkey* command or all files generated at +a specific time can be removed by a rm *filestamp +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. + +All files are installed by default in /usr/local/etc, +which is normally in a shared filesystem in NFS-mounted networks. +The default can be overridden by the keysdir configuration +command. The actual location of each file can be overridden by the +crypto 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 ntp-keygen page. However, the files for +a machine can be put in a more private place, such as /etc +if necessary. + +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. + +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 ntp-keygen page to the generated +files. This allows new file generations to be activated simply by +changing the link. However, ntpd 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. + +All cryptographic keys and related values should be regenerated +on a periodic and automatic basis, like once per month. The +ntp-keygen 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. As explained in the Authentication Options 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 ntp-genkeys program. -Directions for doing this are on the Authentication Options -page. - -The safest way to run the ntp-genkeys program is logged -in directly as root. The recommended procedure is change to the -keys directory, usually /ust/local/etc 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. +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 +ntp-keygen program. If a site supports OpenSSL or its +companion OpenSSH, it is very likely that means to do this are +already available. + +Running the program + +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 +ntp-keygen program is logged in directly as root. The +recommended procedure is change to the keys directory, usually +/ust/local/etc 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. + +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. Running the program as other than root and using the Unix su command to assume root may not work properly, since by @@ -64,139 +128,299 @@ default the OpenSSL library looks for the random seed file .rnd in the user home directory. However, there should be only one .rnd, most conveniently in the root directory, so it is convenient to define the $RANDFILE environment variable -used by the OpenSSL library as the path to /.rnd. +used by the OpenSSL library as the path to /.rnd. 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 /etc using the keysdir 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. - -File Naming Conventions - -All file names include the hostname of the generating -host together with the NTP filestamp 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 gethostname() library routine. The -filestamp is the NTP seconds in decimal ASCII format. Both the -ntp-genkeys 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. - -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 -RSA_MD5, which stands for the MD5 message digest with RSA -encryption scheme. The ntp-genkeys program can make -public/private keys, certificates and certificate requests for all -schemes supported by the OpenSSL library. - -In its present form, the ntp-genkeys 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 /usr/local/etc 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. +keys and certificates of other clients or servers, as these data +are obtained automatically by the Autokey protocol. + +Examples + +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. + +On each trusted server as root, change to the keys directory. To +insure a fresh fileset, remove all ntpkey files. Then run +ntp-keygen -T to generate keys and trusted certificates. +On all other machines do the same, but leave off the -T +flag to generate keys and nontrusted certificates. When complete, +start ntpd 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. + +After setting up the environment it is advisable to update +certificates from time to time, if only to extend the validity +interval. Simply run ntp-keygen 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. + +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 alice run +ntp-keygen -p to generate the keys and private certificate. +Then, using secure means, copy the host key file +ntpkey_RSAkey_alice and certificate file +ntpkey_RSA-MD5_cert_alice to all other subnet machines. On +each machine bob install a soft link from the generic name +ntpkey_host_bob to ntpkey_RSAkey_alice and soft +link ntpkey_cert_bob to +ntpkey_RSA-MD5_cert_alice. 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. + +For the IFF scheme proceed as in the TC scheme, except use the +-I flag instead of -P. Then, using secure means, +copy the IFF parameter file ntpkeys_IFFpar_alice to all +other subnet machines. On each machine bob install a soft +link from the generic ntpkey_iffpar_bob 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. + +For the GQ scheme proceed as in the TC scheme, except use the +-G flag instead of -P. Then, using secure means, +copy the GQ parameters file ntpkeys_GQpar_alice to all +other subnet machines. On each machine bob install a soft +link from the generic ntpkey_gqpar_bob to this file. If +the ntp-keygen program is run on bob before these +steps are complete, then run the program again on bob to +generate the GQ keys file ntpkeys_GQkey_bob and link +unique to bob. 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. + +If it is necessary to use a different sign key or different +digest/signature scheme than the default, run ntp-keygen +with the -S option and either RSA or DSA +argument as needed. The most often need to do this is when a +DSA-signed certificate is used. If ntp-keygen 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 ntp-keygen with +the -c option and selected scheme as needed. If +ntp-keygen is run again without the option, it will generate a +new certificate using the same scheme and existing sign key. + +Command Line Options + + +-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | +RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] + +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 RSA-MD5. + +-d + +Enable debugging. This option displays the cryptographic data +produced in eye-friendly billboards. + +-e + +Insert arbitrary X509v3 extension field. Not for amateurs. +Usually produces a coredump. + +-G + +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. + +-g + +Generate keys for the GQ identification scheme using the +existing GQ parameters. If the GQ parameters do not yet exist, +create them first. + +-H + +Generate new host keys, obsoleting any that may exist. + +-I + +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. + +-M + +Generate MD5 keys, obsoleting any that may exist. + +-p + +Generate a private certificate. By default, the program +generates public certificates. + +-S [ RSA | DSA ] + +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. + +-t + +Generate a trusted certificate. By default, the program +generates a non-trusted certificate. + Symmetric Key File -The ntp-genkeys program generates MD5 symmetric keys in -a file named -ntpkey_MD5key_hostname.filestamp. 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 ntp.keys, 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 The ntp-keygen program generates a MD5 symmetric keys +file ntpkey_MD5key_hostname.filestamp. 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 ntp.keys, so ntp-keygen +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 ntpq and ntpdc utilities. 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 keys configuration file command. Additional keys consisting of easily remembered passwords should be added by hand for use with the ntpq and ntpdc programs. While -the key identifiers for MD5 keys must be in the range 1-65,534, -inclusive, the ntp-genkeys program uses only the +the key identifiers for MD5 keys must be in the range 1-65,535, +inclusive, the ntp-keygen program uses only the identifiers from 1 to 16. The key identifier for each association -is specified as the key argument in the server or peer -configuration command. +is specified as the key subcommand with the +server or peer configuration command. -Public/Private Key Files +Private Key Files The Autokey protocol requires every host to have a -public/private host key pair and an optional public/private sign -key pair. The ntp-genkeys program generates a -public/private key pair in a file named -ntpkey_keynamekey_hostname.filestamp, -where keyname 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 -ntpkey_key_hostname and the sign key file with name -ntpkey_sign_hostname, so soft links are needed to -direct these names to the particular file name generated. - -The ntp-genkeys program generates the Diffie-Hellman -parameters in a file named -ntpkey_dh_hostname.filestamp. 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. - -Public Certificates - -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 ntp-keygen program generates a private key +file ntpkey_keynamekey_hostname.filestamp, +where keyname is the name of the public key algorithm type, +either RSA or DSA. 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 ntpkey_host_hostname +and the sign key file ntpkey_sign_hostname, so +ntp-keygen installs soft links to direct these names to the +generated files. + +Identification Parameter Files + +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 sdist facility +often used to update the latest software within the administrative +domain. + +The ntp-keygen program with the -I flag +generates an IFF parameter file +ntpkey_IFFpar_hostname.filestamp and with the +-G flag generates a GQ parameter file +ntpkey_GQpar_hostname.filestamp. The NTP daemon loads +the IFF parameter file ntpkey_IFFpar_hostname and +the GQ parameter file ntpkey_GQpar_hostname, so +ntp-keygen 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. + +When a certificate is generated for the GQ scheme, the +ntp-keygen also generates a GQ key file +ntpkey_GQkey_hostname.filestamp. The NTP daemon loads +the GQ key file ntpkey_gq_hostname, 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. + +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. + +Certificates + +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. - -The ntp-genkeys program generates a X.509 Version 3 -public certificate in a file named -ntpkey_digestnamecert_hostname.filestamp, -where digestname 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 -ntpkey_cert_hostname, 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. +process. + +Normally, the ntp-keygen program generates certificates +which contain only public values, so they can be transmitted and +stored without cryptographic protection. With the -p +option the program generates a certificate including a "X509v3 +"Extended Key Usage" extension field with value private. +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. + +The Autokey TC identification scheme automates the certificate +trail construction and verification process with each server at +stratum n operating as a CA for clients at stratum n ++ 1. The ntp-keygen program generates a self-signed +X.509v3 public certificate +ntpkey_digestnamecert_hostnamefilestamp, where +digestname is the name of the digest/signature scheme. The +NTP daemon loads the certificate +ntpkey_cert_hostname, so ntp-keygen installs +soft links to direct this name to the generated file. The +ntp-keygen program with he -T flag generates a trusted +certificate including a "X509v3 Extended Key Usage" extension field +with value trustRoot. Certificates generated without this +option do not contain this field and are by default +non-trusted. + +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. The Autokey protocol supports all digest/signature schemes available in the OpenSSL library, including those using the MD2, @@ -226,18 +450,26 @@ can be provided on request to other clients and servers. File Formats -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 # are considered comments and ignored -by the daemon. In the ntp.keys file, the next 16 lines -contain the MD5 keys. If necessary, this file can be further + 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 date +format. Lines beginning with # are considered comments and +ignored by the daemon. In the ntp.keys 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. +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. + +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. The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since diff --git a/html/index.htm b/html/index.htm index c90b95d9ef..764287e51b 100644 --- a/html/index.htm +++ b/html/index.htm @@ -29,9 +29,18 @@ tens of milliseconds on WANs relative to Coordinated Universal Time (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. +reliability. + +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. Background information on computer network time synchronization can be found on the Executive Summary - Computer diff --git a/html/miscopt.htm b/html/miscopt.htm index 05d354e5ee..faaebb3014 100644 --- a/html/miscopt.htm +++ b/html/miscopt.htm @@ -28,6 +28,12 @@ be used under these circumstances. Typically (for Ethernet), a number between 0.003 and 0.007 seconds is appropriate. The default when this command is not used is 0.004 seconds. +calldelay delay + +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. + driftfile driftfile This command specifies the name of the file used to record the diff --git a/html/ntpd.htm b/html/ntpd.htm index c7a4e98835..4598cbf8c5 100644 --- a/html/ntpd.htm +++ b/html/ntpd.htm @@ -289,6 +289,8 @@ to 022. Specify the name and path of the configuration file. (Disable netinfo?) + + -d Specify debugging mode. This flag may occur multiple times, @@ -335,20 +337,20 @@ group address 224.0.1.1 (requires multicast kernel). Don't fork. --N priority +-N To the extent permitted by the operating system, run the -ntpd at a high priority. +ntpd at the highest priority. -p pidfile Specify the name and path to record the ntpd's process ID. --P +-P priority -Override the priority limit set by the operating system. Not -recommended for sissies. +To the extent permitted by the operating system, run the +ntpd at priority priority. -q diff --git a/html/ntpq.htm b/html/ntpq.htm index 4854a4a1cd..c0f62ea229 100644 --- a/html/ntpq.htm +++ b/html/ntpq.htm @@ -21,15 +21,19 @@ Walt Kelly Description -The ntpq 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 +The ntpq utility program is used to monitor NTP daemon +ntpd 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. + +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. ntpq can also obtain and print a -list of peers in a common format by sending multiple queries to the -server. +options being available. The ntpq can also obtain and +print a list of peers in a common format by sending multiple +queries to the server. If one or more request options is included on the command line when ntpq is executed, each of the requests will be sent @@ -126,16 +130,6 @@ command can be used to remove individual variables from the list, while the clearlist command removes all variables from the list. - authenticate yes | no - -Normally ntpq does not authenticate requests unless -they are write requests. The command authenticate yes -causes ntpq 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 -peer display. [I didn't know that - Ed.] - cooked Causes output from query commands to be "cooked", so that @@ -171,25 +165,22 @@ modified using the command line -n switch. keyid keyid -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. +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. ntpversion 1 | 2 | 3 | 4 Sets the NTP version number which ntpq 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. +modes, for that matter) didn't exist in NTP version 1. passwd -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. +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. quit @@ -212,12 +203,12 @@ a timeout will be twice the timeout value set. Control Message Commands -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. +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. Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to @@ -433,50 +424,60 @@ either indirectly via the PPS reference clock driver or directly via kernel interface. -NTPv4 Additional Variables +System Variables -Additional variables displayed in the system variables list -returned by the readvariables command include the following. +The status, leap, stratum, precision, rootdelay, +rootdispersion, refid, reftime, poll, offset, and frequency +variables are described in RFC-1305 specification. Additional NTPv4 +system variables include the following. -state state +version -Shows the state of the clock discipline state machine. +Everything you might need to know about the software version +and generation time. -jitter value +processor -Shows the estimated time error of the system clock measured as -an exponential average of RMS time differences. +The processor and kernel identification string. -stability value +system -Shows the estimated frequency stability of the system clock -measured as an exponential average of RMS frequency -differences. - +The operating system version and release identifier. -When the NTPv4 daemon is compiled with the OpenSSL software -library, additional system variables are displayed, including the -following: +state - -certificate filestamp +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. -Shows the NTP seconds when the certificate file was -created. +peer -hostname host +The internal integer used to identify the association currently +designated the system peer. -Shows the name of the host as returned by the Unix -gethostname() library function. +jitter + +The estimated time error of the system clock measured as an +exponential average of RMS time differences. -flags hex +stability -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: +The estimated frequency stability of the system clock measured +as an exponential average of RMS frequency differences. + + +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: + + +flags + +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: @@ -486,75 +487,101 @@ follows: 0x02 -Public/private key file loaded +NIST leapseconds file loaded -0x04 +0x10 -X.509 certificate file loaded +PC identity scheme -0x08 +0x20 -Diffie-Hellman parameters file loaded +IFF identity scheme -0x10 +0x40 -NIST leapseconds table file loaded +GQ identity scheme -hostkey filestamp +hostname -Shows the NTP seconds when the public/private key file was -created. +The name of the host as returned by the Unix +gethostname() library function. -hostname hostname +hostkey -Shows the node name of the host. +The NTP filestamp of the host key file. -leapseconds filestamp +cert -Shows the NTP seconds when the NIST leapseconds table file was -created. +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: -params filestamp + + +0x01 -Shows the NTP seconds when the Diffie-Hellman agreement -parameter file was created. +certificate has been signed by the server -refresh timestamp +0x02 + +certificate is trusted + +0x04 + +certificate is private + +0x08 + +certificate contains errors and should not be trusted + + + +leapseconds -Shows the NTP seconds when the host public cryptographic values + The NTP filestamp of the NIST leapseconds file. + +refresh + +The NTP timestamp when the host public cryptographic values were refreshed and signed. -signature scheme +signature -Shows the host message digest and digital signature scheme, as -encoded by the OpenSSL software library. +The host digest/signature scheme name from the OpenSSL +library. -tai offset +tai -Shows the TAI-UTC offset in seconds obtained from the NIST + The TAI-UTC offset in seconds obtained from the NIST leapseconds table. -Additional variables displayed in the peer variables list -returned by the readvariables command include the following. +Peer Variables + +The status, srcadr, srcport, dstadr, dstport, leap, stratum, +precision, rootdelay, rootdispersion, readh, hmode, pmode, hpoll, +ppoll, offset, delay, dspersion, reftime variables are +described in the RFC-1305 specification, as are the timestamps +org, rec and xmt. Additional NTPv4 system variables include +the following. -flash flashcode +flash -Shows the flash code for the most recent packet received. The + The flash code for the most recent packet received. The encoding and meaning of these codes is given later in this page. -jitter value +jitter -Shows the estimated time error of the peer clock measured as an + The estimated time error of the peer clock measured as an exponential average of RMS time differences. -unreach count +unreach -Shows the value of the counter which records the number of poll + The value of the counter which records the number of poll intervals since the last valid packet was received. @@ -563,48 +590,35 @@ library, additional peer variables are displayed, including the following: -certificate filestamp - -Shows the NTP seconds when the server certificate file was -created. - -flags hex - -Shows the current flag bits. See the source code for the bit -encodeing. +flags -hcookie hex +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. -Shows the host cookie used in the key agreement algorithm. +hostname -hostname hostname - -Shows the node name of the server. +The server host name. initkey key -Shows the initial key used by the key list generator in the -autokey protocol. +The initial key used by the key list generator in the Autokey +protocol. initsequence index -Shows the initial index used by the key list generator in the -autokey protocol. - -pcookie hex +The initial index used by the key list generator in the Autokey +protocol. -Specifies the peer cookie used in the key agreement -algorithm. +signature -signature scheme - -Shows the server message digest and digital signature scheme, -as encoded by the OpenSSL software library. +The server message digest/signature scheme name from the +OpenSSL software library. timestamp time -Shows the NTP seconds when the last autokey key list was -generated and signed. +The NTP timestamp when the last Autokey key list was generated +and signed. Flash Codes @@ -612,99 +626,102 @@ generated and signed. The flash 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 TEST1 through TEST12. The tests are -performed in a certain order designed to gain maximum diagnostic -information while protecting against accidental or malicious -errors. The flash variable is first initialized to zero. -If after each set of tests one or more bits are set, the packet is -discarded. - -Tests TEST4 and TEST5 check the access -permissions and cryptographic message digest. If any bits are set -after that, the packet is discarded. Tests TEST10 and -TEST11 check the authentication state using Autokey public-key -cryptography, as described in the -Authentication Options 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. +additional ones added in NTPv4. There are 12 tests designated +TEST1 through TEST12. The tests are performed in a +certain order designed to gain maximum diagnostic information while +protecting against accidental or malicious errors. The +flash 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. Tests TEST1 through TEST3 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 TEST6 through TEST8 -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 TEST9 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. - -The flash bits for each test read in increasing order -from the least significant bit are defined as follows. +variables are saved. TEST4 and TEST5 are +associated with access control and cryptographic authentication. If +any bits are set, the packet is discarded immediately with nothing +changed. + +Tests TEST6 through TEST8 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. TEST9 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. + +Tests TEST10 through TEST12 check the +authentication state using Autokey public-key cryptography, as +described in the Authentication Options +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. + + +The flash bits for each test are defined as +follows. -TEST1 +0x001 TEST1 Duplicate packet. The packet is at best a casual retransmission and at worst a malicious replay. -TEST2 +0x002 TEST2 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. -TEST3 +0x004 TEST3 Unsynchronized. One or more timestamp fields are invalid. This normally happens when the first packet from a peer is received. -TEST4 +0x008 TEST4 Access is denied. See the Access Control Options page. -TEST5 +0x010 TEST5 Cryptographic authentication fails. See the Authentication Options page. -TEST6 +0x020TEST6 The server is unsynchronized. Wind up its clock first. -TEST7 +0x040 TEST7 The server stratum is at the maximum than 15. It is probably unsynchronized and its clock needs to be wound up. -TEST8 +0x080 TEST8 Either the root delay or dispersion is greater than one second, which is highly unlikely unless the peer is unsynchronized to Mars. -TEST9 +0x100 TEST9 Either the peer delay or dispersion is greater than one second, which is higly unlikely unless the peer is on Mars. -TEST10 +0x200 TEST10 The autokey protocol has detected an authentication failure. See the Authentication Options page. -TEST11 +0x400 TEST11 The autokey protocol has not verified the server or peer is proventic and has valid public key credentials. See the Authentication Options page. -TEST12 +0x800 TEST12 A protocol or configuration error has occured in the public key algorithms or a possible intrusion event has been detected. See the diff --git a/html/refclock.htm b/html/refclock.htm index df4af3a9df..90a349e505 100644 --- a/html/refclock.htm +++ b/html/refclock.htm @@ -1,202 +1,255 @@ - - - Reference Clock Drivers + +Reference Clock Drivers - - + Reference Clock Drivers - -Master Time Facility at the UDel Internet Research -Laboratory: - - -Support for most of the commonly available radio and modem reference clocks -is included in the default configuration of the NTP daemon for Unix ntpd. -Individual clocks can be activated by configuration file commands, specifically -the server and fudge commands described in the ntpd program manual page. The following discussion -presents Information on how to select and configure the device drivers in -a running Unix system. - -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. - -Radio and modem clocks by convention have addresses in the form 127.127.t.u, -where t is the clock type and u 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 /dev/deviceu to the particular hardware device involved, -where u correspond to the unit number above. - -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. - -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 Audio Drivers page. - -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 Undisciplined Local Clock page and respect -the stratum limit. - -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 External Clock Discipline -and the Local Clock Driver page. - + +Master Time +Facility at the +UDel Internet Research Laboratory: + +Support for most of the commonly available radio and modem +reference clocks is included in the default configuration of the +NTP daemon for Unix ntpd. Individual clocks can be +activated by configuration file commands, specifically the +server and fudge commands described in the ntpd program manual page. The following +discussion presents Information on how to select and configure the +device drivers in a running Unix system. + +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. + +Radio and modem clocks by convention have addresses in the form +127.127.t.u, where t is the clock type and u +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 /dev/deviceu to the particular hardware +device involved, where u correspond to the unit +number above. + +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. + +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 Audio +Drivers page. + +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 Undisciplined Local Clock page and +respect the stratum limit. + +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 External Clock Discipline and the Local Clock +Driver page. + Driver Calibration - -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 Stations, Frequencies and Geographic -Coordinates page. Receiver coordinates can be obtained or estimated from -various sources. The actual calculations are beyond the scope of this document. - -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 enable -calibrate configuration command in the Miscellaneous -Options page is useful for this purpose. The calibration function can -also be enabled and disabled using the ntpdc program utility. - -Most clock drivers use the time1 value specified in the fudge -configuration command to provide the calibration correction when this cannot -be provided by the clock or interface. When the calibration function is enabled, -the time1 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 time1 -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 fudge + + 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 +Stations, Frequencies and Geographic +Coordinates page. Receiver coordinates can be obtained or +estimated from various sources. The actual calculations are beyond +the scope of this document. + +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 enable calibrate +configuration command in the Miscellaneous +Options page is useful for this purpose. The calibration +function can also be enabled and disabled using the ntpdc +program utility. + +Most clock drivers use the time1 value specified in the +fudge configuration command to provide the calibration +correction when this cannot be provided by the clock or interface. +When the calibration function is enabled, the time1 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 time1 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 fudge time1 values for all clock drivers are adjusted. - -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 time1 values displayed by the ntpq utility -and clockvar command. Finally, disable the calibration function -to avoid possible future disruptions due to misbehaving clocks or drivers. - + +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 +time1 values displayed by the ntpq utility and +clockvar command. Finally, disable the calibration function to +avoid possible future disruptions due to misbehaving clocks or +drivers. + Performance Enhancements - -In general, performance can be improved, especially when more than one -clock driver is supported, to use the prefer peer function described in the -Mitigation Rules and the prefer Keyword -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 Pulse-per-second (PPS) Signal Interfacing page. - -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 Kernel Model -for Precision Timekeeping page. Special line discipline and streams modules + + In general, performance can be improved, especially when more +than one clock driver is supported, to use the prefer peer function +described in the Mitigation Rules and the +prefer Keyword 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 Pulse-per-second (PPS) Signal +Interfacing page. + +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 Kernel Model for Precision +Timekeeping page. Special line discipline and streams modules for use in capturing precision timestamps are described in the Line Disciplines and Streams Drivers page. - +href="ldisc.htm">Line Disciplines and Streams Drivers page. + Comprehensive List of Clock Drivers - -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 Copyright Notice page. - -Type 1 Undisciplined Local Clock (LOCAL) - Type 2 Trak 8820 GPS Receiver (GPS_TRAK) - Type 3 PSTI/Traconex 1020 WWV/WWVH Receiver (WWV_PST) - Type 4 Spectracom WWVB and GPS Receivers (WWVB_SPEC) - Type 5 TrueTime GPS/GOES/OMEGA Receivers (TRUETIME) - Type 6 IRIG Audio Decoder (IRIG_AUDIO) - Type 7 Radio CHU Audio Demodulator/Decoder (CHU) - Type 8 Generic Reference Driver (PARSE) - Type 9 Magnavox MX4200 GPS Receiver (GPS_MX4200) - Type 10 Austron 2200A/2201A GPS Receivers (GPS_AS2201) - Type 11 Arbiter 1088A/B GPS Receiver (GPS_ARBITER) - Type 12 KSI/Odetics TPRO/S IRIG Interface (IRIG_TPRO) - Type 13 Leitch CSD 5300 Master Clock Controller (ATOM_LEITCH) - Type 14 EES M201 MSF Receiver (MSF_EES) - Type 15 * TrueTime generic receivers - Type 16 Bancomm GPS/IRIG Receiver (GPS_BANCOMM) - Type 17 Datum Precision Time System (GPS_DATUM) - Type 18 NIST Modem Time Service (ACTS_NIST) - Type 19 Heath WWV/WWVH Receiver (WWV_HEATH) - Type 20 Generic NMEA GPS Receiver (NMEA) - Type 21 TrueTime GPS-VME Interface (GPS_VME) - Type 22 PPS Clock Discipline (PPS) - Type 23 PTB Modem Time Service (ACTS_PTB) - Type 24 USNO Modem Time Service (ACTS_USNO) - Type 25 * TrueTime generic receivers - Type 26 Hewlett Packard 58503A GPS Receiver (GPS_HP) - Type 27 Arcron MSF Receiver (MSF_ARCRON) - Type 28 Shared Memory Driver (SHM) - Type 29 Trimble Navigation Palisade GPS (GPS_PALISADE) - Type 30 Motorola UT Oncore GPS (GPS_ONCORE) - Type 31 Rockwell Jupiter GPS (GPS_JUPITER) - Type 32 Chrono-log K-series WWVB receiver (CHRONOLOG) - Type 33 Dumb Clock (DUMBCLOCK) - Type 34 Ultralink WWVB Receivers (ULINK) - Type 35 Conrad Parallel Port Radio Clock (PCF) - Type 36 Radio WWV/H Audio Demodulator/Decoder -(WWV) - Type 37 Forum Graphic GPS Dating station (FG) - Type 38 hopf GPS/DCF77 6021/komp for Serial Line -(HOPF_S) - Type 39 hopf GPS/DCF77 6039 for PCI-Bus (HOPF_P) - Type 40 JJY Receivers (JJY) -Type 44 NeoClock4X DCF77 / TDF receiver - - -* 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. - + +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 Copyright Notice page. + +Type 1 Undisciplined Local Clock +(LOCAL) +Type 2 Trak 8820 GPS Receiver +(GPS_TRAK) +Type 3 PSTI/Traconex 1020 WWV/WWVH +Receiver (WWV_PST) +Type 4 Spectracom WWVB and GPS Receivers +(WWVB_SPEC) +Type 5 TrueTime GPS/GOES/OMEGA Receivers +(TRUETIME) +Type 6 IRIG Audio Decoder +(IRIG_AUDIO) +Type 7 Radio CHU Audio +Demodulator/Decoder (CHU) +Type 8 Generic Reference Driver +(PARSE) +Type 9 Magnavox MX4200 GPS Receiver +(GPS_MX4200) +Type 10 Austron 2200A/2201A GPS +Receivers (GPS_AS2201) +Type 11 Arbiter 1088A/B GPS Receiver +(GPS_ARBITER) +Type 12 KSI/Odetics TPRO/S IRIG +Interface (IRIG_TPRO) +Type 13 Leitch CSD 5300 Master Clock Controller +(ATOM_LEITCH) +Type 14 EES M201 MSF Receiver (MSF_EES) +Type 15 * TrueTime generic receivers +Type 16 Bancomm GPS/IRIG Receiver +(GPS_BANCOMM) +Type 17 Datum Precision Time System (GPS_DATUM) +Type 18 NIST Modem Time Service +(ACTS_NIST) +Type 19 Heath WWV/WWVH Receiver +(WWV_HEATH) +Type 20 Generic NMEA GPS Receiver +(NMEA) +Type 21 TrueTime GPS-VME Interface (GPS_VME) +Type 22 PPS Clock Discipline +(PPS) +Type 23 PTB Modem Time Service +(ACTS_PTB) +Type 24 USNO Modem Time Service +(ACTS_USNO) +Type 25 * TrueTime generic receivers +Type 26 Hewlett Packard 58503A GPS +Receiver (GPS_HP) +Type 27 Arcron MSF Receiver +(MSF_ARCRON) +Type 28 Shared Memory Driver +(SHM) +Type 29 Trimble Navigation Palisade GPS +(GPS_PALISADE) +Type 30 Motorola UT Oncore GPS +(GPS_ONCORE) +Type 31 Rockwell Jupiter GPS (GPS_JUPITER) +Type 32 Chrono-log K-series WWVB +receiver (CHRONOLOG) +Type 33 Dumb Clock (DUMBCLOCK) +Type 34 Ultralink WWVB Receivers (ULINK) +Type 35 Conrad Parallel Port Radio Clock +(PCF) +Type 36 Radio WWV/H Audio +Demodulator/Decoder (WWV) +Type 37 Forum Graphic GPS Dating station +(FG) +Type 38 hopf GPS/DCF77 6021/komp for +Serial Line (HOPF_S) +Type 39 hopf GPS/DCF77 6039 for PCI-Bus +(HOPF_P) +Type 40 JJY Receivers (JJY) +Type 41 TrueTime 560 IRIG-B Decoder +Type 42 Zyfer GPStarplus Receiver) + + + +* 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. + Additional Information - -Mitigation Rules and the prefer Keyword - Debugging Hints for Reference Clock Drivers - A Kernel Model for Precision Timekeeping - Line Disciplines and Streams Drivers - Reference Clock Audio Drivers - Pulse-per-second (PPS) Signal Interfacing - How To Write a Reference Clock Driver - - - -David L. Mills <mills@udel.edu> - + +Mitigation Rules and the prefer +Keyword +Debugging Hints for Reference Clock +Drivers +A Kernel Model for Precision Timekeeping +Line Disciplines and Streams Drivers +Reference Clock Audio Drivers +Pulse-per-second (PPS) Signal Interfacing +How To Write a Reference Clock Driver + + + + +David L. Mills +<mills@udel.edu> diff --git a/html/release.htm b/html/release.htm index 31997f3cd1..f6af546255 100644 --- a/html/release.htm +++ b/html/release.htm @@ -15,43 +15,42 @@ Adventures in Wonderland, Lewis Carroll -This document was last updated 31 December 2001 +This document was last updated 25 July 2002 NTP Version 4 Release Notes 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. - -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. + +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 -<bugs@ntp.org><. +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 <bugs@ntp.org>>. 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. +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. This note summarizes the differences between this software release of NTPv4, called ntp-4.x.x, and the previous NTPv3 version, @@ -62,6 +61,20 @@ Conformance Statement page. New Features + +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. + + Most calculations are now done using 64-bit floating double format, rather than 64-bit fixed point format. The motivation for @@ -96,38 +109,36 @@ insignificant quality changes. This release includes support for the +"ftp://ftp.udel.edu/usa/ftp/pub/ntp/software/"> nanokernel 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. +older microtime kernel for Digital/Compaq/HP Tru64, Digital +Ultrix, as well as Sun Microsystems SunOS and Solaris, continues to +be supported. 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. -(ASCII). 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 -Authentication Options page and links from there. See also the -new cryptostats monitoring statistics file in the Monitoring Options page. +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 Authentication Options page and links +from there. See also the new cryptostats monitoring +statistics file in the Monitoring Options +page. @@ -138,18 +149,20 @@ cryptography. They provide automatic discovery, configuration and 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 -Automatic NTP Configuration Options page for further -information. +clients listen on these addresses. + +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 Automatic NTP Configuration Options page for +further information. @@ -171,13 +184,13 @@ and more accurate. Support for pulse-per-second (PPS) signals has 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 -/dev/audio. See the Reference Clock Audio -Drivers page for further information. +connection of these signals to a Sun or FreeBSD audio port. See the +Reference Clock Audio Drivers page for +further information. @@ -200,7 +213,8 @@ size of almost 40 percent. automake, 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. +functions. Version control is provided by Bitkeeper using +an online repository at www.ntp.org. @@ -222,6 +236,38 @@ changed since the latest NTP Version 3 release. Following are a few things to worry about: + +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 ntpdc will only show +the IPv4 associations with the peers and other simular +commands. Older versions of ntpq will show 0.0.0.0 for +IPv6 associations with the peers and other simular +commands. + + + +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 +ntptrace 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 +ntpdc utility now uses a special version number to communicate +with the ntpd server. The server uses this version number +to select which address family to used in reply packets. The +ntpdc program falls back to the older version behavior when +communicating with older NTP versions. + + As required by Defense Trade Regulations (DTR), the cryptographic routines supporting the Data Encryption Standard @@ -229,8 +275,8 @@ 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 Building and Installing the Distribution page. @@ -244,17 +290,6 @@ conformance validation tools are in the OpenSSL software distrbution. - -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. - - The NTPv4 enable and disable commands have a few changes in the arguments. See the ntpd