### Authentication Options

from Alice's Adventures in Wonderland, Lewis Carroll

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

#### 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 augmented 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.

Authentication is configured separately for each association using the `key` or `autokey` subcommand on the `peer`, `server`, `broadcast` and `manycastclient` configuration commands as described in the Configuration Options page. The authentication options described below specify the suite of keys, select the key for each configured association and manage the configuration operations. In addition, if public key cryptography is enabled, the commands specify the message digest and signature encryption scheme.

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 `ntpdc` 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 schemes. If this flag is disabled, these operations are effective even if not cryptographic authenticated. It should be understood that operating in the latter mode invites a significant vulnerability where a rogue hacker can seriously disrupt system timekeeping.

In networks with firewalls and large numbers of broadcast clients it may be acceptable to disable authentication, since that avoids key distribution and simplifies network maintenance. However, when the configuration file contains host names, or when a server or client is configured remotely, host names are resolved using the DNS and a separate name resolution process. In order to protect against bogus configuration messages, name resolution messages are authenticated using an internally generated key which is normally invisible to the user. However, if cryptographic support is disabled, the name resolution process will fail. This can be avoided either by specifying IP addresses instead of host names, which is generally inadvisable, or by enabling the `auth`flag for name resolution and disabled it once the name resolution process is complete.

An attractive alternative where multicast support is available is manycast mode, in which clients periodically troll for servers as described in the Association Management page. . Cryptographic authentication in this mode the Autokey protocol described below. 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.

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. Public key cryptography provides secure authentication of servers without compromising accuracy and stability. The security model and protocol schemes for both symmetric key and public key cryptography are summarized below and detailed in the briefings, papers and reports at www.ntp.org.

#### 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 their messages. Keys and related information are specified in a key file, usually called `ntp.keys`, which must be exchanged and stored using secure procedures 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.

When `ntpd` 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 `ntpdc`. This also provides a revocation capability that can be used if a key becomes compromised. The `requestkey` command selects the key used as the password for the `ntpdc` utility, while the `controlkey` command selects the key used as the password for the `ntpq` 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 verifies packet integrity using MD5 message digests and verifies the source with digital signatures and any of several digest/signature schemes available in the OpenSSL software library. 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 interface routines required.

The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. Digital signatures with any of several message digest and signature encryption schemes are used in all modes to verify that the server is authentic and not an intruder. 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. This includes a host key file, certificate file and optional sign file and leapsecond file. The digest/signature scheme is specified in the X.509 certificate configured during installation along with the matching sign key. There are several schemes available in the OpenSSL software library, each identified by a specific string such as `RSA_MD5`, 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. The schemes currently available are described in the `ntp-genkeys` page.

The digest/signature scheme and certificate are provided to dependent clients in the Autokey protocol. Different client or peer associations can use different schemes; each of two symmetric peers can use different schemes. Note that the digest/signature scheme is separate and distinct from the NTP message digest used to construct the packet message authentication code (MAC). The only requirement is that the server private key and signature algorithm must match the public key and verification algorithm specified in the certificate.

#### Key Management

The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the `ntp-genkeys` utility program, including the required symmetric keys, host key pair and public certificate files and optional sign key and leapseconds files. The symmetric keys file is necessary for the `ntpq` and `ntpdc` utility programs. The remaining files are necessary for the Autokey protocols to function. The files incorporate cryptographic values generated by the OpenSSL library algorithms and are in printable PEM-encoded ASCII format. Further information about these files and how they are generated and installed is on the `ntp-genkeys` page.

All key files are installed by default in `/usr/local/etc`, which is normally in a shared filesystem in NFS-mounted networks and avoids installing them in each machine separately. The default can be overridden by the `keysdir` configuration command. Since uniqueness is insured by the hostname and filestamp extensions in the file name, the files for a NFS server and dependent clients can all be installed in the same directory. This is different than the original Autokey version 1 support, which required the private key to be installed separately for each client.

The recommended practice is to keep the file name extensions when installing a file and to install a soft link from the default name specified in the `ntp-genkeys` page to the actual file. This allows new file generations to be activated simply by changing the link. However, `ntpd` parses the link name when present to extract the filestamp and sends it along with the public key and host name when requested. This allows clients to verify that the file and generation time are always current. The actual location of each file can be overridden by the `crypto` configuration command, but this is not recommended.

All cryptographic keys and related values should be regenerated on a periodic and automatic basis, like once per month. The `ntp-genkeys` program uses the same timestamp extension for all files generated at one time, so each generation is distinct and can be readily recognized in monitoring data. While a host key pair and certificate must be generated by every server and peer, the certificates do not need to be explicitly copied to all machines in the same security compartment, since they can be obtained automatically using the Autokey protocol.

