### Authentication Options

from Alice's Adventures in Wonderland, Lewis Carroll

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

Last update: 02:38 UTC Monday, March 17, 2008

#### Related Links

#### Table of Contents

- Introduction
- Symmetric Key Cryptography
- Public Key Cryptography
- NTP Secure Groups
- Identity Schemes and Cryptotypes
- Configuration
- Examples
- Authentication Commands
- Error Codes
- Files

#### Introduction

This page describes the various cryptographic authentication provisions in NTPv4. Details about the configuration commands and options are given on the Configuration Options page. Details about the cryptographic authentication schemes are given on the Authentication Options page. Details about the automatic server discovery schemes are described on the Automatic Server Discovery Schemes page. Additional information is available in the papers, reports, memoranda and briefings on the NTP Project page.

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. The NTPv3 specification RFC-1305 defines a scheme using the Data Encryption Standard (DES) algorithm, commonly called DES-CBC. Subsequently, this scheme 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 as the server.

NTPv4 includes the NTPv3 scheme, properly described as symmetric key cryptography and, in addition a new scheme based on public key cryptography and called Autokey. 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, utility programs in the OpenSSL software library or a utility program in the NTP software distribution.

While the algorithms for symmetric key cryptography are included in the NTPv4 software distribution, Autokey cryptography requires the OpenSSL software library to be installed before building the NTP distribution. 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.

Authentication is configured separately for each association using the `key` or `autokey` option of the `server` 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.

#### 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 and key ID to authenticate NTP packets. If an NTP packet includes a message authentication code (MAC), consisting of a key ID and message digest, it is accepted only if the key ID matches a trusted key and the message digest is verified with this key.

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 using an ordinary text editor.

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

#### Public Key Cryptography

NTPv4 supports the Autokey security 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 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.

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.

#### 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 but different host names. The string specified in the `host` option of the `crypto` command is the name of the host and the name of the host key, sign key and certificate files. The string specified in the `ident` option of the `crypto` comand is the group name of all group hosts and the name of 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 trusted certificate. The host name is used in these fields 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. 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.

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

A specific combination of authentication and identity schemes is called a 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 interoperate with each other, but may not represent good security practice. The server and client cryptotypes are defined by the the following codes.

NONE
  A client or server is type NONE if authentication is not available or not configured. Packets exchanged between client and server have no MAC.
AUTH
  A client or server is type AUTH if the `key` option is specified with the `server` configuration command and the client and server keys are compatible. Packets exchanged between clients and servers have a MAC.
PC
  A client or server is type PC if the `autokey` option is specified with the `server` configuration command and compatible host key and private certificate files are present. Packets exchanged between clients and servers have a MAC.
TC
  A client or server is type TC if the `autokey` option is specified with the `server` configuration command and compatible host key and public certificate files are present. Packets exchanged between clients and servers have a MAC.
IDENT
  A client or server is type IDENT if the `autokey` option is specified with the `server` configuration command and compatible host key, public certificate and identity scheme files are present. Packets exchanged between clients and servers have a MAC.

The compatible cryptotypes for clients and servers are listed in the following table.

Client | Server
NONE | AUTH | PC | TC | IDENT
NONE | yes | yes* | yes* | yes* | yes*
AUTH | no | yes | no | no | no
PC | no | no | yes | no | no
TC | no | no | no | yes | yes
IDENT | no | no | no | no | yes

* These combinations are not valid if the restriction list includes the `notrust` option.

#### Configuration

Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of an unnamed secure group with one TH at the lowest stratum. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the `ntp-keygen -T` command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the `crypto` configuration command with no options. Configuration with passwords is described in the ntp-keygen page

When an identity scheme is included, for example IFF, the TH generates host key, trusted certificate and private server identity files using the `ntp-keygen -T -I -i group` command, where `group` is the group name. The reemaining group hosts use the same command as above. The client identity files are obtained separately. All hosts use the `crypto ident group` configuration command.

Hosts with no dependent clients can retrieve client files from an archive or web page. The `ntp-keygen` can export these data using the `-e` option. Hosts with dependent clients other than the TH must retrieve copies of the server files using secure means. The `ntp-keygen` can export these data using the `-q` option. In either case the data are installed as a file and then renamed using the name given as the first line in the file, but without the filestamp.

#### Examples

Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. TH mort of RED and TH macabre of BLUE run NTP symmetric mode with each other for monitoring or backup. GREEN is typical of a large university providing certified time to the campus community. TH howland of GREEN is a client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys.

BLUE TH macabre uses configuration commands

`crypto pw qqsv ident blue
peer mort autokey`

where `qqsv` is the password for macabre files. It generates BLUE files using the commands

