From: Harlan Stenn Date: Thu, 23 Dec 2010 07:22:35 +0000 (-0500) Subject: Documentation updates from Dave Mills X-Git-Tag: NTP_4_2_7P102~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f2a7386a3a2fb0be157851fd891837f04c6d4250;p=thirdparty%2Fntp.git Documentation updates from Dave Mills bk: 4d12f8bbBwl8KBm85Z_ZzvVxgcnpaw --- diff --git a/ChangeLog b/ChangeLog index 1936fffbf..174587328 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,5 @@ * Allow ntpq &1 associd use without preceding association-fetching. +* Documentation updates from Dave Mills. (4.2.7p101) 2010/12/22 Released by Harlan Stenn * from 4.2.6p3-RC12: Upgrade to libopts 34.0.9 from AutoGen 5.11.6pre7. * from 4.2.6p3-RC12: Relax minimum Automake version to 1.10 with updated diff --git a/html/authopt.html b/html/authopt.html index 9d202feed..252e363df 100644 --- a/html/authopt.html +++ b/html/authopt.html @@ -18,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: - 15-Dec-2010 2:56 + 22-Dec-2010 21:55 UTC

Autokey Public-Key Authentication

Last update: - 19-Dec-2010 22:23 + 23-Dec-2010 6:59 UTC

@@ -38,41 +38,51 @@

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 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 one step closer to the THs and terminating at the self-signed certificate of a TH. In general, NTP servers operate as certificate authorities (CAs) to sign certificates provided by its clients. The CAs include the THs and those group servers with dependent clients. 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 requirement that the NTP subnet be acyclic means that, if peers are configured with each other in symmetric modes, each must be a TH.

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.

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 trusted agent (TA) of a host group, as described below.

The requirement that the NTP subnet be acyclic means that, if peers are configured with each other in symmetric modes, each must be a TH.

+ +

A certificate trail is a sequence of certificates, each signed by a host one step closer to the THs and terminating at the self-signed certificate of a TH. NTP servers operate as certificate authorities (CAs) to sign certificates provided by their clients. The CAs include the TAs of the host group and those subnet servers with dependent clients.

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.

The Autokey protocol runs for each association separately; but, 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. During the protocol, the client recursively obtains 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 valid until it is demobilized, even if certificates on the trail to the THs expire.

Example

Figure 1. Example Configuration

Figure 1 shows an example configuration with three NTP subnets, Alice, Helen and Carol. Hosts A and B are THs of Alice, host R is the TH of Helen and host X is the TH of Carol. Assume that all associations are client/server; so, for example, TH X has two mobilized associations, one to Alice host C and the other to Carol host S. While not shown in the figure, Alice hosts A and B could configure symmetric mode associations between them for redundancy and backup.

Figure 1 shows an example configuration with three NTP subnets, Alice, Helen and Carol. Alice and Helen are host groups for Carol with TA C belonging to Alice and TA S belonging to Helen. Hosts A and B are THs of Alice, host R is the TH of Helen and host X is the TH of Carol. Assume that all associations are client/server, TH X has two mobilized associations, one to Alice TA host C and the other to Carol TA host S. While not shown in the figure, Alice hosts A and B could configure symmetric mode associations between them for redundancy and backup.

Note that host D cetificate trail is D→C→A or D→C→B, depending on the particular order the trails are built. Host Y certificate trail is only Y→X, since X is a TH. Host X has two cetficate trails X→C→A or X→C→B, and X→S→R.

NTP Secure Groups

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 victim of masquerade 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; they and possibly other hosts in the group run the identity exchange. All group hosts construct an unbroken certificate trail from each host, possibly via intermediate hosts, and ending at a TH of that group. The TH verifies authenticity as a client of a serverin another group.

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.

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.

As in NTP subnets, NTP secure groups are configured as an acyclic tree rooted on the THs. The THs are at the lowest stratum of the secure group. They run the identity exchange with the TAs of the host groups. All group hosts construct an unbroken certificate trail from each host, possibly via intermediate hosts, and ending at a TH of that group. The TH verifies authenticity with the TA of a host group.

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.

Figure 2. Identify Scheme

As shown in Figure 2, an Autokey identity scheme involves 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.

The identity exchange is run between a TA acting as a server and a TH acting as a client. As shown in Figure 2, an Autokey identity scheme involves 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 secret group key to persist long after the longest period of certificate validity. In the Schnorr (Identify Friend or Foe - IFF) scheme, 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 server keys file and a nonencrypted client keys file, also called the parameters file, which usually contains a subset of the keys file.

