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

{ntpdman} 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.  {ntpdman} 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 {ntpqman} 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.

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


== FILES

`/etc/ntp.keys`::
  is a common location for the keys file

Reminder: You have to keep it secret.

// end
