[ntpsec commit] A major step towards getting the configuration documentation refactored.

[Eric S. Raymond]

Module:    ntpsec
Branch:    master
Commit:    4a9c0942087d8c2852ca5a5c5f5d7fdf160686a9
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=4a9c0942087d8c2852ca5a5c5f5d7fdf160686a9

Author:    Eric S. Raymond <esr at thyrsus.com>
Date:      Sun Oct 11 12:50:03 2015 -0400

A major step towards getting the configuration documentation refactored.

What this commit does is move most of the material on authentication and
crypto from ntp.conf(5) to the Authentication page in the web documentation.

This material didn't belong on the man page, which should mainly be an
option reference, and it was actually better exposition than what was
already there.  What used to be there has been slimmed down and is
now the sections describing Algorithms and Data Formats.

Some duplication between new and old content remains to be polished out
by future edits.

Also, describe update-leap in scripts/README.

---

 docs/authentic.txt | 333 +++++++++++++++++++++++++++++++++++++++++++++++------
 ntpd/ntp.conf.txt  | 273 ++-----------------------------------------
 scripts/README     |   3 +
 3 files changed, 307 insertions(+), 302 deletions(-)

diff --git a/docs/authentic.txt b/docs/authentic.txt
index 84ee1ca..e121b57 100644
--- a/docs/authentic.txt
+++ b/docs/authentic.txt
@@ -19,7 +19,11 @@ include::includes/authopt.txt[]
 * link:#noauto[Problems with Autokey]
 * link:#auth[Introduction]
 * link:#symm[Symmetric Key Cryptography]
