From: Harlan Stenn Date: Mon, 1 Nov 2010 04:46:10 +0000 (-0400) Subject: Documentation updates from Dave Mills X-Git-Tag: NTP_4_2_7P76~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c9ebdcf16e0b3cf4b1cdc462fc14fd4f20608439;p=thirdparty%2Fntp.git Documentation updates from Dave Mills bk: 4cce46124Leo7fql7iZ6yxvHlBBtfg --- diff --git a/ChangeLog b/ChangeLog index 6c1b1e03b..bc58620cf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -2,6 +2,7 @@ * [Bug 1691] Use first NMEA sentence each second. * Put the sntp tests under sntp/ . * ... and only build/run them if we have gtest. +* Documentation updates from Dave Mills. (4.2.7p75) 2010/10/30 Released by Harlan Stenn * Documentation updates from Dave Mills. * Include Linus Karlsson's GSoC 2010 testing code. diff --git a/html/authentic.html b/html/authentic.html index 9a5948170..acf224a73 100644 --- a/html/authentic.html +++ b/html/authentic.html @@ -11,6 +11,7 @@ color: #FF0000; font-weight: bold; } +.style1 {color: #FF0000} --> @@ -19,7 +20,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: - 28-Oct-2010 17:34 + 31-Oct-2010 4:18 UTC

Introduction

The NTPv3 specification RFC-1305 defines a scheme properly described as symmetric key cryptography. It uses the Data Encryption Standard (DES) algorithm operating in cipher-block chaining (CBC) mode. Subsequently, this algorithm was replaced by the RSA Message Digest 5 (MD5) algorithm commonly called keyed-MD5. Either algorithm computes a message digest or one-way hash which can be used to verify the client has the same key and key identifier as the server. The MD5 message digest algorithm is included in the distribution, so without further cryptographic support, the distribution can be freely exported..

This page describes the various cryptographic authentication provisions in NTPv4. Authentication support allows the NTP client to verify that servers are in fact known and trusted and not intruders intending accidentally or intentionally to masquerade as a legitimate server. A detailed discussion of the NTP multi-layer security model and vulnerability analysis is in the white paper NTP Security Analysis.

The NTPv3 specification RFC-1305 defines a scheme properly described as symmetric key cryptography. It uses the Data Encryption Standard (DES) algorithm operating in cipher-block chaining (CBC) mode. Subsequently, this algorithm was replaced by the RSA Message Digest 5 (MD5) algorithm commonly called keyed-MD5. Either algorithm computes a message digest or one-way hash which can be used to verify the client has the same key and key identifier as the server. The MD5 message digest algorithm is included in the distribution, so without further cryptographic support, the distribution can be freely exported.

If the OpenSSL cryptographic library is installed prior to building the distribution, all message digest algorithms included in the library may be used, including SHA and SHA1. However, if conformance to FIPS 140-2 is required, only a limited subset of these algorithms can be used. This library is available from http://www.openssl.org and can be installed using the procedures outlined in the Building and Installing the Distribution page. Once installed, the configure and build process automatically detects the library and links the library routines required.

In addition to the symmetric key algorithms, 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.

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.

Note that according to US law, NTP binaries including OpenSSL library components, including the OpenSSL library itself, cannot be exported outside the US without license from the US Department of Commerce. Builders outside the US are advised to obtain the OpenSSL library directly from OpenSSL, which is outside the US, and build outside the US.

Authentication is configured separately for each association using the key or autokey option of the server configuration command, as described in the Server Options page, and the options described on this page. The ntp-keygen page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from www.ntp.org.

By default, authentication is required only for those packets that might require significant resources, such as broadcast, symmetric active or manycast server packets, as these represent a potential clogging vulnerability. In the current climate of targeted broadcast or "letterbomb" attacks, defeating this requirement would be decidedly dangerous. However, it can be defeated using the disable auth command. Authentication is also an access control option using the restric command and the notrust flag.

Symmetric Key Cryptography

The original RFC-1305 specification allows any one of possibly 65,534 keys (excluding zero), each distinguished by a 32-bit key ID, to authenticate an association. The servers and clients involved must agree on the key ID, key type and key to authenticate NTP packets.

The message digest is a cryptographic hash computed by an algorithm such as MD5 or SHA. When authentication is specified, the reference implementation appends a message authentication code (MAC) to the NTP packet header. The MAC consists of a 32-bit key identifier (key ID) followed by a 128- or 160-bit message digest. The algorithm computes the digest as the hash of a 128- or 160- bit secret key concatenated with the NTP packet header fields with the exception of the MAC. On transmit, the digest is computed and inserted in the MAC. On receive, the message digest is computed and compared with the MAC. The packet is accepted only if the two digests are identical. If this happens at the client, the client ignores the packet, but raises an alarm. If this happens at the server, the server returns a special message called a crypto-NAK. Since the crypto-NAK is protected by the loopback test, an intruder cannot disrupt the protocol by sending a bogus crypto-NAK.

