From: Harlan Stenn Date: Wed, 15 Dec 2010 06:49:59 +0000 (-0500) Subject: Documentation updates from Dave Mills. X-Git-Tag: NTP_4_2_7P94~2^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9b07648f1fc96e506a4860cb582300df833f44bb;p=thirdparty%2Fntp.git Documentation updates from Dave Mills. bk: 4d086517x5Qfh3JUrbDrVhPiU2Kb0g --- diff --git a/ChangeLog b/ChangeLog index 1158291cb..6ff46863c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Documentation updates from Dave Mills. (4.2.7p93) 2010/12/13 Released by Harlan Stenn * [Bug 1510] from 4.2.6p3-RC12: Add modes 20/21 for driver 8 to support RAWDCF @ 75 baud. diff --git a/html/authopt.html b/html/authopt.html index 8b175af27..9d202feed 100644 --- a/html/authopt.html +++ b/html/authopt.html @@ -10,6 +10,7 @@ color: #FF0000; font-weight: bold; } +.style1 {color: #FF0000} @@ -17,7 +18,7 @@ color: #FF0000; gif

from Alice's Adventures in Wonderland, Lewis Carroll

Our resident cryptographer; now you see him, now you don't.

Last update: - 31-Oct-2010 3:55 + 15-Dec-2010 2:56 UTC

Autokey Public-Key Authentication

Last update: - 12-Dec-2010 21:14 + 15-Dec-2010 6:06 UTC

@@ -28,88 +28,75 @@

Introduction

This distribution includes support for the Autokey public key algorithms and protocol specified in RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This support is available only if the OpenSSL library has been installed and the --enable-autokey option is specified when the distribution is built.

Public key cryptography is generally considered more secure than symmetric key cryptography. Symmetic key cryptography is based on a shared secret which must be distributed by secure means to all participats. Public key cryptography is based on a private secret key known only to the originator and a public key known to all participants. A recipient can verify the originator has the correct private key using the public key and any of several digital signature algortihms.

Public key cryptography is generally considered more secure than symmetric key cryptography. Symmetic key cryptography is based on a shared secret key which must be distributed by secure means to all participats. Public key cryptography is based on a private secret key known only to the originator and a public key known to all participants. A recipient can verify the originator has the correct private key using the public key and any of several digital signature algortihms.

The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using message digest algorithms, such as MD5 or SHA, and verifies the source using any of several digital signature schemes, such as RSA or DSA. As used in Autokey, message digests are exceptionlly difficult to cryptanalyze, as the keys are used only once.

Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. Identity schemes provide strong security against masquerade and most forms of clogging attacks. These schemes are exceptionally difficulat to cryptanalyze, as the challenge/responsee exchange data are used only once. They are described along with an executive summary, current status, briefing slides and reading list on the Autonomous Authentication page.

Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.

Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. Identity schemes provide strong security against masquerade and most forms of clogging attacks. These schemes are exceptionally difficulat to cryptanalyze, as the challenge/response exchange data are used only once. They are described along with an executive summary, current status, briefing slides and reading list on the Autonomous Authentication page.

Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same IP addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers and clients are operated outside firewall perimeters.

Auokey is designed to authenticate servers to clients, not the other way around as in SSH. An Autokey server can support an authentication scheme such as the Trusted Certificate (TC) scheme described in RFC 5905, whle a client is free to choose between the various options. It is important to understand that these provisions are optional and that selection of which option is at the discretion of the client. If the client does not require authentication, it is free to ignore it, even if some other client of the same server elects to participate in either symmetric key or public key cryptography.

Autokey uses industry standard X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library and the ntp-keygen utility program in the NTP software distribution. A certificate includes the subject name of the client, the issuer name of the server, the public key of the server and the time period over which the the server public and private keys are valid. All Autokey hosts have a self-signed certificate with the Autokey name as both the subject and issuer. During the protocol, additional certificates are produces with the Autokey host name as subject and the host that signs the certificate as issuer.

Autokey uses industry standard X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library, and the ntp-keygen utility program in the NTP software distribution. A certificate includes the subject name of the client, the issuer name of the server, the public key of the server and the time period over which the the server public and private keys are valid. All Autokey hosts have a self-signed certificate with the Autokey name as both the subject and issuer. During the protocol, additional certificates are produced with the Autokey host name as subject and the host that signs the certificate as issuer.

There are two timeouts associated with the Autokey scheme. The key list timeout is set by the automax command, which specifies the interval between generating new key lists by the client. The default timeout of about 1.1 hr is appropriate for the majority of configurations and ordinarily should not be changed. The revoke timeout is set by the revoke command, which specifies the interval between generating new server private values. It is intended to reduce the vulnerability to cryptanalysis; however, new values require the server to encrypt each client cookie separately. The default timeout of about 36 hr is appropriate for most servers, but might be too short for national time servers.

Autokey Subnets

An Autokey subnet consists of a collection of hosts configured as an acyclic, directed tree with roots one or more trusted hosts (THs) operating at the lowest stratum of the subnet. The THs are synchronized directly or indirectly to national time services via trusted means, such as radio, satellite or telephone modem, or a private, dedicated NTP subnet. Autokey hosts operate as servers, clients or both at the same time.

A certificate trail is a sequence of certificates, each signed by a host nearer the THs and terminating at the self-signed certificate of a Th. As the Autokey protocol proceeds, each client provides its self-signed certificate to a server nearer the THs for signature. In order for the signature to succeed, the client certificate valid period must begin within the valid period of the server certificate. If the server period begins later than the client period, the client certificate has expired; if the client period begins later than the server period, the server certificate has expired. While the certificate trail authenticates each host on the trail to the THs, it does not verify the validity of the time values themselves. Ultimately, this is determined by the NTP on-wire protocool.

The Autokey protocol runs for each association separately. During the protocol the client recursively obtains all the certificates on the trail to a TH, saving each in a cache ordered from most recent to oldest. If an expired certificate is found, it is invalidate, but marked for later replacement. As the client certificate itself is not involved in the certificate trail, it can only be declared valid or expired when the server signs it.

An Autokey subnet consists of a collection of hosts configured as an acyclic, directed tree with roots one or more trusted hosts (THs) operating at the lowest stratum of the subnet. The THs are synchronized directly or indirectly to national time services via trusted means, such as radio, satellite or telephone modem, or an NTP secure group as described in the next section.. Autokey hosts operate as servers, clients or both at the same time.

A certificate trail is a sequence of certificates, each signed by a host nearer the THs and terminating at the self-signed certificate of a TH. As the Autokey protocol proceeds, each client provides its self-signed certificate to a server nearer the THs for signature. In order for the signature to succeed, the client certificate valid period must begin within the valid period of the server certificate. If the server period begins later than the client period, the client certificate has expired; if the client period begins later than the server period, the server certificate has expired. While the certificate trail authenticates each host on the trail to the THs, it does not validate the time values themselves. Ultimately, this is determined by the NTP on-wire protocool.

The Autokey protocol runs for each association separately. During the protocol the client recursively obtains all the certificates on the trail to a TH, saving each in a cache ordered from most recent to oldest. If an expired certificate is found, it is invalidated and marked for later replacement. As the client certificate itself is not involved in the certificate trail, it can only be declared valid or expired when the server signs it.

The certificates derived from each association are combined in the cache with duplicates suppressed. If it happens that two different associations contribute certificates to the cache, a certificate on the trail from one association could expire before any on another trail. In this case the remaining trails will survive until the expired certificate is replaced. Once saved in the cache, a certificate remains valid until it expires or is replaced by a new one.

It is important to note that the certificate trail is validated only at startup when an association is mobilized. Once validated in this way, the server remains validated until it is demobilized, even if certificates on the trail to the THs expire.

It is important to note that the certificate trail is validated only at startup when an association is mobilized. Once validated in this way, the server remains valid until it is demobilized, even if certificates on the trail to the THs expire.

NTP Secure Groups

NTP security groups are and extension of NTP subnets. They include in addition to certificate trails one or another identity schemes described on the Autokey Identity Schemes page. NTP secure groups are used to define cryptographic compartments and security - hierarchies. The identity scheme insures that the server is authentic and not masqueraded by an intruder acting as a middleman.

As in NTP subnets, the THs are at the lowest stratum of the secure group. For secure group THs the string specified by the -s option of the ntp-keygen program is the name used as the subject and issuer of the trusted certificate and is also the name of the secure group. This name must match the ident option - of the crypto command, which is the group name for all group hosts and the - name used in the identity files. The file naming conventions are described on +