-* link:#windows[Microsoft Windows Authentication]
+* link:#operation[Operation]
+* link:#keys[Key Management]
+* link:#algorithms[Algorithms]
+* link:#formats[Data Formats]
+//* link:#windows[Microsoft Windows Authentication]
 * link:#pub[Public Key Cryptography]
 
 '''''
@@ -44,18 +48,274 @@ Autokey will remain disabled by default until the maintainers have
 confidence that its deficiencies have been repaired. We would welcome
 any assistance in that repair.
 
-
-[[auth]]
 == Introduction ==
 
-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
+Authentication support allows the NTP client to verify that the server
+is in fact known and trusted and not an intruder intending
+accidentally or on purpose to masquerade as that server.  NTP performs
+authentication via the RSA Message Digest 5 (MD5) algorithm using a
+private key, commonly called keyed-MD5. Either algorithm computes a
+message digest, or one-way hash, which can be used to verify the
+server has the correct private key and key identifier.
+
+A detailed discussion of the NTP multi-layer security model and
 vulnerability analysis is in the white paper
 {millshome}security.html[NTP Security Analysis].
 
+//NTPv4 retains the NTPv3 scheme, properly described as symmetric key
+//cryptography and, in addition, provides a new Autokey scheme based on
+//public key cryptography. Public key cryptography is generally considered
+//more secure than symmetric key cryptography, since the security is based
+//on a private value which is generated by each server and never revealed.
+//With Autokey all key distribution and management functions involve only
+//public values, which considerably simplifies key distribution and
+//storage. Public key management is based on X.509 certificates, which can
+//be provided by commercial services or produced by utility programs in
+//the OpenSSL software library or the NTPv4 distribution.
+//
+//While the algorithms for symmetric key cryptography are included in the
+//NTPv4 distribution, public key cryptography requires the OpenSSL
+//software library to be installed before building the NTP distribution.
+//Directions for doing that are on the "Building and Installing the
+//Distribution page."
+
+Authentication is configured separately for each association using the `key`
+//or `autokey`
+subcommand on the `peer`, `server`, `broadcast` and `manycastclient`
+configuration commands. The authentication options described below
+specify the locations of the key files, if other than default, which
+symmetric keys are trusted and the interval between various
+operations, if other than default.
+
+Authentication is always enabled, although ineffective if not configured
+as described below. If a NTP packet arrives including a message
+authentication code (MAC), it is accepted only if it passes all
+cryptographic checks. The checks require correct key ID, key value and
+message digest. If the packet has been modified in any way or replayed
+by an intruder, it will fail one or more of these checks and be
+discarded. Furthermore, the Autokey scheme requires a preliminary
+protocol exchange to obtain the server certificate, verify its
+credentials and initialize the protocol
+
+The `auth` flag controls whether new associations or remote
+configuration commands require cryptographic authentication. This flag
+can be set or reset by the `enable` and `disable` commands and also by
+remote configuration commands sent by a {ntpqman} program
+running in another machine. If this flag is enabled, which is the
+default case, new broadcast client and symmetric passive associations
+and remote configuration commands must be cryptographically
+authenticated using either symmetric key or public key cryptography. If
+this flag is disabled, these operations are effective even if not
+cryptographic authenticated. It should be understood that operating with
+theauthflag disabled invites a significant vulnerability where a rogue
+hacker can masquerade as a falseticker and seriously disrupt system
+timekeeping. It is important to note that this flag has no purpose other
+than to allow or disallow a new association in response to new broadcast
+and symmetric active messages and remote configuration commands and, in
+particular, the flag has no effect on the authentication process
+itself.
+
+An attractive alternative where multicast support is available is
+manycast mode, in which clients periodically troll for servers as
+described in the 'Automatic NTP Configuration Options' page of the Web
+documentation.  Either symmetric key or public key cryptographic
+authentication can be used in this mode. The principle advantage of
+manycast mode is that potential servers need not be configured in
+advance, since the client finds them during regular operation, and the
+configuration files for all clients can be identical.
+
+The security model and protocol schemes for symmetric key
+//and public key cryptography
+are summarized below; further details are in the
+briefings, papers and reports at the {project-fullname} page linked from
+{project-website}.
+
+[[symm]]
+=== Symmetric-Key Cryptography ===
+
+The original RFC-1305 specification allows any one of possibly 65,534
+keys, each distinguished by a 32-bit key identifier, to authenticate an
+association. The servers and clients involved must agree on the key and
+key identifier to authenticate NTP packets. Keys and related information
+are specified in a key file, usually called _{ntpkeys}_, 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 {ntpqman}
+utility program.
+
+When {ntpdman} is first started, it reads the key file specified
+in the keys configuration command and installs the keys in the key cache.
+However, individual keys must be activated with the trusted command before
+use. This allows, for instance, the installation of possibly several
+batches of keys and then activating or deactivating each batch remotely
+using {ntpqman}. This also provides a revocation capability
+that can be used if a key becomes compromised. The controlkey command
+selects the key used as the password for the {ntpqman} utility.
+
+//=== Public Key Cryptography ===
+//
+//NTPv4 supports the original NTPv3 symmetric key scheme described in
+//RFC-1305 and in addition the Autokey protocol, which is based on public
+//key cryptography. The Autokey Version 2 protocol described on the
+//Autokey Protocol page verifies packet integrity using MD5 message
+//digests and verifies the source with digital signatures and any of
+//several digest/signature schemes. Optional identity schemes described on
+//the Identity Schemes page and based on cryptographic challenge/response
+//algorithms are also available. Using all of these schemes provides
+//strong security against replay with or without modification, spoofing,
+//masquerade and most forms of clogging attacks.
+//
+////FIXME: page reference may be invalid
+//The Autokey protocol has several modes of operation corresponding to
+//the various NTP modes supported. Most modes use a special cookie which
+//can be computed independently by the client and server, but encrypted
+//in transmission. All modes use in addition a variant of the S-KEY
+//scheme, in which a pseudo-random key list is generated and used in
+//reverse order. These schemes are described along with an executive
+//summary, current status, briefing slides and reading list on the
+//"Autonomous Authentication" page.
+//
+//The specific cryptographic environment used by Autokey servers and
+//clients is determined by a set of files and soft links generated by the
+//{keygenman} program. This includes a required host key
+//file, required certificate file and optional sign key file, leapsecond
+//file and identity scheme files. The digest/signature scheme is specified
+//in the X.509 certificate along with the matching sign key. There are
+//several schemes available in the OpenSSL software library, each
+//identified by a specific string such as md5WithRSAEncryption, which
+//stands for the MD5 message digest with RSA encryption scheme. The
+//current NTP distribution supports all the schemes in the OpenSSL
+//library, including those based on RSA and DSA digital signatures.
+//
+//NTP secure groups can be used to define cryptographic compartments and
+//security hierarchies. It is important that every host in the group be
+//able to construct a certificate trail to one or more trusted hosts in
+//the same group. Each group host runs the Autokey protocol to obtain the
+//certificates for all hosts along the trail to one or more trusted hosts.
+//This requires the configuration file in all hosts to be engineered so
+//that, even under anticipated failure conditions, the NTP subnet will
+//form such that every group host can find a trail to at least one trusted
+//host.
+//
+//=== Naming and Addressing ===
+//
+//It is important to note that Autokey does not use DNS to resolve
+//addresses, since DNS can't be completely trusted until the name servers
+//have synchronized clocks. The cryptographic name used by Autokey to bind
+//the host identity credentials and cryptographic values must be
+//independent of interface, network and any other naming convention. The
+//name appears in the host certificate in either or both the subject and
+//issuer fields, so protection against DNS compromise is essential.
+//
+//By convention, the name of an Autokey host is the name returned by the
+//Unix gethostname(2) system call or equivalent in other systems. By the
+//system design model, there are no provisions to allow alternate names or
+//aliases. However, this is not to say that DNS aliases, different names
+//for each interface, etc., are constrained in any way.
+//
+//It is also important to note that Autokey verifies authenticity using
+//the host name, network address and public keys, all of which are bound
+//together by the protocol specifically to deflect masquerade attacks. For
+//this reason Autokey includes the source and destinatino IP addresses in
+//message digest computations and so the same addresses must be available
+//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.
+
+[[operation]]
+== Operation ==
+
+A specific combination of authentication scheme (none, symmetric key,
+public key) and identity scheme is called a cryptotype, although not all
+combinations are compatible. There may be management configurations
+where the clients, servers and peers may not all support the same
+cryptotypes. A secure NTP subnet can be configured in many ways while
+keeping in mind the principles explained above and in this section. Note
+however that some cryptotype combinations may successfully interoperate
+with each other, but may not represent good security practice.
+
+The cryptotype of an association is determined at the time of
+mobilization, either at configuration time or some time later when a
+message of appropriate cryptotype arrives. When mobilized by a `server`
+or `peer` configuration command and no `key` or `autokey` subcommands
+are present, the association is not authenticated; if the `key`
+subcommand is present, the association is authenticated using the
+symmetric key ID specified. I
+//If the `autokey` subcommand is present, the
+//association is authenticated using Autokey.
+//
+//When multiple identity schemes are supported in the Autokey protocol,
+//the first message exchange determines which one is used. The client
+//request message contains bits corresponding to which schemes it has
+//available. The server response message contains bits corresponding to
+//which schemes it has available. Both server and client match the
+//received bits with their own and select a common scheme.
+
+Following the principle that time is a public value, a server responds
+to any client packet that matches its cryptotype capabilities. Thus, a
+server receiving an unauthenticated packet will respond with an
+unauthenticated packet, while the same server receiving a packet of a
+cryptotype it supports will respond with packets of that cryptotype.
+However, unconfigured broadcast or manycast client associations or
+symmetric passive associations will not be mobilized unless the server
+supports a cryptotype compatible with the first packet received. By
+default, unauthenticated associations will not be mobilized unless
+overridden in a decidedly dangerous way.
+
+Some examples may help to reduce confusion. Client Alice has no specific
+cryptotype selected. Server Bob has a symmetric key file.
+//and minimal Autokey files.
+Alice's unauthenticated messages arrive at Bob,
+who replies with unauthenticated messages. Cathy has a copy of Bob's
+symmetric key file and has selected key ID 4 in messages to Bob. Bob
+verifies the message with his key ID 4. If it's the same key and the
+message is verified, Bob sends Cathy a reply authenticated with that
+key. If verification fails, Bob sends Cathy a thing called a crypto-NAK,
+which tells her something broke. She can see the evidence using the
+{ntpqman} program.
+
+//Denise has rolled her own host key and certificate. She also uses one of
+//the identity schemes as Bob. She sends the first Autokey message to Bob
+//and they both dance the protocol authentication and identity steps. If
+//all comes out okay, Denise and Bob continue as described above.
+
+It should be clear from the above that Bob can support all the girls at
+the same time, as long as he has compatible authentication and identity
+credentials. Now, Bob can act just like the girls in his own choice of
+servers; he can run multiple configured associations with multiple
+different servers (or the same server, although that might not be
+useful). But, wise security policy might preclude some cryptotype
+combinations; for instance, running an identity scheme with one server
+and no authentication with another might not be wise.
+
+[[keys]]
+== Key Management ==
+
+The cryptographic values used by the Autokey protocol are incorporated
+as a set of files generated by the {keygenman} utility
+program, including symmetric key, host key and public certificate files,
+as well as sign key, identity parameters and leapseconds files.
+Alternatively, host and sign keys and certificate files can be generated
+by the OpenSSL utilities and certificates can be imported from public
+certificate authorities. Note that symmetric keys are necessary for the
+{ntpqman} utility program. The remaining files are necessary only for
+the Autokey protocol.
+
+Certificates imported from OpenSSL or public certificate authorities
+have certain limitations. The certificate should be in ASN.1 syntax,
+X.509 Version 3 format and encoded in PEM, which is the same format used
+by OpenSSL. The overall length of the certificate encoded in ASN.1 must
+not exceed 1024 bytes. The subject distinguished name field (CN) is the
+fully qualified name of the host on which it is used; the remaining
+subject fields are ignored. The certificate extension fields must not
+contain either a subject key identifier or a issuer key identifier
+field; however, an extended key usage field for a trusted host must
+contain the value _trustRoot_;. Other extension fields are ignored.
+
+[[algorithms]]
+== Algorithms ==
+
 The NTPv3 specification (RFC-1305) defined an authentication scheme
 properly described as _symmetric key cryptography_. It used the Data
 Encryption Standard (DES) algorithm operating in cipher-block chaining
@@ -76,23 +336,24 @@ 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 considered 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, the OpenSSL application
-program, or the link:keygen.html[`{ntpkeygen}`] utility program in the
-NTP software distribution.
+//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 considered 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, the OpenSSL application
+//program, or the link:keygen.html[`{ntpkeygen}`] 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.
+(However, these restrictions have been considerably relaxed since 1996.)
 Builders outside the US are advised to obtain the OpenSSL library
 directly from OpenSSL, which is outside the US, and build outside the
 US.
@@ -110,15 +371,15 @@ responds with non-authenticated packets. If the client sends
 authenticated packets, the server responds with authenticated packets if
 correct, or a crypto-NAK packet if not.. In the case of unsolicited
 packets which might consume significant resources, such as broadcast or
-symmetric mode packets, , authentication is required, unless overridden
+symmetric mode packets, authentication is required, unless overridden
 by a `disable auth` command. In the current climate of targeted
 broadcast or "letterbomb" attacks, defeating this requirement would be
 decidedly dangerous. In any case, the `notrust `flag, described on the
 link:authopt.html[Access Control Options] page, can be used to disable
 access to all but correctly authenticated clients..
 
-[[symm]]
-== Symmetric Key Cryptography ==
+[[formats]]
+== Data Formats ==
 
 The original NTPv3 specification (RFC-1305), as well as the current
 NTPv4 specification (RFC-5905), allows any one of possibly 65,534
@@ -179,18 +440,18 @@ batches of keys and then activating a key remotely using `{ntpq}`.
 The `controlkey` command selects the key ID used as the password
 for the `{ntpq}` utility.
 
-[[windows]]
-== Microsoft Windows Authentication ==
-
-In addition to the above means, `{ntpd}` supports Microsoft Windows
-MS-SNTP authentication using Active Directory services. This support was
-contributed by the Samba Team and is still in development. It is enabled
-using the `mssntp` flag of the `restrict` command described on the
-link:accopt.html#restrict[Access Control Options] page. [red]#Note: Potential
-users should be aware that these services involve a TCP connection to
-another process that could potentially block, denying services to other
-users. Therefore, this flag should be used only for a dedicated server
-with no clients other than MS-SNTP.
+//[[windows]]
+//== Microsoft Windows Authentication ==
+//
+//In addition to the above means, `{ntpd}` supports Microsoft Windows
+//MS-SNTP authentication using Active Directory services. This support was
+//contributed by the Samba Team and is still in development. It is enabled
+//using the `mssntp` flag of the `restrict` command described on the
+//link:accopt.html#restrict[Access Control Options] page. [red]#Note: Potential
+//users should be aware that these services involve a TCP connection to
+//another process that could potentially block, denying services to other
+//users. Therefore, this flag should be used only for a dedicated server
+//with no clients other than MS-SNTP.
 
 [[pub]]
 == Public Key Cryptography ==
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index 841bd9b..ffb294d 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -92,274 +92,15 @@ include::../docs/assoc-options.txt[]
 
 include::../docs/assoc-auxcommands.txt[]
 
-== Authentication Support ==
-
-Authentication support allows the NTP client to verify that the server
-is in fact known and trusted and not an intruder intending accidentally
-or on purpose to masquerade as that server. The NTPv3 specification
-RFC-1305 defines a scheme which provides cryptographic authentication of
-received NTP packets. Originally, this was done using the Data
-Encryption Standard (DES) algorithm operating in Cipher Block Chaining
-(CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by
-the RSA Message Digest 5 (MD5) algorithm using a private key, commonly
-called keyed-MD5. Either algorithm computes a message digest, or one-way
-hash, which can be used to verify the server has the correct private key
-and key identifier.
-
-NTPv4 retains the NTPv3 scheme, properly described as symmetric key
-cryptography and, in addition, provides a new Autokey scheme based on
-public key cryptography. Public key cryptography is generally considered
-more secure than symmetric key cryptography, since the security is based
-on a private value which is generated by each server and never revealed.
-With Autokey all key distribution and management functions involve only
-public values, which considerably simplifies key distribution and
-storage. Public key management is based on X.509 certificates, which can
-be provided by commercial services or produced by utility programs in
-the OpenSSL software library or the NTPv4 distribution.
-
-//FIXME: page reference may be invalid
-While the algorithms for symmetric key cryptography are included in the
-NTPv4 distribution, public key cryptography requires the OpenSSL
-software library to be installed before building the NTP distribution.
-Directions for doing that are on the Building and Installing the
-Distribution page.
-
-Authentication is configured separately for each association using the
-`key` or `autokey` subcommand on the `peer`, `server`, `broadcast` and
-`manycastclient` configuration commands. The authentication options
-described below specify the locations of the key files, if other than
-default, which symmetric keys are trusted and the interval between
-various operations, if other than default.
-
-Authentication is always enabled, although ineffective if not configured
-as described below. If a NTP packet arrives including a message
-authentication code (MAC), it is accepted only if it passes all
-cryptographic checks. The checks require correct key ID, key value and
-message digest. If the packet has been modified in any way or replayed
-by an intruder, it will fail one or more of these checks and be
-discarded. Furthermore, the Autokey scheme requires a preliminary
-protocol exchange to obtain the server certificate, verify its
-credentials and initialize the protocol
-
-The `auth` flag controls whether new associations or remote
-configuration commands require cryptographic authentication. This flag
-can be set or reset by the `enable` and `disable` commands and also by
-remote configuration commands sent by a {ntpqman} program
-running in another machine. If this flag is enabled, which is the
-default case, new broadcast client and symmetric passive associations
-and remote configuration commands must be cryptographically
-authenticated using either symmetric key or public key cryptography. If
-this flag is disabled, these operations are effective even if not
-cryptographic authenticated. It should be understood that operating with
-theauthflag disabled invites a significant vulnerability where a rogue
-hacker can masquerade as a falseticker and seriously disrupt system
-timekeeping. It is important to note that this flag has no purpose other
-than to allow or disallow a new association in response to new broadcast
-and symmetric active messages and remote configuration commands and, in
-particular, the flag has no effect on the authentication process
-itself.
-
-An attractive alternative where multicast support is available is
-manycast mode, in which clients periodically troll for servers as
-described in the 'Automatic NTP Configuration Options' page of the Web
-documentation.  Either symmetric key or public key cryptographic
-authentication can be used in this mode. The principle advantage of
-manycast mode is that potential servers need not be configured in
-advance, since the client finds them during regular operation, and the
-configuration files for all clients can be identical.
-
-The security model and protocol schemes for both symmetric key and
-public key cryptography are summarized below; further details are in the
-briefings, papers and reports at the {project-fullname} page linked from
-{project-website}.
-
-=== Symmetric-Key Cryptography ===
-
-The original RFC-1305 specification allows any one of possibly 65,534
-keys, each distinguished by a 32-bit key identifier, to authenticate an
-association. The servers and clients involved must agree on the key and
-key identifier to authenticate NTP packets. Keys and related information
-are specified in a key file, usually called _{ntpkeys}_, 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 {ntpqman}
-utility program.
-
-When {ntpdman} is first started, it reads the key file specified
-in the keys configuration command and installs the keys in the key cache.
-However, individual keys must be activated with the trusted command before
-use. This allows, for instance, the installation of possibly several
-batches of keys and then activating or deactivating each batch remotely
-using {ntpqman}. This also provides a revocation capability
-that can be used if a key becomes compromised. The controlkey command
-selects the key used as the password for the {ntpqman} utility.
-
-=== Public Key Cryptography ===
-
-NTPv4 supports the original NTPv3 symmetric key scheme described in
-RFC-1305 and in addition the Autokey protocol, which is based on public
-key cryptography. The Autokey Version 2 protocol described on the
-Autokey Protocol page verifies packet integrity using MD5 message
-digests and verifies the source with digital signatures and any of
-several digest/signature schemes. Optional identity schemes described on
-the Identity Schemes page and based on cryptographic challenge/response
-algorithms are also available. Using all of these schemes provides
-strong security against replay with or without modification, spoofing,
-masquerade and most forms of clogging attacks.
-
-//FIXME: page reference may be invalid
-The Autokey protocol has several modes of operation corresponding to
-the various NTP modes supported. Most modes use a special cookie which
-can be computed independently by the client and server, but encrypted
-in transmission. All modes use in addition a variant of the S-KEY
-scheme, in which a pseudo-random key list is generated and used in
-reverse order. These schemes are described along with an executive
-summary, current status, briefing slides and reading list on the
-"Autonomous Authentication" page.
-
-The specific cryptographic environment used by Autokey servers and
-clients is determined by a set of files and soft links generated by the
-{keygenman} program. This includes a required host key
-file, required certificate file and optional sign key file, leapsecond
-file and identity scheme files. The digest/signature scheme is specified
-in the X.509 certificate along with the matching sign key. There are
-several schemes available in the OpenSSL software library, each
-identified by a specific string such as md5WithRSAEncryption, which
-stands for the MD5 message digest with RSA encryption scheme. The
-current NTP distribution supports all the schemes in the OpenSSL
-library, including those based on RSA and DSA digital signatures.
-
-NTP secure groups can be used to define cryptographic compartments and
-security hierarchies. It is important that every host in the group be
-able to construct a certificate trail to one or more trusted hosts in
-the same group. Each group host runs the Autokey protocol to obtain the
-certificates for all hosts along the trail to one or more trusted hosts.
-This requires the configuration file in all hosts to be engineered so
-that, even under anticipated failure conditions, the NTP subnet will
-form such that every group host can find a trail to at least one trusted
-host.
-
-=== Naming and Addressing ===
-
-It is important to note that Autokey does not use DNS to resolve
-addresses, since DNS can't be completely trusted until the name servers
-have synchronized clocks. The cryptographic name used by Autokey to bind
-the host identity credentials and cryptographic values must be
-independent of interface, network and any other naming convention. The
-name appears in the host certificate in either or both the subject and
-issuer fields, so protection against DNS compromise is essential.
-
-By convention, the name of an Autokey host is the name returned by the
-Unix gethostname(2) system call or equivalent in other systems. By the
-system design model, there are no provisions to allow alternate names or
-aliases. However, this is not to say that DNS aliases, different names
-for each interface, etc., are constrained in any way.
-
-It is also important to note that Autokey verifies authenticity using
-the host name, network address and public keys, all of which are bound
-together by the protocol specifically to deflect masquerade attacks. For
-this reason Autokey includes the source and destinatino IP addresses in
-message digest computations and so the same addresses must be available
-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.
-
-== Operation
-
-A specific combination of authentication scheme (none, symmetric key,
-public key) and identity scheme is called a cryptotype, although not all
-combinations are compatible. There may be management configurations
-where the clients, servers and peers may not all support the same
-cryptotypes. A secure NTPv4 subnet can be configured in many ways while
-keeping in mind the principles explained above and in this section. Note
-however that some cryptotype combinations may successfully interoperate
-with each other, but may not represent good security practice.
-
-The cryptotype of an association is determined at the time of
-mobilization, either at configuration time or some time later when a
-message of appropriate cryptotype arrives. When mobilized by a `server`
-or `peer` configuration command and no `key` or `autokey` subcommands
-are present, the association is not authenticated; if the `key`
-subcommand is present, the association is authenticated using the
-symmetric key ID specified; if the `autokey` subcommand is present, the
-association is authenticated using Autokey.
-
-When multiple identity schemes are supported in the Autokey protocol,
-the first message exchange determines which one is used. The client
-request message contains bits corresponding to which schemes it has
-available. The server response message contains bits corresponding to
-which schemes it has available. Both server and client match the
-received bits with their own and select a common scheme.
-
-Following the principle that time is a public value, a server responds
-to any client packet that matches its cryptotype capabilities. Thus, a
-server receiving an unauthenticated packet will respond with an
-unauthenticated packet, while the same server receiving a packet of a
-cryptotype it supports will respond with packets of that cryptotype.
-However, unconfigured broadcast or manycast client associations or
-symmetric passive associations will not be mobilized unless the server
-supports a cryptotype compatible with the first packet received. By
-default, unauthenticated associations will not be mobilized unless
-overridden in a decidedly dangerous way.
-
-Some examples may help to reduce confusion. Client Alice has no specific
-cryptotype selected. Server Bob has both a symmetric key file and
-minimal Autokey files. Alice's unauthenticated messages arrive at Bob,
-who replies with unauthenticated messages. Cathy has a copy of Bob's
-symmetric key file and has selected key ID 4 in messages to Bob. Bob
-verifies the message with his key ID 4. If it's the same key and the
-message is verified, Bob sends Cathy a reply authenticated with that
-key. If verification fails, Bob sends Cathy a thing called a crypto-NAK,
-which tells her something broke. She can see the evidence using the
-{ntpqman} program.
-
-Denise has rolled her own host key and certificate. She also uses one of
-the identity schemes as Bob. She sends the first Autokey message to Bob
-and they both dance the protocol authentication and identity steps. If
-all comes out okay, Denise and Bob continue as described above.
-
-It should be clear from the above that Bob can support all the girls at
-the same time, as long as he has compatible authentication and identity
-credentials. Now, Bob can act just like the girls in his own choice of
-servers; he can run multiple configured associations with multiple
-different servers (or the same server, although that might not be
-useful). But, wise security policy might preclude some cryptotype
-combinations; for instance, running an identity scheme with one server
-and no authentication with another might not be wise.
-
-== Key Management
-
-The cryptographic values used by the Autokey protocol are incorporated
-as a set of files generated by the {keygenman} utility
-program, including symmetric key, host key and public certificate files,
-as well as sign key, identity parameters and leapseconds files.
-Alternatively, host and sign keys and certificate files can be generated
-by the OpenSSL utilities and certificates can be imported from public
-certificate authorities. Note that symmetric keys are necessary for the
-{ntpqman} utility program. The remaining files are necessary only for
-the Autokey protocol.
-
-Certificates imported from OpenSSL or public certificate authorities
-have certian limitations. The certificate should be in ASN.1 syntax,
-X.509 Version 3 format and encoded in PEM, which is the same format used
-by OpenSSL. The overall length of the certificate encoded in ASN.1 must
-not exceed 1024 bytes. The subject distinguished name field (CN) is the
-fully qualified name of the host on which it is used; the remaining
-subject fields are ignored. The certificate extension fields must not
-contain either a subject key identifier or a issuer key identifier
-field; however, an extended key usage field for a trusted host must
-contain the value _trustRoot_;. Other extension fields are ignored.
-
 == Authentication Commands ==
 
-`autokey` [_logsec_]::
-  Specifies the interval between regenerations of the session key list
-  used with the Autokey protocol. Note that the size of the key list for
-  each association depends on this interval and the current poll
-  interval. The default value is 12 (4096 s or about 1.1 hours). For
-  poll intervals above the specified interval, a session key list with a
-  single entry will be regenerated for every message sent.
+//`autokey` [_logsec_]::
+//  Specifies the interval between regenerations of the session key list
+//  used with the Autokey protocol. Note that the size of the key list for
+//  each association depends on this interval and the current poll
+//  interval. The default value is 12 (4096 s or about 1.1 hours). For
+//  poll intervals above the specified interval, a session key list with a
+//  single entry will be regenerated for every message sent.
 
 `controlkey` _key_::
   Specifies the key identifier to use with the
diff --git a/scripts/README b/scripts/README
index 41ed17e..3367f3a 100644
--- a/scripts/README
+++ b/scripts/README
@@ -39,4 +39,7 @@ summary::	Generate summary files out of stat files produced by NTP
 
 t::		Tests for the scripts.
 
+update-leap::	Script to update the leap-second from the NIST leapsecond file.
+		Meant to be run from a cron job.
+
 // end