Servers and peers can make a new generation in the following way. All machines have loaded the old generation at startup and are operating normally. At designated intervals, each machine generates a new public/private key pair and certificate and makes links from the default file names to the new file names. The `ntpd` daemon is then restarted and loads the new generation, with result clients no longer can authenticate correctly. The Autokey protocol is designed so that after a few minutes the clients time out and restart the protocol from the beginning, with result the new generation is loaded and operation continues as before.

#### Random Seed File

All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal random number generator of the library. It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources. Suitable means are described in the OpenSSL software documentation, but are outside the scope of this page.

The entropy seed used by the OpenSSL library is contained in a file, usually called `.rnd`, which must be available when starting the NTP daemon or the `ntp-genkeys` program. The NTP daemon will first look for the file using the path specified by the `random` subcommand of the `crypto` command. If not specified in this way, or when starting the `ntp-genkeys` program, the OpenSSL library will look for the file using the path specified by the `$RANDFILE` environment variable in the user home directory, whether root or some other user. If the `$RANDFILE` environment variable is not present, the library will look for the `.rnd` file in the user home directory. If the file is not available or cannot be written, the daemon exits with a message to the system log and the `ntp-genkeys` program exits with a suitable error message.

The daemon will occasionally add additional entropy and write to the file when computing a Diffie-Hellman agreement value, for example, so the file must be writable by root. If the `ntp-genkeys` program is run by other than root, or if the Unix `su` command is used to assume root, the home directory assumed by the OpenSSL library might not be root. Probably the safest way to generate keys is to log in as root, change to the keys directory and run the `ntp-genkeys` program from there

#### 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.
`controlkey key`
  Specifies the key identifier to use with the `ntpq` utility, which uses the standard protocol defined in RFC-1305. The `key` argument is the key identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive.
`crypto [certificate file] [leap file] [randfile file] [rsakey file] [signkey file]`
  This command requires the OpenSSL library. It activates public key cryptography, selects the message digest and signature encryption scheme and loads the required private and public values described above. If one or more files are left unspecified, the default names are used as described above. Following are the subcommands:
  `certificate file`
    Specifies the location of the public certificate file, which by default is linked from `ntpkey_cert_hostname` in the keys directory.
  `leap file`
    Specifies the location of the optional leapsecond table file, which by default is linked from `ntpkey_leap` in the keys directory.
  `randfile file`
    Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above.
  `rsakey file`
    Specifies the location of the public/private key file, which by default is linked from `ntpkey_key_hostname` in the keys directory.
  `signkey file`
    Specifies the location of the optional sign key file used to construct digital signatures, which by default is linked from `ntpkey_sign_hostname` in the keys directory. If this file is not present, the `rsakey` file is used.
`keys keyfile`
  Specifies the location of the MD5 symmetric key file containing the keys and key identifiers used by `ntpd`, `ntpq` and `ntpdc` when operating with symmetric key cryptography.
`keysdir path`
  This command requires the OpenSSL library. It specifies the default directory path for the cryptographic files generated by the `ntp-genkeys` program. The default is `/usr/local/etc/`.
`requestkey key`
  Specifies the key identifier to use with the `ntpdc` utility program, which uses a proprietary protocol specific to this implementation of `ntpd`. The `key` argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive.
`revoke [logsec]`
  Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms of the scheme; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent.
`trustedkey key [...]`
  Specifies the key identifiers which are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the `ntpq` and `ntpdc` programs. The authentication procedures require that both the local and remote servers share the same key and key identifier for this purpose, although different keys can be used with different servers. The `key` arguments are 32-bit unsigned integers with values from 1 to 65,534.

#### Error Codes

The following error codes are reported via the NTP control and monitoring protocol trap mechanism.

101 (bad field length)
  The packet has invalid version, length or format.
102 (bad timestamp)
  The packet timestamp is the same or older than the most recent received. This could be due to a replay or a server clock time step.
103 (bad filestamp)
  The packet filestamp is the same or older than the most recent received. This could be due to a replay or a key file generation error.
104 (bad public key)
  The public key is missing, has incorrect format or is an unsupported type.
105 (unsupported digest type)
  The server requires an unsupported digest/signature scheme.
106 (mismatched digest types)
  Not used.
107 (bad signature length)
  The signature length does not match the current public key.
108 (signature not verified)
  The message fails the signature check. It could be bogus or signed by a different private key.
109 (subject hostname mismatch)
  The host name is invalid or does not match the subject name in the certificate.
110 (time not verified)
  The certificate is not yet valid or has expired.
111 (bad cookie encrypt)
  The cookie is corrupted or bogus.
112 (bad TAI data)
  The leapseconds file is currupted or bogus.

#### Files

See the `ntp-genkeys` page.

#### Bugs

The mysterious Digital Signature Algorithm (DSA) in the OpenSSL library should be conquered and provisioned.