NTP security groups are an extension of the NTP subnets described in the previous section. They include in addition to certificate trails one or another identity schemes described on the Autokey Identity Schemes page. NTP secure groups are used to define cryptographic compartments and security +hierarchies. The identity scheme insures that the server is authentic and not masqueraded by an intruder acting as a middleman.

As in NTP subnet, NTP secure groups are configured as an acyclic tree rooted on the THs. The THs are at the lowest stratum of the secure group. All group hosts construct an unbroken certificate trail from each host, possibly via intermediate hosts, and ending at a TH. In addition, each group host verifies the server has the secret group key using an identity exchange.

For secure group servers, the string specified by the -i option of the ntp-keygen program is the name of the secure group. For secure group servers this name must match the ident option + of the crypto command. For secure group clients, this name must match the ident option of the server command. This name is also used in the identity keys and parameters file names. The file naming conventions are described on the ntp-keygen page.

The Autokey identity schemes involve a challenge-response exchange where a client generates a nonce and sends to the server. The server performs a mathematical operation involving a second nonce and a secret key, and sends the result along with a hash to the client. The client performs a another mathematical operation and verifies the result with the hash. Since each exchange involves two nonces, even after repeated observations of many exchanges, an intruder cannot learn the secret group key. It is this quality that allows the secure group key to persist long after the longest period of certificate validity. In the Schnorr IFF scheme considered in this section, the secret group key is not divulged to the clients, so they cannot conspire to prove identity to other hosts.

As in NTP subnets, each secure group includes one or more trusted hosts (THs) operating at the lowest stratum in the group. For THs the group name specified by the -i option of the ntp_keygen program and the ident option of the crypto command is used as the subject and issuer of the TH self-signed trusted certificate. For the IFF scheme, the other group hosts need only the crypto command with no options.

As in NTP subnet, NTP secure group hosts are configured as an acyclic tree rooted on the THs. All group hosts construct an unbroken certificate trail from each host, possibly via intermediate hosts, and ending at a TH. In addition, each group host verifies the server has the secret key using the identity exchange. When a host starts up, it recursively retrieves the certificates along the trail to the TH in order to verify group membership and avoid masquerade and middleman attacks.

NTP Secure Group Configuration

The simplest scenario consists of a TH where the host name of the TH is also the name of the group. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the ntp-keygen -T command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the crypto configuration command with no options. Configuration with passwords is described in the ntp-keygen page. All group hosts are configured as an acyclic tree with root the TH.

An NTP secure group is an NTP subnet consisting of one or more low-stratum trusted hosts (THs) as the root from which all other group hosts derive synchronization directly or indirectly. For authentication purposes all hosts in a group must have the same group name specified by the ident option of the crypto command, in the case of servers, or by the ident option of the server configuration command, in the case of clients. Group names are used only for authentication purposes and have nothing to do with DNS names.

For THs the group name is specified by the -i option of the ntp-keygen program and must match the ident option of the crypto configuration command. For other hosts the group name is specified by the ident option of the server configuration command. In the latest version of this program, the host name and group name are independent of each other and the host option of the crypto command is deprecated. When compatibility with older versions is required, specify the same name for both the -s and -i options.

As described on the Authentication Options page, there are five identity schemes, three of which - IFF, GQ and MV - require identity files specific to each scheme. There are two types of files for each scheme, an encrypted keys file and a nonencrypted parameters file, which usually contains a subset of the keys file. In general, NTP hosts operating as certificate authorities (CAs) use the keys file and clients use the parameters file. The TAs include the THs and those group servers with dependent clients.

The parameters files are public; they can be stored in a public place and sent in the clear. The keys files are encrypted with the local password. To retrieve the keys file, a host can send a mail request to the TA including its local password. The TA encrypts the keys file with this password and returns it as an attachment. The attachment is then copied intact to the keys directory with name given in the first line of the file, but all in lower case and with the filestamp deleted. Alternatively, the parameters file can be generated using the -e option of the ntp-keygen program.

When an identity scheme is included, for example IFF, the TH generates host - key, trusted certificate and private server identity key files using the ntp-keygen - -T -I -i group command, where group is the group - name. The remaining group hosts use the same command as above. All hosts - use the crypto ident group configuration command.

Hosts with no dependent clients can retrieve client parameter files from an - archive or web page. The ntp-keygen can export these data using the -e option. - Hosts with dependent clients other than the TH must retrieve copies of the server - key files using secure means. The ntp-keygen can export these data - using the -q option. In either case the data are installed as a file +

In the latest Autokey version, the host name and group name are independent of each other and the host option of the crypto command is deprecated. When compatibility with older versions is required, specify the same name for both the -s and -i options.

The Autokey identity schemes involve a challenge-response exchange where a client generates a nonce and sends to the server. The server performs a mathematical operation involving a second nonce and the secret group key, and sends the result along with a hash to the client. The client performs a another mathematical operation and verifies the result with the hash. Since each exchange involves two nonces, even after repeated observations of many exchanges, an intruder cannot learn the secret group key. It is this quality that allows the secure group key to persist long after the longest period of certificate validity. In the Schnorr IFF scheme considered later on this page, the secret group key is not divulged to the clients, so they cannot conspire to prove identity to other hosts.

As described on the Autokey Identity Schemes page, there are five identity schemes, three of which - IFF, GQ and MV - require identity files specific to each scheme. There are two types of files for each scheme, an encrypted keys file and a nonencrypted parameters file, which usually contains a subset of the keys file. In general, NTP servers operating as certificate authorities (CAs) use the keys file and clients use the parameters file. The CAs include the THs and those group servers with dependent clients.

Hosts with no dependent clients can retrieve client parameter files from an + archive or web page. The ntp-keygen program can export these data using the -e option. + Hosts with dependent clients other than the CA must retrieve copies of the server + key files using secure means. The ntp-keygen program can export these data + using the -q option and chosen remote password. In either case the data are installed as a file and then renamed using the name given as the first line in the file, but without - the filestamp.

Configuration - Authentication Scheme

Autokey has an intimidating number of authentication options, most of which are not necessary in typical scenarios. However, the Trusted Certificate (TC) scheme is recommended for national NTP time services, such as those operated by NIST and USNO. Configuration for TC is very simple. For each server, e.g. time.nist.gov, as root:

+the filestamp.

Configuration - Authentication Schemes

Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. However, the Trusted Certificate (TC) scheme is recommended for national NTP time services, such as those operated by NIST and USNO. Configuration for TC is very simple. For each server, e.g. time.nist.gov, as root:

# cd /usr/local/etc -# ntp-keygen -T

+ # ntp-keygen -T

This generates an RSA private/public host key file and a self-signed certificate file for the RSA digital signature algorithm with the MD5 message digest algorithm. Include in the ntp.conf configuration file something like

# disable kernel # server 127.127.18.1 minpoll 12 maxpoll 17 # ACTS modem -# phone atdt913035547785 atddt913034944774 + # phone atdt913035547785 atddt913034944774 # crypto -# driftfile /etc/ntp.drift

+ # driftfile /etc/ntp.drift

Note the first three lines are specific to the ACTS driver and NIST modem telephone numbers. The second number will be tried if the first times out. Alternatively, any other reference clock can be used, or even another time server.

For each client, e.g. grundoon.udel.edu, as root:

# cd /usr/local/etc -# ntp-keygen

+ # ntp-keygen

(There is no -T option). Include in the ntp.conf configuration file something like

# server time.nist.gov iburst autokey - # crypto -# driftfile /etc/ntp.drift

+ # crypto
+ # driftfile /etc/ntp.drift

It is possible to configure clients of server grundoon.udel.edu in the same way with the server line pointing to grundoon.udel.edu. Dependent clients authenticate to time.nistg.gov through grundoon.udel.edu.

In the above configuration examples, the default Autokey host name is the string returned by the Unix gethostname() library routine. This name has nothing to do with the DNS name of the host. The Autokey host name is used as the subject and issuer names on the certificate, as well as the default password for the encrypted key files. The Autokey host name can be changed using the -s option of the ntp-keygen program. The default password can be changed using the -p option of the ntp-keygen program and the pw option of the crypto command.

In the above configuration examples, the default Autokey host name is the string returned by the Unix gethostname() library routine. However, this name has nothing to do with the DNS name of the host. The Autokey host name is used as the subject and issuer names on the certificate, as well as the default password for the encrypted keys files. The Autokey host name can be changed using the -s option of the ntp-keygen program. The default password can be changed using the -p option of the ntp-keygen program and the pw option of the crypto command.

Configuration - Identity Schemes