Figure 2 shows how keys and parameters are distributed to servers and clients. Here, a TH constructs the encrypted keys file and the nonencrypted parameters file. Hosts with no dependent clients can retrieve client parameter files from an - archive or web page. The ntp-keygen program can export parameter files using the -e option. - Servers with dependent clients other than THs must retrieve copies of the server +

Figure 2 shows how keys and parameters are distributed to servers and clients. Here, a TA constructs the encrypted keys file and the nonencrypted parameters file. Hosts with no dependent clients can retrieve client parameter files from an + archive or web page. The ntp-keygen program can export parameter files using the -e option. By convention, the file name is the name of the secure group and must match the ident command option and the ident option of the server command.

When more than one TH Is involved, it is conventient to distribute copies of the keys file with different passwords. THs can retrieve copies of the server keys file using secure means. The ntp-keygen program can export server keys files using the -q option and chosen remote password. In either case the files are installed and then renamed using the name given as the first line in the file, but without - the filestamp.

+ the filestamp. Unless the files are named according to the following conventions, it may be necessary to use symbolic links.

In the current version of Autokey, it is not necessary to provide a name for the secure group. However, a name is required for previous Aurokwy versions. ONe of the TAs of the host group generatees the identify keys and parameters files and exports the keys file to all other TAs seving the secure group as described in the previous section.

The string specified by the -i option of the ntp-keygen program is the name of the secure group. This name must match the ident option + of the crypto command of all TAs in the host group. The name is used in the identity keys and parameters file names, but has no effect on protocol opedrations. The file naming conventions are described on + the ntp-keygen page.

Example

Returning to the example of Figure 1, Alice, Helen and Carol run TC, internally, as the environment is secure and without threat from external attack, in particular a middleman masquerade. However, TH X of Carol is vulnerable to masquerade on the links between X and C and between X and S. Therefor, both C and S are configured as Autokey servers with, for example, the IFF identity scheme, and X as a client of both of them. For this purpose, both C and S export their IFF parameter files to X as described above.

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 @@ -93,15 +103,15 @@ # 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. 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

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

Configuration - Identity Schemes

For the simplest identity scheme TC, the server TA generates identity files using an ntp-keygen program commadn with options specified in this section, while the client TH uses the same command with no options. The TA uses the crypto command in the comnfiguration file with options specified in this section, while the TH uses the same command with no options. Additional TH options are specified in the server and ident command for each association.

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

ntp-keygen -I.

Note the TA is not a trusted host, so does not have the -T option. 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

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 to one or more THs. 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

where passwd2 is the read password for another host. In the client case the file name is arbitrary as used in the server and ident commands. In the server 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, diff --git a/html/keygen.html b/html/keygen.html index d7f7d2e47..1b0e275b3 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: - 14-Dec-2010 5:00 + 22-Dec-2010 21:55

Synopsis

ntpd [ -46aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ] [ -U interface_update_interval ] [ -v variable ] [ -V variable ]

Description

The ntpd program is an operating system daemon that synchronises the system clock to remote NTP time servers or local reference clocks. It is a complete implementation of NTP version 4 defined by RFC-5905, but also retains compatibley with version 3 defined by RFC-1305 and versions 1 and 2, defined by RFC-1059 and RFC-1119, respectively. The program can operate in any of several modes, including client/server, symmetric and broadcasrt modes, and with both symmetric-key and public key-cryptography

The ntpd program is an operating system daemon that synchronizes the system clock to remote NTP time servers or local reference clocks. It is a complete implementation of NTP version 4 defined by RFC-5905, but also retains compatible with version 3 defined by RFC-1305 and versions 1 and 2, defined by RFC-1059 and RFC-1119, respectively. The program can operate in any of several modes, including client/server, symmetric and broadcast modes, and with both symmetric-key and public key-cryptography

The ntpd program ordinarily requires a configuration file described on this page. It contains configuration commands described on the pages listed above. However a client can discover remote servers and configure them automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. Further details are on the

The ntpd program normally operates continuously while adjusting the system time and frequency, but in some cases this might not be practical. With the -q option ntpd operates as in continous mode, but exits just after setting the clock for the first time. Most applications will probably want to specify the iburst option with the server command. With this option a volley of messages is exchanged to groom the data and set the clock in about ten seconds. If nothing is heard after a few minutes, the daemon times out and exits without setting the clock.

The ntpd program normally operates continuously while adjusting the system time and frequency, but in some cases this might not be practical. With the -q option ntpd operates as in continuous mode, but exits just after setting the clock for the first time. Most applications will probably want to specify the iburst option with the server command. With this option a volley of messages is exchanged to groom the data and set the clock in about ten seconds. If nothing is heard after a few minutes, the daemon times out and exits without setting the clock.

