# ntp.keys - NTP symmetric key file format

| from Alice’s Adventures in Wonderland, Lewis Carroll Three can keep a secret, if two are dead.

## 1. Manual Pages

### 1.1. Manual Pages

- `ntp.conf(5)` - ntpd Configuration File

- `ntp.keys(5)` - NTP symmetric key file format

- `ntpd(8)` - Network Time Protocol (NTP) daemon

- `ntpdig(1)` - Simple Network Time Protocol (SNTP) client

- `ntpfrob(8)` - frob the local clock hardware

- `ntpkeygen(8)` - generate public and private keys

- `ntpleapfetch(8)` fetch and manage leap-offset file

- `ntploggps(1)` - log gpsd data for use by ntpviz

- `ntplogtemp(1)` - log system temperature data for use by ntpviz

- `ntpmon(1)` - real-time NTP status monitor

- `ntpq(1)` - standard NTP query program

- `ntpsnmp(1)` - an AgentX Simple Network Management Protocol sub-agent [`experimental`]

- `ntpsweep(1)` - print information about given NTP servers

- `ntptime(8)` - read and set kernel time variables

- `ntptrace(1)` - trace a chain of NTP servers back to the primary source

- `ntpviz(1)` - make offset, jitter, and other plots from logfiles

- `ntpwait(8)` - wait until ntpd is in synchronized state

## 2. Table of Contents

- DESCRIPTION

- USAGE

- FILES

- SEE ALSO

## 3. DESCRIPTION

This document describes the format of an NTP symmetric key file. For a description of the use of this type of file, see the "Authentication Support" page of the Web documentation.

ntpd(8) reads its keys from a file specified using the -k command line option or the keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more keys numbered between 1 and 65535 may be arbitrarily set in the keys file.

The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form

    keyno type key

where `keyno` is a positive integer (between 1 and 65535), `type` is the message digest or cipher algorithm, and `key` is the key itself.

The file does not need to be sorted by `keyno`.

`type` can be the name of any digest or cipher supported by your OpenSSL package. Digests or CMACs longer than 20 bytes will be truncated.

You can get a list from `openssl list -digest-algorithms` or `openssl list -cipher-algorithms`. (As of Jan 2018, they lie. Be sure to try it. ntpd(8) will print an error on startup if a selected type isn’t supported.)

AES-128 is recommended by RFC 8573. Most modern CPUs have hardware support.

Only the `-CBC` cipher modes are useful. The `-CBC` is appended to the `type` internally. Do not include it in `type`.

AES is an alias for AES-128.

SHA-1 is an alias for SHA1. (NIST uses SHA-1. OpenSSL uses SHA1.)

Note that MD5 was deprecated by RFC 8573 in June of 2019. `AES-128` is currently preferred. Most modern CPUs have hardware support. Our code still supports MD5 for backwards compatibility.

FIPS 140-2, FIPS 180-4, and/or FIPS 202 may restrict your choices. If it matters to you, check with your lawyer. (Let us know if you find a good reference.) In particular, they don’t allow MD5.

The `key` may be printable ASCII excluding "#" or hex encoded. Keys longer than 20 characters are assumed to be hex. The max length of a (de-hexified) key is 32 bytes. If you want to use an ASCII key longer than 20 bytes, you must hexify it.

Note that the keys used by the ntpq(1) programs are checked against passwords entered by hand, so it is generally appropriate to specify these keys in ASCII format. Or you can cut-paste a hex string from your password manager.

## 4. USAGE

In order to use symmetric keys, the client side configuration file needs:

      keys <path-to-client-keys-file>
      trustedkey <keyno>
      server ... key <keyno>

The server side needs:

      keys <path-to-server-keys-file>
      trustedkey <keyno>

Note that the client and server key files must both contain identical copies of the line specified by keyno.

## 5. FILES

`/etc/ntp.keys`

  is a common location for the keys file

Reminder: You have to keep it secret.

## 6. SEE ALSO

ntp.conf(5), ntpd(8), ntpq(1), ntpkeygen(8), ntpdig(1).

Home Page | Site Map | Contacts