An authentication scheme such as TC can be augmented by an identify scheme to form a secure group. For example, the TA generates encrypted host key and IFF key files and nonencrypted trusted certificate using the command

ntp-keygen -p server_password -T -I -i group,

where group_name is the group name used by all hosts in the group. Each client host generates encrypted host keys and nonencrypted, nontrusted certificate using the command

ntp-keygen -p client_passwd

Once these media have been generated, the TA can then generate the public parameters using the command

ntp-keygen -p local_passwd -e >parameters_file

where the -e option redirects the unencrypted client parameters to the standard output stream for a mail application or stored locally for later distribution. In a similar fashion the -q option redirects the encrypted server keys to the standard output stream using the command

ntp-keygen -p local_passwd -q remote_password -e >keys_file

For the simplest identity scheme TC, the server generates host keys, trusted certificate and identity files using an ntp-keygen program commadn with options specified in this section, while the clients use the same command with no options. The server uses the crypto command in the comnfiguration file with options specified in this section, while the clients use the same command with no options. Additonia client options are specified in the server command for each association.

It's best to start with a functioning TC configuation and add commands as necessary. For example, the CA generates an encrypted server keys file using the command

ntp-keygen -I -i group,

where group is the group name used by all hosts in the group. This and following commands can be combined in a single command. The nonencrypted client parameters can be exported using the command

ntp-keygen -e >file,

where the -e option redirects the client parameters to file via the standard output stream for a mail application or stored locally for later distribution. In a similar fashion the encrypted keys file can be exported using the command

ntp-keygen -q passw2 >file,

where passwd2 is the read password for another host. In either case the file is installed under the name found in the first line of the file, but converted to lower case and without the filestamp

As in the TC scheme, the server includes a crypto command in the configuration file with the ident group option. The crypto command in the client configuration file is unchanged, but the server command includes the ident group option.

In special circumstances the Autokey message digest algorithm can be changed using the digest option of the crypto command. The digest algorithm is separate and distinct from the symmetric -key message digest algorithm. If compliance with FIPS 140-2 is required, -the algorithm must be ether SHA or SHA1. The Autokey message digest algorithm must be the same for all participants in the NTP subnet (see next section). The message digest/digital signature scheme can be changed for each server separately using the -c option of the ntp_keygen program. This applies only for clients of that server, which select whatever scheme the server specifies.

It is important to note that certificates have a defined lifetime of one year from the time of creation. Sometime toward the end of the liftetime period, it is necessary to create a new certificate at both the server and client. For each server and client as root:

# ntp_keygen

The options are copied from the current certificate.

+ key message digest algorithm. If compliance with FIPS 140-2 is required, +the algorithm must be ether SHA or SHA1. The Autokey message digest algorithm must be the same for all participants in the NTP subnet.

Examples

Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. As shown ion the figure, RED TH mort and BLUE TH macabre run NTP symmetric mode with each other for monitoring or backup. For the purpose of illustration, assume both THs are primary servers. GREEN is typical of a large university providing certified time to the campus community. GREEN TH howland is a broadcast client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys. YELLOW is a client of GREEN and for purposes of illustration a TH for YELLOW.

The BLUE TH macabre uses configuration commands

crypto pw qqsv ident blue
- peer mort autokey
+ peer mort autokey ident red
broadcast address autokey

where qqsv is the password for macabre files and address is the broadcast address for the local LAN. It generates BLUE files using the commands

ntp-keygen -p qqsv -T -G -i blue
@@ -117,14 +104,14 @@ the algorithm must be ether SHA or SHA1. The Autokey message d

The first line generates the host, trusted certificate and private GQ server keys file. The second generates the public GQ client parameters file, which can have any nonconflicting mnemonic name.

The RED TH mort uses configuration commands

crypto pw xxx ident red
- peer macabre autokey
+ peer macabre autokey ident blue
broadcast address autokey

where xxx is the password for mort files. It generates RED files using the commands

ntp-keygen -p xxx -T -I -i red
ntp-keygen -p xxx -e >ntpkey_iffpar_red

The GREEN TH howland uses configuration commands

crypto pw yyy ident green
- broadcastclient

+ broadcastclient ident red blue

where yyy is the password for howland files. It generates GREEN files using the commands

ntp-keygen -p yyy -T -G -i green
ntp-keygen -p yyy -e >ntpkey_gqpar_green
@@ -133,8 +120,8 @@ the algorithm must be ether SHA or SHA1. The Autokey message d third line generates a copy of the private GREEN server file for use on another server in the same group, say YELLOW, but encrypted with the zzz password.

A client of GREEN, for example YELLOW, uses the configuration commands

crypto pw abc ident green
- server howland autokey

crypto pw abc
+ server howland autokey ident red

where abc is the password for its files. It generates files using the command

ntp-keygen -p abc

The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server keys file from the TH of that group, but it is encrypted and so must be sent using secure means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.

diff --git a/html/copyright.html b/html/copyright.html index 8975390e2..01673e091 100644 --- a/html/copyright.html +++ b/html/copyright.html @@ -7,92 +7,71 @@

Copyright Notice

"Clone me," says Dolly sheepishly. -

Last update: - 03-Sep-2010 21:20 - UTC
+ jpg "Clone me," says Dolly sheepishly. +

Last update: 03-Sep-2010 21:20 UTC

The following copyright notice applies to all files collectively called the Network Time Protocol Version 4 Distribution. Unless specifically declared otherwise in an individual file, this notice applies as if the text was explicitly included in the file.

-***********************************************************************
-*                                                                     *
-* Copyright (c) University of Delaware 1992-2010                      *
-*                                                                     *
-* Permission to use, copy, modify, and distribute this software and   *
-* its documentation for any purpose with or without fee is hereby     *
-* granted, provided that the above copyright notice appears in all    *
-* copies and that both the copyright notice and this permission       *
-* notice appear in supporting documentation, and that the name        *
-* University of Delaware not be used in advertising or publicity      *
-* pertaining to distribution of the software without specific,        *
-* written prior permission. The University of Delaware makes no       *
-* representations about the suitability this software for any         *
-* purpose. It is provided "as is" without express or implied          *
-* warranty.                                                           *
-*                                                                     *
-***********************************************************************
-

The following individuals contributed in part to the Network Time Protocol Distribution Version 4 and are acknowledged as authors of this work.

***********************************************************************  *                                                                     *  * Copyright (c) University of Delaware 1992-2010                      *  *                                                                     *  * Permission to use, copy, modify, and distribute this software and   *  * its documentation for any purpose with or without fee is hereby     *  * granted, provided that the above copyright notice appears in all    *  * copies and that both the copyright notice and this permission       *  * notice appear in supporting documentation, and that the name        *  * University of Delaware not be used in advertising or publicity      *  * pertaining to distribution of the software without specific,        *  * written prior permission. The University of Delaware makes no       *  * representations about the suitability this software for any         *  * purpose. It is provided "as is" without express or implied          *  * warranty.                                                           *  *                                                                     *  ***********************************************************************

The following individuals contributed in part to the Network Time Protocol Distribution Version 4 and are acknowledged as authors of this work.