The message digest is a cryptographic hash computed by an algorithm such as MD5 or SHA. When authentication is specified, a message authentication code (MAC) is appended to the NTP packet header. The MAC consists of a 32-bit key identifier (key ID) followed by a 128- or 160-bit message digest. The algorithm computes the digest as the hash of a 128- or 160- bit secret key concatenated with the NTP packet header fields with the exception of the MAC. On transmit, the digest is computed and inserted in the MAC. On receive, the message digest is computed and compared with the MAC. The packet is accepted only if the two digests are identical. If this happens at the client, the client ignores the packet, but raises an alarm. If this happens at the server, the server returns a special message called a crypto-NAK. Since the crypto-NAK is protected by the loopback test, an intruder cannot disrupt the protocol by sending a bogus crypto-NAK.

Keys and related information are specified in a keys file, usually called ntp.keys, 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 used as passwords for the ntpq and ntpdc utility programs. Ordinarily, the ntp.keys file is generated by the ntp-keygen program, but it can be constructed and edited using an ordinary text editor. The program generates pseudo-random keys, one key for each line. Each line consists of three fields, the key identifier as a decimal number from 1 to 65,534 inclusive, a key type chosen from the keywords of the digest option of the crypto command, and a 20-character printable ASCII string or a 40-character hex string as the key itself.

gif

Figure 1. Typical Symmetric Key File

Figure 1 shows a typical keys file used by the reference implementation. In the case of MD5, the key is restricted to ASCII printing characters, either a given string, such as 2late4Me for key ID 10, or a random string. In other digest algorithms the key is a random hex string.

Figure 1 shows a typical keys file used by the reference implementation. In the case of MD5, the key consists of 16 characters randomized over the ASCII printing codes The string can be edited later for a password, for instance as 2late4Me for key ID 10. For message digest algorithms other than MD5, the key is a 20-octet random hex string.

When ntpd is first started, it reads the key file specified by the keys command and installs the keys in the key cache. However, individual keys must be activated with the trustedkey configuration command before use. This allows, for instance, the installation of possibly several batches of keys and then activating a key remotely using ntpdc. The requestkey command selects the key ID used as the password for the ntpdc utility, while the controlkey command selects the key ID used as the password for the ntpq utility.

Microsoft Windows Authentication

diff --git a/html/authopt.html b/html/authopt.html index 8d6e23dc9..8b175af27 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: - 14-Oct-2010 22:27 + 31-Oct-2010 3:55 UTC

Autokey Public-Key Authentication

Last update: - 12-Sep-2010 3:22 + 31-Oct-2010 4:38 UTC

@@ -22,10 +22,11 @@

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.

The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using message digest algorihtms such as MD5 and SHA and verifies the source using 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.

There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 h, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.

There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 hr, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.

NTP Secure Groups

NTP secure groups are used to define cryptographic compartments and security hierarchies. All hosts belonging to a secure group have the same group name @@ -35,13 +36,13 @@ of the crypto command is the group name of all group hosts and the name used in the identity files. The file naming conventions are described on the ntp-keygen page.

Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH self-signed trusted certificate for these hosts. The host name is used in the subject and issuer fields of the self-signed certificates for all other hosts.

All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts and ending at a TH. When a host starts up, it recursively retrieves the certificates along the trail in order to verify group membership and avoid masquerade and middleman attacks.

Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. A certificate trail consist of a chain of hosts starting at a client, leading through secondary servers of progressively lower stratum and ending at a TH. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.

All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts, and ending at a TH. 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.

Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. In a typical scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.

Identity Schemes and Cryptotypes

All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the Identity Schemes page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the Autokey Identity Schemes page.

All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three optional identity schemes, IFF, GQ and MV described on the Identity Schemes page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the Autokey Identity Schemes page.

A specific combination of authentication and identity schemes is called a - cryptotype, which applies to clients and servers separately. A group can be + cryptotype, which applies to clients and servers separately. A group can be configured using more than one cryptotype combination, although not all combinations are interoperable. Note however that some cryptotype combinations may successfully intemperate with each other, but may not represent good security practice. The diff --git a/html/keygen.html b/html/keygen.html index ed6910a31..f443bb6c5 100644 --- a/html/keygen.html +++ b/html/keygen.html @@ -11,7 +11,7 @@

gif from Alice's Adventures in Wonderland, Lewis Carroll

Alice holds the key.

Last update: - 12-Sep-2010 3:36 + 30-Oct-2010 3:19

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.

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

gif

Figure 1. Typical Symmetric Key File

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 must 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 character 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.

diff --git a/html/scripts/external.txt b/html/scripts/external.txt index f9c6cc9c4..b59f8d242 100644 --- a/html/scripts/external.txt +++ b/html/scripts/external.txt @@ -9,6 +9,7 @@ document.write("

External Links

Related Links

Introduction

Symmetric Key Cryptography

Related Links

Autokey Public-Key Authentication

Table of Contents

Introduction

NTP Secure Groups

Identity Schemes and Cryptotypes

Related Links

Description