From: Harlan Stenn Date: Mon, 13 Sep 2010 05:21:03 +0000 (-0400) Subject: Documentation updates from Dave Mills X-Git-Tag: NTP_4_2_7P49~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9f52ebf576a9117cba2b7bee8ab14e2728fab095;p=thirdparty%2Fntp.git Documentation updates from Dave Mills bk: 4c8db4bfbZeCjMfOoBVr9eQnwZtrZg --- diff --git a/ChangeLog b/ChangeLog index 7e35a0386..104737e46 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Documentation updates from Dave Mills. (4.2.7p48) 2010/09/12 Released by Harlan Stenn * Documentation updates from Dave Mills. (4.2.7p47) 2010/09/11 Released by Harlan Stenn diff --git a/html/assoc.html b/html/assoc.html index fac418ffc..774a9b4c5 100644 --- a/html/assoc.html +++ b/html/assoc.html @@ -11,7 +11,7 @@ gif

from Alice's Adventures in Wonderland, Lewis Carroll

Make sure who your friends are.

Last update: - 09-Sep-2010 20:30 + 12-Sep-2010 3:04 UTC

Association Modes

This page describes the various modes of operation provided in NTPv4. There are three types of associations in NTP: persistent, preemptable and ephemeral. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the preempt option and are demobilized by a "better" server or by timeout, but only if the number of survivors exceeds the threshold set by the tos maxclock command. Ephemeral associations are mobilized upon arrival of designated NTP packets and demobilized by timeout.

Ordinarily, successful mobilization of ephemeral associations requires the server to be cryptographically authenticated to the client. This can be done using either symmetric key or Autokey public key cryptography, as described in the Authentication Options page.

There are three principal modes of operation in NTP: client/server, symmetric active/passive and broadcast/multicast. There are three automatic server discovery schemes in NTP: broadcast/multicast, manycast and pool described on the Automatic Server Discovery Schemes page. In addition, the orphan mode and burst options described on this page can be used in appropriate cases.

Following is a summary of the operations in each mode. Note that reference to option applies to the commands described on the Configuration Options page. See that page for applicability and defaults.

Client/Server Mode

Client/server mode is the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers and stateful clients. In this mode a host sends a client (mode 3) request to the specified server and expects a server (mode 4) reply at some future time. In some contexts this would be described as a "pull" operation, in that the host pulls the time and related values from the server.

@@ -52,11 +52,11 @@

A peer is configured in symmetric active mode using the peer command and specifying the other peer DNS name or IPv4 or IPv6 address. The burst and iburst options should not be used in symmetric modes, as this can upset the intended symmetry of the protocol and result in spurious duplicate or dropped messages.

As symmetric modes are most often used as root servers for moderate to large subnets where rapid response is required, it is generally best to set the minimum and maximum poll intervals of each root server to the same value using the minpoll and maxpoll options.

Broadcast/Multicast Modes

NTP broadcast and multicast modes are intended for configurations involving one or a few servers and a possibly very large client population. Broadcast mode can be used with Ethernet, FDDI and WiFi spans interconnected by hubs or switches. Ordinarily, broadcast packets do not extend beyond a level-3 router. Where service is intended beyond a level-3 router, multicast mode can be used. Additional information is on the Automatic NTP Configuration Options page.

A server is configured to send broadcast or multicast messages using the broadcast command and specifying the subnet address for broadcast or the multicast group address for multicast. A broadcast client is enabled using the broadcastclient command, while a multicasst client is enabled using the multicstclient command and specifiying the multicast group address. Multiple commands of either type can be used. However, the association is not mobilized until the first broadcast or multicast message is actuayl received.

Manycast and Pool Modes

Manycast and pool modes are automatic discovery and configuration paradigms new to NTPv4. They are intended as a means for a client to troll the nearby network neighborhood to find cooperating willing servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each client mobilizes ephemeral client associations with some number of the "best" of the nearby servers, yet automatically reconfigures to sustain this number of servers should one or another fail. Additional information is on the Automatic Server Discovery Schemes page.

Poll Interval Control

NTP uses an intricate heuristic algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network overhead. The algorithm measures the incidental offset and jitter to determine the best poll interval. When ntpd starts, the interval is the default minimum 64 s. Under normal conditions when the clock discipline has stabilized, the interval increases in steps to the default maximum 1024 s. In addition, should a server become unreachable after some time, the interval increases in steps to the maximum in order to reduce network overhead.

The default poll interval range is suitable for most conditions, but can be changed using options on the Server Options and Miscellaneous Options pages. However, when using maximum intervals much larger than the default, the residual clock frequency error must be small enough for the discipline loop to capture and correct. The capture range is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM.

In the NTPv4 specificationn and reference implementation, the poll interval is expressed in log₂ units, properly called the poll exponent. It is constrained by the lower limit minpoll and upper limit maxpoll options of the server command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases. The default limits can be changed with these options to a minimum set by the average option of the discard command (see below) to a maximum of 17 (36 h).

@@ -67,7 +67,7 @@