Takao Abe <takao_abe@xurb.jp> Clock driver for JJY receivers
Mark Andrews <mark_andrews@isc.org> Leitch atomic clock controller
Bernd Altmeier <altmeier@atlsoft.de> hopf Elektronik serial line and PCI-bus devices
Viraj Bais <vbais@mailman1.intel.com> and Clayton Kirkwood <kirkwood@striderfm.intel.com> port to WindowsNT 3.5
Michael Barone <michael,barone@lmco.com> GPSVME fixes
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.
Marc Brett <Marc.Brett@westgeo.com> Magnavox GPS clock driver
Piete Brooks <Piete.Brooks@cl.cam.ac.uk> MSF clock driver, Trimble PARSE support
Nelson B Bolyard <nelson@bolyard.me> update and complete broadcast and crypto features in sntp
Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca> IPv6 support
Reg Clemens <reg@dwf.com> Oncore driver (Current maintainer)
Steve Clift <clift@ml.csiro.au> OMEGA clock driver
Casey Crellin <casey@csc.co.za> vxWorks (Tornado) port and help with target configuration
Sven Dietrich <sven_dietrich@trimble.com> Palisade reference clock driver, NT adj. residuals, integrated Greg's Winnt port.
John A. Dundas III <dundas@salt.jpl.nasa.gov> Apple A/UX port
Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de> Linux port
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
Dave Hart <davehart@davehart.com> General maintenance, Windows port interpolation rewrite
Claas Hilbrecht <neoclock4x@linum.com> NeoClock4X clock driver
Glenn Hollinger <glenn@herald.usask.ca> GOES clock driver
Mike Iglesias <iglesias@uci.edu> DEC Alpha port
Jim Jagielski <jim@jagubox.gsfc.nasa.gov> A/UX port
Jeff Johnson <jbj@chatham.usdesign.com> massive prototyping overhaul
Hans Lambermont <Hans.Lambermont@nl.origin-it.com> or <H.Lambermont@chello.nl> ntpsweep
Poul-Henning Kamp <phk@FreeBSD.ORG> Oncore driver (Original author)
Frank Kardel <kardel (at) ntp (dot) org> PARSE <GENERIC> (driver 14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup, dynamic interface handling
William L. Jones <jones@hermes.chpc.utexas.edu> RS/6000 AIX modifications, HPUX modifications
Dave Katz <dkatz@cisco.com> RS/6000 AIX port
Craig Leres <leres@ee.lbl.gov> 4.4BSD port, ppsclock, Magnavox GPS clock driver
George Lindholm <lindholm@ucs.ubc.ca> SunOS 5.1 port
Louis A. Mamakos <louie@ni.umd.edu> MD5-based authentication
Lars H. Mathiesen <thorinn@diku.dk> adaptation of foundation code for Version 3 as specified in RFC-1305
Danny Mayer <mayer@ntp.org>Network I/O, Windows Port, Code Maintenance
David L. Mills <mills@udel.edu> Version 4 foundation, precision kernel; clock drivers: 1, 3, 4, 6, 7, 11, 13, 18, 19, 22, 36
Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de> VMS port
Jeffrey Mogul <mogul@pa.dec.com> ntptrace utility
Tom Moore <tmoore@fievel.daytonoh.ncr.com> i386 svr4 port
Kamal A Mostafa <kamal@whence.com> SCO OpenServer port
Derek Mulcahy <derek@toybox.demon.co.uk> and Damon Hart-Davis <d@hd.org> ARCRON MSF clock driver
Rob Neal <neal@ntp.org> Bancomm refclock and config/parse code maintenance
Rainer Pruy <Rainer.Pruy@informatik.uni-erlangen.de> monitoring/trap scripts, statistics file handling
Dirce Richards <dirce@zk3.dec.com> Digital UNIX V4.0 port
Wilfredo Sánchez <wsanchez@apple.com> added support for NetInfo
Nick Sayer <mrapple@quack.kfu.com> SunOS streams modules
Jack Sasportas <jack@innovativeinternet.com> Saved a Lot of space on the stuff in the html/pic/ subdirectory
Ray Schnitzler <schnitz@unipress.com> Unixware1 port
Michael Shields <shields@tembel.org> USNO clock driver
Jeff Steinman <jss@pebbles.jpl.nasa.gov> Datum PTS clock driver
Harlan Stenn <harlan@pfcs.com> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)
Kenneth Stone <ken@sdd.hp.com> HP-UX port
Ajit Thyagarajan <ajit@ee.udel.edu>IP multicast/anycast support
Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp>TRAK clock driver
Paul A Vixie <vixie@vix.com> TrueTime GPS driver, generic TrueTime clock driver
Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de> corrected and validated HTML documents according to the HTML DTD
Takao Abe <takao_abe@xurb.jp> Clock driver for JJY receivers
Mark Andrews <mark_andrews@isc.org> Leitch atomic clock controller
Bernd Altmeier <altmeier@atlsoft.de> hopf Elektronik serial line and PCI-bus devices
Viraj Bais <vbais@mailman1.intel.com> and Clayton Kirkwood <kirkwood@striderfm.intel.com> port to WindowsNT 3.5
Michael Barone <michael,barone@lmco.com> GPSVME fixes
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.
Marc Brett <Marc.Brett@westgeo.com> Magnavox GPS clock driver
Piete Brooks <Piete.Brooks@cl.cam.ac.uk> MSF clock driver, Trimble PARSE support
Nelson B Bolyard <nelson@bolyard.me> update and complete broadcast and crypto features in sntp
Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca> IPv6 support
Reg Clemens <reg@dwf.com> Oncore driver (Current maintainer)
Steve Clift <clift@ml.csiro.au> OMEGA clock driver
Casey Crellin <casey@csc.co.za> vxWorks (Tornado) port and help with target configuration
Sven Dietrich <sven_dietrich@trimble.com> Palisade reference clock driver, NT adj. residuals, integrated Greg's Winnt port.
John A. Dundas III <dundas@salt.jpl.nasa.gov> Apple A/UX port
Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de> Linux port
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
Dave Hart <davehart@davehart.com> General maintenance, Windows port interpolation rewrite
Claas Hilbrecht <neoclock4x@linum.com> NeoClock4X clock driver
Glenn Hollinger <glenn@herald.usask.ca> GOES clock driver
Mike Iglesias <iglesias@uci.edu> DEC Alpha port
Jim Jagielski <jim@jagubox.gsfc.nasa.gov> A/UX port
Jeff Johnson <jbj@chatham.usdesign.com> massive prototyping overhaul
Hans Lambermont <Hans.Lambermont@nl.origin-it.com> or <H.Lambermont@chello.nl> ntpsweep
Poul-Henning Kamp <phk@FreeBSD.ORG> Oncore driver (Original author)
Frank Kardel <kardel (at) ntp (dot) org> PARSE <GENERIC> (driver 14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup, dynamic interface handling
William L. Jones <jones@hermes.chpc.utexas.edu> RS/6000 AIX modifications, HPUX modifications
Dave Katz <dkatz@cisco.com> RS/6000 AIX port
Craig Leres <leres@ee.lbl.gov> 4.4BSD port, ppsclock, Magnavox GPS clock driver
George Lindholm <lindholm@ucs.ubc.ca> SunOS 5.1 port
Louis A. Mamakos <louie@ni.umd.edu> MD5-based authentication
Lars H. Mathiesen <thorinn@diku.dk> adaptation of foundation code for Version 3 as specified in RFC-1305
Danny Mayer <mayer@ntp.org>Network I/O, Windows Port, Code Maintenance
David L. Mills <mills@udel.edu> Version 4 foundation, precision kernel; clock drivers: 1, 3, 4, 6, 7, 11, 13, 18, 19, 22, 36
Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de> VMS port
Jeffrey Mogul <mogul@pa.dec.com> ntptrace utility
Tom Moore <tmoore@fievel.daytonoh.ncr.com> i386 svr4 port
Kamal A Mostafa <kamal@whence.com> SCO OpenServer port
Derek Mulcahy <derek@toybox.demon.co.uk> and Damon Hart-Davis <d@hd.org> ARCRON MSF clock driver
Rob Neal <neal@ntp.org> Bancomm refclock and config/parse code maintenance
Rainer Pruy <Rainer.Pruy@informatik.uni-erlangen.de> monitoring/trap scripts, statistics file handling
Dirce Richards <dirce@zk3.dec.com> Digital UNIX V4.0 port
Wilfredo Sánchez <wsanchez@apple.com> added support for NetInfo
Nick Sayer <mrapple@quack.kfu.com> SunOS streams modules
Jack Sasportas <jack@innovativeinternet.com> Saved a Lot of space on the stuff in the html/pic/ subdirectory
Ray Schnitzler <schnitz@unipress.com> Unixware1 port
Michael Shields <shields@tembel.org> USNO clock driver
Jeff Steinman <jss@pebbles.jpl.nasa.gov> Datum PTS clock driver
Harlan Stenn <harlan@pfcs.com> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)
Kenneth Stone <ken@sdd.hp.com> HP-UX port
Ajit Thyagarajan <ajit@ee.udel.edu>IP multicast/anycast support
Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp>TRAK clock driver
Paul A Vixie <vixie@vix.com> TrueTime GPS driver, generic TrueTime clock driver
Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de> corrected and validated HTML documents according to the HTML DTD

- diff --git a/html/drivers/driver8.html b/html/drivers/driver8.html index b4c34f375..6d7403398 100644 --- a/html/drivers/driver8.html +++ b/html/drivers/driver8.html @@ -9,283 +9,249 @@ -

Generic Reference Driver

Synopsis

- Address: 127.127.8.u
- Reference ID: PARSE
- Driver ID: GENERIC
- Serial Port: /dev/refclock-u; TTY mode according to clock type
- PPS device: /dev/refclockpps-u; alternate PPS device (if not available via the serial port) -

Description

- The PARSE driver supports 20 different clock types/configurations. PARSE is actually a multi-clock driver.
-
-

