### Autokey Public-Key Authentication

Last update: 02-Nov-2010 19:13 UTC

#### Table of Contents

- Introduction
- NTP Secure Groups
- Identity Schemes and Cryptotypes
- Configuration
- Examples

#### Introduction

This distribution includes support for the Autokey public key algorithms and protocol specified in RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This support is available only if the OpenSSL library has been installed and the `--enable-autokey` option is specified 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, 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 message digest algorithms, such as MD5 or SHA, and verifies the source using any of several digital signature schemes, including RSA and DSA. Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. These schemes provide strong security against 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.

#### Configuration

The Trusted Certificate (TC) is recommended for national NTP time services, such as those operated by NIST and USNO. Configuration for TC is very simple. For each server as root:

`# cd /usr/local/etc
# ntp-keygen -T`

This generates an RSA private/public key pair and a self-signed certificate for the RSA digital signature algorithm with the MD5 message digest algoirhtm. Include in the `ntp.conf` configuration file something like

`# disable kernel
# server 127.127.18.1 minpoll 12 maxpoll 17 # ACTS modem
# phone atdt913035547785 atddt913034944774
# crypto
# driftfile /etc/nto.drift.`

Note the first three lines are specific to the ACTS driver and NIST phone numbers. The second number will be tried if the first times out. Any other reference clock can be used, or even another time server.

For each client as root,

`# cd /usr/local/etc
# ntp-keygen`

(There is no -`T` option). Include in the `ntp.conf` configuration file for a client such as grundoon.udel.edu something like

`# server time.nist.gov iburst
# crypto
# driftfile /etc/nto.drift.`

It is possible to configure client hosts of server grundoon in the same way with the server line pointing to grundoon. Dependent clients authenticate to time.nistg.gov through grundoon.udel.edu.

In the above configuration examples, the default autokey host name is the string returned by the Unix gethostbyname() library routine. The host name is used as the subject and issuer names on the certificate, as well as the default deault password for the host key and certificate files. The host name can be chaned using the -s option with the ntp-keygen program. The default password can be changed using the -p optoin for the ntp-keygen and the pw option of the crypto command.

It is important to note that certificates have a defined lifetime of one year from the time of creation. Sometime toward the end of the liftetime period, it is necessary to create a new certificat at both the server and client. For each server and client as root:

`# ntp_keygen`

The options are copied from the current certificarte.

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

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 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 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 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 a TH where the host name of the TH is also the name of the group. 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. All group hosts are configured as an acyclic tree with root the TH.

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

Hosts with no dependent clients can retrieve client parameter 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 key 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. As shown ion the figure, RED TH mort and BLUE TH macabre run NTP symmetric mode with each other for monitoring or backup. For the purpose of illustration, assume both THs are primary servers. GREEN is typical of a large university providing certified time to the campus community. GREEN TH howland is a broadcast client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys. YELLOW is a client of GREEN and for purposes of illustration a TH for YELLOW.

The BLUE TH macabre uses configuration commands

`crypto pw qqsv ident blue`
`peer mort autokey`
`broadcast address autokey`

where `qqsv` is the password for macabre files and address is the broadcast address for the local LAN. 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 keys file. The second generates the public GQ client parameters file, which can have any nonconflicting mnemonic name.

The RED TH mort uses configuration commands

`crypto pw xxx ident red`
`peer macabre autokey`
`broadcast address 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`

The GREEN TH howland uses configuration commands

`crypto pw yyy ident green`
`broadcastclient`

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 preceding examples. The third line generates a copy of the private GREEN server file for use on another server in the same group, say YELLOW, but encrypted with the `zzz` password.

A client of GREEN, for example YELLOW, 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 keys file from the TH of that group, but it is encrypted and so must be sent using secure means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.

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. Note also that this scenario is for illustration only and probably would not be wise for practical use, as if one of the TH reference clocks fails, the certificate trail becomes cyclic. In such cases the symmetric path between RED and BLUE, each in a different group, would not be a good idea.

#### Error Codes

Errors can occur due to mismatched configurations, unexpected protocol 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` - generate public and private keys program.

The following error codes are reported via the NTP control and monitoring protocol trap mechanism and to the `cryptostats` monitoring file if configured.

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.

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