With symmetric modes the most stable behavior results when both peers are configured in symmetric active mode with matching poll intervals of 6 (64 s).

The poll interval should not be modified for reference clocks, with the single exception the ACTS telephone modem driver. In this case the recommended minimum and maximum intervals are 12 (1.1 h) and 17 (36 h), respectively.

Burst Options

Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the burst and iburst options of the server command, the poll algorithm sends a burst of several packets at 2-s intervals. The ntpd poll algorithm avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding.

For the iburst option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the burst option, the number of packets in the burst is determined by the difference between the poll interval and the minimum poll interval set by the minpoll option of the server command. For instance, with a poll exponent of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll intervals of 9 (512 s) or more.

There are two burst options where a single poll event triggers a burst of eight packets at 2-s intervals instead of the normal one packet. They should be used only with the server and pool commands, but not with reference clock drivers nor symmetric peers. The burst option sends a burst when the server is reachable, while the iburst option sends a burst when the server is unreachable. Each mode is independently of the other and both can be used at the same time. In either mode the client sends one packet, waits for the reply, then sends the remaining packets in the burst. This may be useful to allow a modem to complete a call.

diff --git a/html/authopt.html b/html/authopt.html index 226bcf4e5..dea49cf9f 100644 --- a/html/authopt.html +++ b/html/authopt.html @@ -17,7 +17,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: - 11-Sep-2010 15:56 + 12-Sep-2010 3:08 UTC

Autokey Public-Key Authentication

Last update: - 11-Sep-2010 19:19 + 12-Sep-2010 3:22 UTC

Introduction
Introduction
NTP Secure Groups
Identity Schemes and Cryptotypes
Configuration
Examples

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 used when the distribution is built. Public key cryptography is generally more secure than symmetric key cryptography, since the security is based on private and public values which are generated by each participant and where the private value is never revealed. Autokey uses X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library or the ntp-keygen utility program in the NTP software distribution.

The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes 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.

The chicken is getting configuration advice.

Last update: - 10-Sep-2010 0:29 + 12-Sep-2010 4:07

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 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. Printable ASCII keys can have - length from one to 20 characters, inclusive. Bit string keys have length - 20 octets (40 hex characters). All keys are 160 bits in length.

+ 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. Printable ASCII keys can have length from one to 20 characters, inclusive. Bit string keys have length 20 octets (40 hex characters). All keys are 160 bits in length.

The file can be edited later with purpose-chosen passwords for the ntpq and ntpdc programs. - Each line of the file contains three fields, first an integer between 1 and - 65534, inclusive, representing the key identifier used in the server and peer configuration - commands. Next is the key type for the message digest algorithm, - which in the absence of the OpenSSL library should be the string MD5 to - designate the MD5 message digest algorithm. - If the OpenSSL library is installed, the key type can be any message digest - algorithm supported by that library. However, if compatibility with FIPS - 140-2 is required, the key type must be either SHA or SHA1.Finally - is the key itself as a printable ASCII string excluding the space and # characters. - If not greater than 20 characters in length, the string is the key itself; - otherwise, it is interpreted as a hex-encoded bit string. As is - custom, # and the remaining characters on the line are ignored. Later, this - file can be edited to include the passwords for the ntpq and ntpdc utilities. - If this is the only need, run ntp-keygen with the -M option - and disregard the remainder of this page.

+ Each line of the file contains three fields, first an integer between 1 and 65534, inclusive, representing the key identifier used in the server and peer configuration commands. Next is the key type for the message digest algorithm, which in the absence of the OpenSSL library should be the string MD5 to designate the MD5 message digest algorithm. If the OpenSSL library is installed, the key type can be any message digest algorithm supported by that library. However, if compatibility with FIPS 140-2 is required, the key type must be either SHA or SHA1.Finally is the key itself as a printable ASCII string excluding the space and # characters. If not greater than 20 characters in length, the string is the key itself; otherwise, it is interpreted as a hex-encoded bit string. As is custom, # and the remaining characters on the line are ignored. Later, this file can be edited to include the passwords for the ntpq and ntpdc utilities. If this is the only need, run ntp-keygen with the -M option and disregard the remainder of this page.

The remaining generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates generated by this program should be 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.

Most 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 files sent to remote sites. If no local password is specified, the host name returned by the Unix gethostname() function, normally the DNS name of the host, is used. If no remote password is specified, the local password 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.

All files and links are usually installed in the directory /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. 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.

All files and links are usually installed in the directory /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. 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.

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 a file. 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; however, the certificate is not generated if the -e or -q options are present.

@@ -86,41 +55,25 @@

As described on the Authentication Options page, an NTP secure group consists of one or more low-stratum 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 -i option and matching the ident option of the crypto configuration command. The group name is used in the subject and issuer fields of trusted, self-signed certificates and when constructing the file names for identity keys. All hosts must have different host names, either the default host name or as specified by the -s option and matching the host option of the crypto configuration command. Most installations need not specify the -i option nor the host option. Host names are used in the subject and issuer fields of self-signed, nontrusted certificates and when constructing the file names for host and sign keys and certificates. Host and group names are used only for authentication purposes and have nothing to do with DNS names.