The actual receiver status is mapped into various synchronization states generally used by receivers. The driver is configured to interpret the time codes of Meinberg DCF77 AM receivers, DCF77 FM receivers, Meinberg GPS16x/17x receivers, Trimble SV6 GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see list below).

The reference clock support in NTP contains the necessary configuration tables for those receivers. In addition to supporting several different clock types and up to 4 devices, the processing of a PPS signal is also provided as a configuration option. The PPS configuration option uses the receiver-generated time stamps for feeding the PPS loopfilter control for much finer clock synchronization.

CAUTION: The PPS configuration option is different from the hardware PPS signal, which is also supported (see below), as it controls the way ntpd is synchronized to the reference clock, while the hardware PPS signal controls the way time offsets are determined.

The use of the PPS option requires receivers with an accuracy of better than 1ms.

Timecode variables listed by ntpq (8)

The ntpq program can read and display several clock variables. These hold the following information:

refclock_format: A qualification of the decoded time code format.
refclock_states: The overall running time and the accumulated times for the clock event states.
refclock_status: Lists the currently active receiver flags. Additional feature flags for the receiver are optionally listed in parentheses.
refclock_time: The local time with the offset to UTC (format HHMM).
timecode: The actual time code.

If PPS information is present, additional variables are available:

refclock_ppsskew: The difference between the RS-232-derived timestamp and the PPS timestamp.
refclock_ppstime: The PPS timestamp.

Supported Devices

Currently, nineteen clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported by the PARSE driver.
- A note on the implementations:

These implementations were mainly done without actual access to the hardware, thus not all implementations provide full support. The development was done with the help of many kind souls who had the hardware and kindly lent me their time and patience during the development and debugging cycle. Thus for continued support and quality, direct access to the receivers is a big help. Nevertheless I am not prepared to buy these reference clocks - donations to (kardel <AT> ntp.org) are welcome as long as they work within Europe 8-). -
Verified implementations are:
-
- RAWDCF variants -
  These variants have been tested for correct decoding with my own homegrown receivers. Interfacing with specific commercial products may involve some fiddling with cables. In particular, commercial RAWDCF receivers have a seemingly unlimited number of ways to draw power from the RS-232 port and to encode the DCF77 datastream. You are mainly on your own here unless I have a sample of the receiver.
  -
- Meinberg clocks -
  These implementations have been verified by the Meinberg people themselves and I have access to one of these clocks.
  -
-

The pictures below have been taken from and are linked to the vendors' web pages.

- -

server 127.127.8.0-3 mode 0 -
Meinberg PZF5xx receiver family (FM demodulation/TCXO / 50μs)
-
- -
server 127.127.8.0-3 mode 1 -
Meinberg PZF5xx receiver family (FM demodulation/OCXO / 50μs)
-
-
- -
server 127.127.8.0-3 mode 2 -
Meinberg DCF C51 receiver and similar (AM demodulation / 4ms)
-
-
-
This mode expects the Meinberg standard time string format with 9600/7E2.
-
Note: mode 2 must also be used for Meinberg PCI cards under Linux, e.g. the GPS PCI card or the DCF77 PCI card. Please note the Meinberg Linux driver must be installed. That driver emulates a refclock device in order to allow ntpd to access those cards. For details, please refer to the README file that comes with the Meinberg driver package.
-
- -
server 127.127.8.0-3 mode 3 -
ELV DCF7000 (sloppy AM demodulation / 50ms)
-
- -
server 127.127.8.0-3 mode 4 -
Walter Schmid DCF receiver Kit (AM demodulation / 1ms)
-
- -
server 127.127.8.0-3 mode 5 -
RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)
-
- -
server 127.127.8.0-3 mode 6 -
RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)
-
- -
server 127.127.8.0-3 mode 7 -
Meinberg GPS16x/GPS17x receivers (GPS / <<1μs)
-
-
-
This mode expects either the University of Erlangen time string format or the Meinberg standard time string format at 19200/8N1.
-
The University of Erlangen format is preferred. Newer Meinberg GPS receivers can be configured to transmit that format; for older devices, a special firmware version may be available.
-
In this mode some additional GPS receiver status information is also read. However, this requires a point-to-point connection. Mode 18 should be used if the device is accessed by a multidrop connection.
-
Note: mode 7 must not be used with Meinberg PCI cards; use mode 2 instead.
-
- -
server 127.127.8.0-3 mode 8 -
IGEL clock
-
-
- -
server 127.127.8.0-3 mode 9 -
Trimble SVeeSix GPS receiver TAIP protocol (GPS / <<1μs)
-
- -
server 127.127.8.0-3 mode 10 -
Trimble SVeeSix GPS receiver TSIP protocol (GPS / <<1μs) (no kernel support yet)
-
-
-
- -
server 127.127.8.0-3 mode 11 -
Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master Clock support
-
- -
server 127.127.8.0-3 mode 12 -
HOPF Funkuhr 6021
-
-
- -
server 127.127.8.0-3 mode 13 -
Diem's Computime Radio Clock
-
- -
server 127.127.8.0-3 mode 14 -
RAWDCF receiver (DTR=high/RTS=low)
-
- -
server 127.127.8.0-3 mode 15 -
WHARTON 400A Series Clocks with a 404.2 Serial Interface
-
- -
server 127.127.8.0-3 mode 16 -
RAWDCF receiver (DTR=low/RTS=high)
-
- -
server 127.127.8.0-3 mode 17 -
VARITEXT Receiver (MSF)
-
- -
server 127.127.8.0-3 mode 18 -
Meinberg GPS16x/GPS17x receivers (GPS / <<1μs)
-
-
This mode works without additional data communication (version, GPS status etc.) and thus should be used with multidrop, heterogeneous multiclient operation.
-
Note: mode 18 must not be used with Meinberg PCI cards, use mode 2 instead.
-
-
server 127.127.8.0-3 mode 19 -
Gude Analog- und Digitalsystem GmbH 'Expert mouseCLOCK USB v2.0'
-
- -
server 127.127.8.0-3 mode 20 -
RAWDCF receiver similar to mode 14, but operating @ 75 baud (DTR=high/RTS=low)
-
-
Driving the DCF clocks at 75 baud may help to get them to work with a bunch of common USB serial converters, that do 75 but cannot do 50 baud at all, e.g. those based on Prolific PL2303. -
- -
server 127.127.8.0-3 mode 21 -
RAWDCF receiver similar to mode 16, but operating @ 75 baud (DTR=low/RTS=high)
-
-
See comment from mode 20 clock. -
- -

Actual data formats and setup requirements of the various clocks can be found in NTP PARSE clock data formats.

Operation

The reference clock support software carefully monitors the state transitions of the receiver. All state changes and exceptional events (such as loss of time code transmission) are logged via the syslog facility. Every hour a summary of the accumulated times for the clock states is listed via syslog.

PPS support is only available when the receiver is completely synchronized. The receiver is believed to deliver correct time for an additional period of time after losing synchronization, unless a disruption in time code transmission is detected (possible power loss). The trust period is dependent on the receiver oscillator and thus is a function of clock type.

Raw DCF77 pulses can be fed via a level converter to the RXD pin of an RS-232 serial port (pin 3 of a 25-pin connector or pin 2 of a 9-pin connector). The telegrams are decoded and used for synchronization. DCF77 AM receivers can be bought for as little as $25. The accuracy is dependent on the receiver and is somewhere between 2ms (expensive) and 10ms (cheap). Synchronization ceases when reception of the DCF77 signal deteriorates, since no backup oscillator is available as usually found in other reference clock receivers. So it is important to have a good place for the DCF77 antenna. During transmitter shutdowns you are out of luck unless you have other NTP servers with alternate time sources available.

In addition to the PPS loopfilter control, a true PPS hardware signal can be utilized via the PPSAPI interface. PPS pulses are usually fed via a level converter to the DCD pin of an RS-232 serial port (pin 8 of a 25-pin connector or pin 1 of a 9-pin connector). To select PPS support, the mode parameter is the mode value as above plus 128. If 128 is not added to the mode value, PPS will be detected to be available but will not be used. -

Hardware PPS support
-

For PPS to be used, add 128 to the mode parameter.

If the PPS signal is fed in from a device different from the device providing the serial communication (/dev/refclock-{0..3}), this device is configured as /dev/refclockpps-{0..3}. This allows the PPS information to be fed in e.g. via the parallel port (if supported by the underlying operation system) and the date/time telegrams to be handled via the serial port.

Monitor Data