Command Line Options

-a
-b: Enable the client to synchronize to broadcast servers.
-c conffile: Specify the name and path of the configuration file, default /etc/ntp.conf.; Specify the name and path of the configuration file. Without the option the default is /etc/ntp.conf.
-d: Specify debugging mode. This option may occur more than once, with each occurrence indicating greater detail of display.; Disable switching into daemon mode, so ntpd stays attached to the starting terminal which will get all the debugging printout. Also, ^C will kill it. This option may occur more than once, with each occurrence indicating greater detail of display.
-D level: Specify debugging level directly.; Specify debugging level directly, with level corresponding to the numbe of -d options..
-f driftfile: Specify the name and path of the frequency file, default /etc/ntp.drift. This is the same operation as the driftfile driftfile command.; Specify the name and path of the frequency file. This is the same operation as the driftfile command.
-g: Normally, ntpd exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, ntpd will exit with a message to the system log. This option can be used with the -q and -x options. See the tinker command for other options.
-i jaildir
-L: Do not listen to virtual interfaces, defined as those with names containing a colon. This option is deprecated. Please consider using the configuration file interface command, which is more versatile.
-M: Raise scheduler precision to its maximum (1 msec) using timeBeginPeriod. (Windows only); Raise scheduler precision to its maximum (1 ms) using timeBeginPeriod. (Windows only)
-n: Don't fork.
-N
-u user[:group]: Specify a user, and optionally a group, to switch to. This option is only available if the OS supports running the server without full root privileges. Currently, this option is supported under NetBSD (configure with --enable-clockctl) and Linux (configure with --enable-linuxcaps).
-U interface update interval: Number of seconds to wait between interface list scans to pick up new and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.
-v variable
-V variable: Number of seconds to wait between interface list scans to pick up old and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.
-v variable + -V variable: Add a system variable listed by default.
-x: Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus, an adjustment as much as 600 s will take almost 14 days to complete. This option can be used with the -g and -q options. See the tinker command for other options. Note: The kernel time discipline is disabled with this option.
clockvar assocID [name [ = value [...]] [...] cv assocID [name [ = value [...] ][...]: Display a list of clock variables for those assocations supporting a reference clock.; Display a list of clock variables for those associations supporting a reference clock.
:config [...]: Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.
config-from-file filename
keyid: Specify the key ID to use for write requests.
lassociations: Perform the same function as the associations command, execept display mobilized and unmobilized associations.; Perform the same function as the associations command, except display mobilized and unmobilized associations.
monstats: Display monitor facility statistics.
mrulist [limited | kod | mincount=count | laddr=localaddr | sort=sortorder | resany=hexmask | resall=hexmask]
saveconfig filename: Write the current configuration, including any runtime modifications given with :config or config-from-file, to the ntpd host's file filename. This command will be rejected by the server unless saveconfigdir appears in the ntpd configuration file. filename can use strftime() format specifiers to substitute the current date and time, for example, saveconfig ntp-%Y%m%d-%H%M%S.conf. The filename used is stored in system variable savedconfig. Authentication is required.; Write the current configuration, including any runtime modifications given with :config or config-from-file, to the ntpd host's file filename. This command will be rejected by the server unless saveconfigdir appears in the ntpd configuration file. filename can use strftime() format specifies to substitute the current date and time, for example, saveconfig ntp-%Y%m%d-%H%M%S.conf. The filename used is stored in system variable savedconfig. Authentication is required.
writevar assocID name = value [,...]: Write the specified variables. If the assocID is zero, the variables are from the system variables name space, otherwise they are from the peer variables name space. The assocID is required, as the same name can occur in both spaces.
sysstats

Variable	`jitter`	filter jitter
`ident`	Autokey group name for this association
`bias`	unicast/broadcast bias	interleave delay (see NTP Interleaved Modes)

`signature`	OpenSSL digest/signature shceme	OpenSSL digest/signature scheme
`initsequence`

Variable	Description
`associd`	`assoc id`	association ID
device description
`timecode`	ASCII timecode string (specific to device)	`time code`	ASCII time code string (specific to device)
`poll`	poll messages sent
`noreply`	`no reply`	no reply
`badformat`	`bad format`	bad format
`baddata`	`bad data`	bad date or time
driver stratum
`refid`	`re fid`	driver reference ID

Related Links

Autokey Public-Key Authentication

Table of Contents

Autokey Subnets

NTP Secure Groups

Configuration - Authentication Schemes

Configuration - Identity Schemes

Configuration - Identity Schemes

Related Links

Related Links

Synopsis

Description

Command Line Options

More Help

Peer Variables

Clock Variables