Identity Schemes

As described on the Authentication Options page, there are five identity schemes, three of which - IFF, GQ and MV - require identity keys 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 secondary servers operating as certificate signing authorities (CSA) use the keys file and clients use the parameters file. Both files are generated by the TA operating as a certificate authority (CA) on behalf of all servers and clients in the group.

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 retrieved from +

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 retrieved from a secure web site.

For example, the TA generates default host key, IFF keys and trusted certificate using the command

ntp-keygen -p local_passwd -T -I -igroup_name

Each group host generates default host keys and nontrusted certificate use - the same command line but omitting the -i option. Once these media - have been generated, the TA can then generate the public parameters using the - command

Each group host generates default host keys and nontrusted certificate use the same command line but omitting the -i option. 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 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.

Command Line Options

-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]: Select certificate and message digest/signature encryption scheme. Note that - RSA schemes must be used with a RSA sign key and DSA schemes must be used - with a DSA sign key. The default without this option is RSA-MD5. If - compatibility with FIPS 140-2 is required, either the DSA-SHA or DSA-SHA1 scheme - must be used.; Select certificate and message digest/signature encryption scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is RSA-MD5. If compatibility with FIPS 140-2 is required, either the DSA-SHA or DSA-SHA1 scheme must be used.
-d: Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.
-e: Extract the IFF or GQ public parameters from the IFFkey or GQkey keys file previously specified. Send the unencrypted data to the standard output stream stdout. While the IFF parameters do not reveal the private group key, the GQ parameters should be used with caution, as they include the group key. Use the -q option with password instead. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.
-G: Generate a new encrypted GQ key file and link for the Guillou-Quisquater - (GQ) identity scheme.; Generate a new encrypted GQ key file and link for the Guillou-Quisquater (GQ) identity scheme.
-H: Generate a new encrypted RSA public/private host key file and link. - Note that if the sign key is the same as the host key, generating a new host - key invalidates all certificates signed with the old host key.; Generate a new encrypted RSA public/private host key file and link. Note that if the sign key is the same as the host key, generating a new host key invalidates all certificates signed with the old host key.
-i group: Set the group name to group. This is used in the identity file names. It must match the group name specified in the ident option of the crypto configuration command.
-I
freq freq: Specifies the frequency offset in parts-per-million (PPM) with default the value in the frequency file.
huffpuff huffpuff: Sp edifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours).; Sp edifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 min), but a more reasonable value is 7200 (2 hours).See the Huff-n'-Puff Filter page for further information.
panic panic: Sp edifies the panic threshold in seconds with default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.
step step: Sp edifies the step threshold in seconds. The default without this command - is 0.128 s. If set to zero, step adjustments will never - occur. Note: The kernel time discipline is disabled if - the step threshold is set to zero or greater than 0.5 +; Sp edifies the step threshold in seconds. The default without this command is 0.128 s. If set to zero, step adjustments will never occur. Note: The kernel time discipline is disabled if the step threshold is set to zero or greater than 0.5 s.
stepout stepout: Specifies the stepout threshold in seconds. The default without this - command is 900 s. If set to zero, popcorn spikes will - not be suppressed.; Specifies the stepout threshold in seconds. The default without this command is 900 s. If set to zero, popcorn spikes will not be suppressed.

tos [ beacon beacon | ceiling ceiling | cohort {0 | 1} | floor floor | maxclock maxclock | maxdist maxdist | minclock minclock | mindist mindist | minsane minsane | orphan stratum | orphanwait delay ]

beacon beacon: The manycast server sends packets at intervals of 64 s if less than maxclock servers are available. Otherwise, it sends packets at the beacon interval in seconds. The default is 3600 s. See the Automatic Server Discovery page for further details.; The manycast server sends packets at intervals of 64 s if less than maxclock servers are available. Otherwise, it sends packets at the beacon interval in seconds. The default is 3600 s. See the Automatic Server Discovery page for further details.
ceiling ceiling: Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the Automatic Server Discovery page for further details.; Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the Automatic Server Discovery page for further details.
cohort { 0 | 1 }: Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the Automatic Server Discovery page for further details.; Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the Automatic Server Discovery page for further details.
floor floor: Specify the minimum stratum (inclusive) for acceptable server packets. The default is 1. See the Automatic Server Discovery page for further details.; Specify the minimum stratum (inclusive) for acceptable server packets. The default is 1. See the Automatic Server Discovery page for further details.
maxclock maxclock: Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the Automatic Server Discovery page for further details.; Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the Automatic Server Discovery page for further details.
maxdist maxdistance: Specify the synchronization distance threshold used by the clock selection algorithm. The default is 1.5 s. This determines both the minimum number of packets to set the system clock and the maximum roundtrip delay. It can be decreased to improve reliability or increased to synchronize clocks on the Moon or planets.
minclock minclock

Related Links

Association Modes

Client/Server Mode

Broadcast/Multicast Modes

Manycast and Pool Modes