Clock state statistics are written hourly to the syslog service. Online information can be found by examining the clock variables via the ntpq cv command.
- Some devices have quite extensive additional information (GPS16x/GPS17x, Trimble). The driver reads out much of the internal GPS data - and makes it accessible via clock variables. To find out about additional variable names, query for the clock_var_list variable on - a specific clock association as shown below. -

First let ntpq display the table of associations:

-  ntpq> as
-  ind assID status  conf reach auth condition  last_event cnt
-  ===========================================================
-    1 19556  9154   yes   yes  none falsetick   reachable  5
-    2 19557  9435   yes   yes  none  candidat  clock expt  3
-    3 19558  9714   yes   yes  none  pps.peer   reachable  1
-

Then switch to raw output. This may be required because of display limitations in ntpq/ntpd - so large lists need to be retrieved in several queries.

-  ntpq> raw
-  Output set to raw
-

Use the cv command to read the list of clock variables of a selected association:

-  ntpq> cv 19557 clock_var_list
-

The long output of the command above looks similar to:

-  assID=19557 status=0x0000,
-  clock_var_list="type,timecode,poll,noreply,badformat,baddata,fudgetime1,
-  fudgetime2,stratum,refid,flags,device,clock_var_list,refclock_time,refclock_status,
-  refclock_format,refclock_states,refclock_id,refclock_iomode,refclock_driver_version,
-  meinberg_gps_status,gps_utc_correction,gps_message,meinberg_antenna_status,gps_tot_51,
-  gps_tot_63,gps_t0a,gps_cfg[1],gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],
-  gps_health[3],gps_cfg[4],gps_health[4],gps_cfg[5]"
-

Then use the cv command again to list selected clock variables. The following command must be entered as a single line:

-  ntpq> cv 19557 refclock_status,refclock_format,refclock_states,refclock_id,
-  refclock_iomode,refclock_driver_version,meinberg_gps_status,gps_utc_correction,
-  gps_message,meinberg_antenna_status,gps_tot_51,gps_tot_63,gps_t0a,gps_cfg[1],
-  gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],gps_health[3],gps_cfg[4],
-  gps_health[4],gps_cfg[5]
-

The output of the command above is wrapped around depending on the screen width and looks similar to:

-  status=0x0003,
-  refclock_status="UTC DISPLAY; TIME CODE; PPS; POSITION; (LEAP INDICATION;
-  PPS SIGNAL; POSITION)",
-  refclock_format="Meinberg GPS Extended",
-  refclock_states="*NOMINAL: 21:21:36 (99.99%); FAULT: 00:00:03 (0.00%);
-  running time: 21:21:39",
-  refclock_id="GPS", refclock_iomode="normal",
-  refclock_driver_version="refclock_parse.c,v 4.77 2006/08/05 07:44:49
-  kardel RELEASE_20060805_A",
-  meinberg_gps_status="[0x0000] <OK>",
-  gps_utc_correction="current correction 14 sec, last correction
-  on c7619a00.00000000  Sun, Jan  1 2006  0:00:00.000",
-  gps_message="/PFU3SOP-4WG14EPU0V1KA",
-  meinberg_antenna_status="RECONNECTED on 2006-07-18 08:13:20.0000000 (+0000)
-  UTC CORR, LOCAL TIME, reconnect clockoffset +0.0000000 s,
-  disconnect time 0000-00-00 00:00:00.0000000 (+0000) ",
-  gps_tot_51="week 1400 + 3 days + 42300.0000000 sec",
-  gps_tot_63="week 1400 + 3 days + 42294.0000000 sec",
-  gps_t0a="week 1400 + 5 days + 71808.0000000 sec",
-  gps_cfg[1]="[0x9] BLOCK II", gps_health[1]="[0x0] OK;SIGNAL OK",
-  gps_cfg[2]="[0x0] BLOCK I", gps_health[2]="[0x3f] PARITY;MULTIPLE ERRS",
-  gps_cfg[3]="[0x9] BLOCK II", gps_health[3]="[0x0] OK;SIGNAL OK",
-  gps_cfg[4]="[0x9] BLOCK II", gps_health[6]="[0x0] OK;SIGNAL OK",
-  gps_cfg[5]="[0x9] BLOCK II"
-

Fudge Factors

time1 time -: Specifies the time offset calibration factor, in seconds and fraction. The default value depends on the clock type. -
time2 time -: - If flag1 is 0, time2 specifies the offset of the PPS signal from the actual time (PPS fine tuning). -; - If flag1 is 1, time2 specifies the number of seconds a receiver with a premium local oscillator can be trusted after losing synchronisation. -
stratum stratum -: The stratum for this reference clock. -
refid refid -: The refid for this reference clock. -

flag1 { 0 | 1 } -: If 0, the fudge factor time2 refers to the PPS offset. -; If 1, time2 refers to the TRUST TIME. -
flag2 { 0 | 1 } -: If flag2 is 1, sample PPS on CLEAR instead of on ASSERT. -
flag3 { 0 | 1 } -: If flag3 is 1, link kernel PPS tracking to this refclock instance. -
flag4 { 0 | 1 } -: Delete next leap second instead of adding it. (You'll need to wait a bit for that to happen 8-) -

- Note about auxiliary Sun STREAMS modules (SunOS and Solaris):
-

The timecode of these receivers can be sampled via a STREAMS module in the kernel. (The STREAMS module has been designed for use with Sun systems under SunOS 4.1.x or Solaris 2.3 - 2.8. It can be linked directly into the kernel or loaded via the loadable driver mechanism.) This STREAMS module can be adapted to convert different time code formats. Nowadays the PPSAPI mechanism is usually used. -

Making your own PARSE clocks

The parse clock mechanism deviates from the way other NTP reference clocks work. For a short description of how to build parse reference clocks, see making PARSE clocks.

Additional Information

Reference Clock Drivers

- - +

Generic Reference Driver

Synopsis

+ Address: 127.127.8.u
+Reference ID: PARSE
+Driver ID: GENERIC
+Serial Port: /dev/refclock-u; TTY mode according to clock type
+PPS device: /dev/refclockpps-u; alternate PPS device (if not available via the serial port) +

Description

+The PARSE driver supports 20 different clock types/configurations. PARSE is actually a multi-clock driver.
+
+

The use of the PPS option requires receivers with an accuracy of better than 1ms.

Timecode variables listed by ntpq (8)

The ntpq program can read and display several clock variables. These hold the following information:

refclock_format: A qualification of the decoded time code format.
refclock_states: The overall running time and the accumulated times for the clock event states.
refclock_status: Lists the currently active receiver flags. Additional feature flags for the receiver are optionally listed in parentheses.
refclock_time: The local time with the offset to UTC (format HHMM).
timecode: The actual time code.

If PPS information is present, additional variables are available:

refclock_ppsskew: The difference between the RS-232-derived timestamp and the PPS timestamp.
refclock_ppstime: The PPS timestamp.

Supported Devices

Currently, nineteen clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported by the PARSE driver.
+ A note on the implementations:

These implementations were mainly done without actual access to the hardware, thus not all implementations provide full support. The development was done with the help of many kind souls who had the hardware and kindly lent me their time and patience during the development and debugging cycle. Thus for continued support and quality, direct access to the receivers is a big help. Nevertheless I am not prepared to buy these reference clocks - donations to (kardel <AT> ntp.org) are welcome as long as they work within Europe 8-). +
Verified implementations are:
+
- RAWDCF variants +
  These variants have been tested for correct decoding with my own homegrown receivers. Interfacing with specific commercial products may involve some fiddling with cables. In particular, commercial RAWDCF receivers have a seemingly unlimited number of ways to draw power from the RS-232 port and to encode the DCF77 datastream. You are mainly on your own here unless I have a sample of the receiver.
  +
- Meinberg clocks +
  These implementations have been verified by the Meinberg people themselves and I have access to one of these clocks.
  +
+

The pictures below have been taken from and are linked to the vendors' web pages.

+ +