`ntp-keygen -p qqsv -T -G -i blue
ntp-keygen -p qqsv -e >ntpkey_gqpar_blue`

The first line generates the host, trusted certificate and private GQ server files. The second generates the public GQ client file, which can have any nonconflicting mnemonic name.

RED TH mort uses configuration commands

`crypto pw xxx ident red
peer macabre autokey`

where `xxx` is the password for mort files. It generates RED files using the commands

`ntp-keygen -p xxx -T -I -i red
ntp-keygen -p xxx -e >ntpkey_iffpar_red`

GREEN TH howland uses configuration commands

`crypto pw yyy ident green
` `server mort autokey
` `server macabre autokey`

where `yyy` is the password for howland files. It generates GREEN files using the commands

`ntp-keygen -p yyy -T -G -i green
ntp-keygen -p yyy -e >ntpkey_gqpar_green
` `ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green`

The first two lines serve the same purpose as the preceeding examples. The third line generats a copy of the private GREEN server file for use on another server in the same group, but encrypted with the `zzz` pasword.

A client of GREEN, for example, uses the configuration commands

`crypto pw abc ident green
` `server howland autokey`

where `abc` is the password for its files. It generates files using the command

`ntp-keygen -p abc`

The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server file from the TH of that group, but it is encrypted and so can be sent using nonsecured means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.

In another example mort and macabre are operated as broadcast servers and howland as a broadcast client. Replace the server configuration command for both mort and macabre with the two commands

`broadcast ipaddr autokey
broadcastclient`

where `ipaddr` is the broadast address, and replace the two server commands for howland with the single command

`broadcastclient`

Note that if servers of different groups, in this case RED and BLUE, share the same broadcast media, each server must have client files for all groups other than its own, while each client must have client files for all groups.

#### Authentication Commands

`autokey [logsec]`
  Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). 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 ID to use with the `ntpq` utility, which uses the standard protocol defined in RFC-1305. The `key` argument is the key ID for a trusted key, where the value can be in the range 1 to 65,534, inclusive.
`crypto [randfile file] [host name] [ident name] [pw password]`
  This command requires the OpenSSL library. It activates public key cryptography and loads the required host key and public certificat. If one or more files are left unspecified, the default names are used as described below. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the `keysdir` configuration command or default `/usr/local/etc`. Following are the options.
  `host name`
    Specifies the string used when constructing the names for the host, sign and certificate files generated by the `ntp-keygen` program with the `-s name` option.
  `ident name`
    Specifies the string used in constructing the identity files generated by the `ntp-keygen` program with the `-i name` option.
  `pw password`
    Specifies the password to decrypt files previously encrypted by the `ntp-keygen` program with the `-p` option.
  `randfile file`
    Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the `ntp-keygen` page.
`keys keyfile`
  Specifies the complete path to the MD5 key file containing the keys and key IDs used by `ntpd`, `ntpq` and `ntpdc` when operating with symmetric key cryptography. This is the same operation as the `-k` command line option.
`keysdir path`
  This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is `/usr/local/etc/`.
`requestkey key`
  Specifies the key ID to use with the `ntpdc` utility program, which uses a proprietary protocol specific to this implementation of `ntpd`. The `key` argument is a key ID 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; however, updating some values is a relatively expensive operation. The default interval is 17 (about 36 h). For poll intervals above the specified interval, the values will be updated for every message sent.
`trustedkey key [...]`
  Specifies the key ID 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 ID for this purpose, although different keys can be used with different servers.

#### Error Codes

Errors can occur due to mismatched configurations, unexpected restarts, expired certificates and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errors is expired certificates, which must be regenerated and signed at least once per year using the `ntp-keygen` program.

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

101 (bad field format or 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 or missing 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 (unsupported identity type)
  The client or server has requested an identity scheme the other does not support.
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 (certificate not verified)
  The certificate is invalid or signed with the wrong key.
110 (host certificate expired)
  The old server certificate has expired.
111 (bad or missing cookie)
  The cookie is missing, corrupted or bogus.
112 (bad or missing leapseconds table)
  The leapseconds table is missing, corrupted or bogus.
113 (bad or missing certificate)
  The certificate is missing, corrupted or bogus.
114 (bad or missing group key)
  The identity key is missing, corrupt or bogus.
115 (protocol error)
  The protocol state machine has wedged due to unexpected restart
116 (server certificate expired)
  The old server certificate has expired.

#### Files

See the `ntp-keygen` page. Note that provisions to load leap second values from the NIST files have been removed. These provisions are now available whether or not the OpenSSL library is available. However, the functions that can download these values from servers remains available.