server 127.127.8.0-3 mode 0 +
Meinberg PZF5xx receiver family (FM demodulation/TCXO / 50μs)
+
+
+
server 127.127.8.0-3 mode 1 +
Meinberg PZF5xx receiver family (FM demodulation/OCXO / 50μs)
+
+
+
+
server 127.127.8.0-3 mode 2 +
Meinberg DCF C51 receiver and similar (AM demodulation / 4ms)
+
+
+
This mode expects the Meinberg standard time string format with 9600/7E2.
+
Note: mode 2 must also be used for Meinberg PCI cards under Linux, e.g. the GPS PCI card or the DCF77 PCI card. Please note the Meinberg Linux driver must be installed. That driver emulates a refclock device in order to allow ntpd to access those cards. For details, please refer to the README file that comes with the Meinberg driver package.
+
+
+
server 127.127.8.0-3 mode 3 +
ELV DCF7000 (sloppy AM demodulation / 50ms)
+
+
+
server 127.127.8.0-3 mode 4 +
Walter Schmid DCF receiver Kit (AM demodulation / 1ms)
+
+
+
server 127.127.8.0-3 mode 5 +
RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)
+
+
+
server 127.127.8.0-3 mode 6 +
RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)
+
+
+
server 127.127.8.0-3 mode 7 +
Meinberg GPS16x/GPS17x receivers (GPS / <<1μs)
+
+
+
This mode expects either the University of Erlangen time string format or the Meinberg standard time string format at 19200/8N1.
+
The University of Erlangen format is preferred. Newer Meinberg GPS receivers can be configured to transmit that format; for older devices, a special firmware version may be available.
+
In this mode some additional GPS receiver status information is also read. However, this requires a point-to-point connection. Mode 18 should be used if the device is accessed by a multidrop connection.
+
Note: mode 7 must not be used with Meinberg PCI cards; use mode 2 instead.
+
+
+
server 127.127.8.0-3 mode 8 +
IGEL clock
+
+
+
+
server 127.127.8.0-3 mode 9 +
Trimble SVeeSix GPS receiver TAIP protocol (GPS / <<1μs)
+
+
+
server 127.127.8.0-3 mode 10 +
Trimble SVeeSix GPS receiver TSIP protocol (GPS / <<1μs) (no kernel support yet)
+
+
+
+
+
server 127.127.8.0-3 mode 11 +
Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master Clock support
+
+
+
server 127.127.8.0-3 mode 12 +
HOPF Funkuhr 6021
+
+
+
+
server 127.127.8.0-3 mode 13 +
Diem's Computime Radio Clock
+
+
+
server 127.127.8.0-3 mode 14 +
RAWDCF receiver (DTR=high/RTS=low)
+
+
+
server 127.127.8.0-3 mode 15 +
WHARTON 400A Series Clocks with a 404.2 Serial Interface
+
+
+
server 127.127.8.0-3 mode 16 +
RAWDCF receiver (DTR=low/RTS=high)
+
+
+
server 127.127.8.0-3 mode 17 +
VARITEXT Receiver (MSF)
+
+
+
server 127.127.8.0-3 mode 18 +
Meinberg GPS16x/GPS17x receivers (GPS / <<1μs)
+
+
This mode works without additional data communication (version, GPS status etc.) and thus should be used with multidrop, heterogeneous multiclient operation.
+
Note: mode 18 must not be used with Meinberg PCI cards, use mode 2 instead.
+
+
+
server 127.127.8.0-3 mode 19 +
Gude Analog- und Digitalsystem GmbH 'Expert mouseCLOCK USB v2.0'
+
+
+
server 127.127.8.0-3 mode 20 +
RAWDCF receiver similar to mode 14, but operating @ 75 baud (DTR=high/RTS=low)
+
+
Driving the DCF clocks at 75 baud may help to get them to work with a bunch of common USB serial converters, that do 75 but cannot do 50 baud at all, e.g. those based on Prolific PL2303.
+
+
server 127.127.8.0-3 mode 21 +
RAWDCF receiver similar to mode 16, but operating @ 75 baud (DTR=low/RTS=high)
+
+
See comment from mode 20 clock.
+
+

Actual data formats and setup requirements of the various clocks can be found in NTP PARSE clock data formats.

Operation

Hardware PPS support
+

For PPS to be used, add 128 to the mode parameter.

Monitor Data

Clock state statistics are written hourly to the syslog service. Online information can be found by examining the clock variables via the ntpq cv command.
+ Some devices have quite extensive additional information (GPS16x/GPS17x, Trimble). The driver reads out much of the internal GPS data and makes it accessible via clock variables. To find out about additional variable names, query for the clock_var_list variable on a specific clock association as shown below.

First let ntpq display the table of associations:

  ntpq> as    ind assID status  conf reach auth condition  last_event cnt    ===========================================================      1 19556  9154   yes   yes  none falsetick   reachable  5      2 19557  9435   yes   yes  none  candidat  clock expt  3      3 19558  9714   yes   yes  none  pps.peer   reachable  1

Then switch to raw output. This may be required because of display limitations in ntpq/ntpd - so large lists need to be retrieved in several queries.

  ntpq> raw    Output set to raw

Use the cv command to read the list of clock variables of a selected association:

  ntpq> cv 19557 clock_var_list

The long output of the command above looks similar to:

  assID=19557 status=0x0000,    clock_var_list="type,timecode,poll,noreply,badformat,baddata,fudgetime1,    fudgetime2,stratum,refid,flags,device,clock_var_list,refclock_time,refclock_status,    refclock_format,refclock_states,refclock_id,refclock_iomode,refclock_driver_version,    meinberg_gps_status,gps_utc_correction,gps_message,meinberg_antenna_status,gps_tot_51,    gps_tot_63,gps_t0a,gps_cfg[1],gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],    gps_health[3],gps_cfg[4],gps_health[4],gps_cfg[5]"

Then use the cv command again to list selected clock variables. The following command must be entered as a single line:

  ntpq> cv 19557 refclock_status,refclock_format,refclock_states,refclock_id,    refclock_iomode,refclock_driver_version,meinberg_gps_status,gps_utc_correction,    gps_message,meinberg_antenna_status,gps_tot_51,gps_tot_63,gps_t0a,gps_cfg[1],    gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],gps_health[3],gps_cfg[4],    gps_health[4],gps_cfg[5]

The output of the command above is wrapped around depending on the screen width and looks similar to:

  status=0x0003,    refclock_status="UTC DISPLAY; TIME CODE; PPS; POSITION; (LEAP INDICATION;    PPS SIGNAL; POSITION)",    refclock_format="Meinberg GPS Extended",    refclock_states="*NOMINAL: 21:21:36 (99.99%); FAULT: 00:00:03 (0.00%);    running time: 21:21:39",    refclock_id="GPS", refclock_iomode="normal",    refclock_driver_version="refclock_parse.c,v 4.77 2006/08/05 07:44:49    kardel RELEASE_20060805_A",    meinberg_gps_status="[0x0000] <OK>",    gps_utc_correction="current correction 14 sec, last correction    on c7619a00.00000000  Sun, Jan  1 2006  0:00:00.000",    gps_message="/PFU3SOP-4WG14EPU0V1KA",    meinberg_antenna_status="RECONNECTED on 2006-07-18 08:13:20.0000000 (+0000)    UTC CORR, LOCAL TIME, reconnect clockoffset +0.0000000 s,    disconnect time 0000-00-00 00:00:00.0000000 (+0000) ",    gps_tot_51="week 1400 + 3 days + 42300.0000000 sec",    gps_tot_63="week 1400 + 3 days + 42294.0000000 sec",    gps_t0a="week 1400 + 5 days + 71808.0000000 sec",    gps_cfg[1]="[0x9] BLOCK II", gps_health[1]="[0x0] OK;SIGNAL OK",    gps_cfg[2]="[0x0] BLOCK I", gps_health[2]="[0x3f] PARITY;MULTIPLE ERRS",    gps_cfg[3]="[0x9] BLOCK II", gps_health[3]="[0x0] OK;SIGNAL OK",    gps_cfg[4]="[0x9] BLOCK II", gps_health[6]="[0x0] OK;SIGNAL OK",    gps_cfg[5]="[0x9] BLOCK II"

Fudge Factors

time1 time: Specifies the time offset calibration factor, in seconds and fraction. The default value depends on the clock type.
time2 time: If flag1 is 0, time2 specifies the offset of the PPS signal from the actual time (PPS fine tuning).; If flag1 is 1, time2 specifies the number of seconds a receiver with a premium local oscillator can be trusted after losing synchronisation.
stratum stratum: The stratum for this reference clock.
refid refid: The refid for this reference clock.

flag1 { 0 | 1 }: If 0, the fudge factor time2 refers to the PPS offset.; If 1, time2 refers to the TRUST TIME.
flag2 { 0 | 1 }: If flag2 is 1, sample PPS on CLEAR instead of on ASSERT.
flag3 { 0 | 1 }: If flag3 is 1, link kernel PPS tracking to this refclock instance.
flag4 { 0 | 1 }: Delete next leap second instead of adding it. (You'll need to wait a bit for that to happen 8-)

+Note about auxiliary Sun STREAMS modules (SunOS and Solaris):
+

The timecode of these receivers can be sampled via a STREAMS module in the kernel. (The STREAMS module has been designed for use with Sun systems under SunOS 4.1.x or Solaris 2.3 - 2.8. It can be linked directly into the kernel or loaded via the loadable driver mechanism.) This STREAMS module can be adapted to convert different time code formats. Nowadays the PPSAPI mechanism is usually used.

Making your own PARSE clocks

The parse clock mechanism deviates from the way other NTP reference clocks work. For a short description of how to build parse reference clocks, see making PARSE clocks.

Additional Information

Reference Clock Drivers

+ diff --git a/html/keygen.html b/html/keygen.html index d58100cf1..d7f7d2e47 100644 --- a/html/keygen.html +++ b/html/keygen.html @@ -16,7 +16,7 @@

gif from Alice's Adventures in Wonderland, Lewis Carroll

Alice holds the key.

Last update: - 13-Dec-2010 5:07 + 14-Dec-2010 5:00

Description

This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It can generate message digest keys used in symmetric key cryptography and, if the OpenSSL software library has been installed, it can generate host keys, sign keys, certificates and identity keys used by the Autokey public key cryptography. The message digest keys file is generated in a format compatible with NTPv3. All other files are in PEM-encoded printable ASCII format so they can be embedded as MIME attachments in mail to other sites.

This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It can generate message digest keys used in symmetric key cryptography and, if the OpenSSL software library has been installed, it can generate host keys, sign keys, certificates, and identity keys and parameters used by the Autokey public key cryptography. The message digest keys file is generated in a format compatible with NTPv3. All other files are in PEM-encoded printable ASCII format so they can be embedded as MIME attachments in mail to other sites.

When used to generate message digest keys, the program produces a file containing - ten pseudo-random printable ASCII strings suitable for the MD5 message digest algorithm included in the distribution. If the OpenSSL library is installed, it produces an additional ten hex-encoded random bit strings suitable for the SHA1 and other message digest algorithms.

Message digest keys are specified in a keys file which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, additional keys can be defined as passwords for the ntpq and ntpdc utility programs.

+ ten pseudo-random printable ASCII strings suitable for the MD5 message digest algorithm included in the distribution. If the OpenSSL library is installed, it produces an additional ten hex-encoded random bit strings suitable for the SHA1 and other message digest algorithms. The message digest keys file must be distributed and stored using secure means beyond the scope of NTP itself. Besides the keys used for ordinary NTP associations, additional keys can be defined as passwords for the ntpq and ntpdc utility programs.

The remaining generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates generated by this program are compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity keys are probably not compatible with anything other than Autokey.

Some files used by this program are encrypted using a private password. The -p option specifies the password for local files and the -q option the password for encrypted files sent to remote sites. If no password is specified, the host name returned by the Unix gethostname() function, normally the DNS name of the host, is used.

The pw option of the crypto configuration command specifies the read password for previously encrypted files. This must match the local password used by this program. If not specified, the host name is used. Thus, if files are generated by this program without password, they can be read back by ntpd without password, but only on the same host.

Normally, encrypted files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page. The symmetric keys file, normally called ntp.keys, is usually installed in /etc. Other files and links are usually installed in /usr/local/etc, which is normally in a shared filesystem in NFS-mounted networks and cannot be changed by shared clients. The location of the keys directory can be changed by the keysdir configuration command in such cases.

Some files used by this program are encrypted using a private password. The -p option specifies the password for local encrypted files and the -q option the password for encrypted files sent to remote sites. If no password is specified, the host name returned by the Unix gethostname() function, normally the DNS name of the host, is used.

The pw option of the crypto configuration command specifies the read password for previously encrypted local files. This must match the local password used by this program. If not specified, the host name is used. Thus, if files are generated by this program without password, they can be read back by ntpd without password, but only on the same host.

This program directs commentary and error messages to the standard error stream stderr and remote files to the standard output stream stdout where they can be piped to other applications or redirected to files. The names used for generated files and links all begin with the string ntpkey and include the file type, generating host and filestamp, as described in the Cryptographic Data Files section below

Running the Program

To test and gain experience with Autokey concepts, log in as root and change to the keys directory, usually /usr/local/etc. When run for the first time, or if all files with names beginning ntpkey have been removed, use the ntp-keygen command without arguments to generate a default RSA host key and matching RSA-MD5 certificate with expiration date one year hence. If run again, the program uses the existing keys and parameters and generates only a new certificate with new expiration date one year hence.

To test and gain experience with Autokey concepts, log in as root and change to the keys directory, usually /usr/local/etc. When run for the first time, or if all files with names beginning ntpkey have been removed, use the ntp-keygen command without arguments to generate a default RSA host key and matching RSA-MD5 certificate with expiration date one year hence. If run again without options, the program uses the existing keys and parameters and generates only a new certificate with new expiration date one year hence.

Run the command on as many hosts as necessary. Designate one of them as the trusted host (TH) using ntp-keygen with the -T option and configure it to synchronize from reliable Internet servers. Then configure the other hosts to synchronize to the TH directly or indirectly. A certificate trail is created when Autokey asks the immediately ascendant host towards the TH to sign its certificate, which is then provided to the immediately descendant host on request. All group hosts should have acyclic certificate trails ending on the TH.

The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. A different sign key can be assigned using the -S option and this can be either RSA or DSA type. By default, the signature message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified using the -c option.

The rules say cryptographic media should be generated with proventic filestamps, which means the host should already be synchronized before this program is run. This of course creates a fowl problem when the host is started for the first time. Accordingly, the host time should be set by some other means, such as eyeball-and-wristwatch, at lest so that the certificate lifetime is within the current year. After that and when the host is synchronized to a proventic source, the certificate should be re-generated.

The rules say cryptographic media should be generated with proventic filestamps, which means the host should already be synchronized before this program is run. This of course creates a chicken-and-egg problem when the host is started for the first time. Accordingly, the host time should be set by some other means, such as eyeball-and-wristwatch, at least so that the certificate lifetime is within the current year. After that and when the host is synchronized to a proventic source, the certificate should be re-generated.

Additional information on trusted groups and identity schemes is on the Autokey Public-Key Authentication page.

Command Line Options

-T: Generate a trusted certificate. By default, the program generates nontrusted certificates.
-V nkeys: Generate server parameters keys for the Mu-Varadharajan (MV) identity scheme. This option is mutually exclusive with the -I and -G options. Note: support for this option should be considered a work in progress.; Generate nkeys encrypted server keys for the Mu-Varadharajan (MV) identity scheme. This option is mutually exclusive with the -I and -G options. Note: support for this option should be considered a work in progress.

Random Seed File

All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the OpenSSL library routines. If a site supports ssh, it is very likely that means to do this are already available. The entropy seed used by the OpenSSL library is contained in a file, usually called .rnd, which must be available when starting the ntp-keygen program or ntpd daemon.

Related Links

Autokey Public-Key Authentication

Table of Contents

Introduction

Autokey Subnets

NTP Secure Groups

NTP Secure Group Configuration

Configuration - Authentication Scheme

Configuration - Authentication Schemes

Configuration - Identity Schemes

Examples

Copyright Notice

Generic Reference Driver

Synopsis

Description

Timecode variables listed by ntpq (8)

Supported Devices

Operation

Hardware PPS support
-

Monitor Data

Fudge Factors

Making your own PARSE clocks

Generic Reference Driver

Synopsis

Description

Timecode variables listed by ntpq (8)

Supported Devices

Operation

Hardware PPS support
+

Monitor Data

Fudge Factors

Making your own PARSE clocks

Related Links

Description

Running the Program

Command Line Options

Random Seed File

Related Links

Autokey Public-Key Authentication

Table of Contents

Introduction

Autokey Subnets

NTP Secure Groups

NTP Secure Group Configuration

Configuration - Authentication Scheme

Configuration - Authentication Schemes

Configuration - Identity Schemes

Examples

Copyright Notice

Generic Reference Driver

Synopsis

Description

Timecode variables listed by ntpq (8)

Supported Devices

Operation

Hardware PPS support -

Monitor Data

Fudge Factors

Making your own PARSE clocks

Generic Reference Driver

Synopsis

Description

Timecode variables listed by ntpq (8)

Supported Devices

Operation

Hardware PPS support +

Monitor Data

Fudge Factors

Making your own PARSE clocks

Related Links

Description

Running the Program

Command Line Options

Random Seed File

Hardware PPS support
-

Hardware PPS support
+