### `ntp-genkeys` - generate public and private keys

from Alice's Adventures in Wonderland, Lewis Carroll

Alice holds the key.

#### Synopsis

`ntp-genkeys`

#### Description

This program generates random keys used by either or both the NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey) cryptographic authentication schemes. By default the program generates a symmetric key file containing 16 random keys for the MD5 message digest algorithm. In addition, if the OpenSSL software library has been installed, the program generates cryptographic key files used by the Autokey protocol. These files contain the public/private key pair, certificate request, certificate and Diffie-Hellman parameters. While all available files are generated, the Autokey Version 2 protocol requires only the public/private key pair and certificate files. All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities.

As explained in the Authentication Options page, all cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal random number generator. It is important to understand that entropy must be evolved for each file generation and agreement calculation, for otherwise the random number sequence would be predictable. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting the NTP daemon and `ntp-genkeys` program. Directions for doing this are on the Authentication Options page.

The safest way to run the `ntp-genkeys` program is logged in directly as root. The recommended procedure is change to the keys directory, usually `/ust/local/etc` then run the program, which in its present form has no command line options. The program generates key files for all message digest and signature encryption schemes supported by the OpenSSL library. The key files are guaranteed to be unique, so no existing key files will be overwritten. Then, using procedures described below, install soft links from the default file names used by the daemon to the selected file names.

Running the program as other than root and using the Unix `su` command to assume root may not work properly, since by default the OpenSSL library looks for the random seed file in the user home directory. However, installing the keys as root might not work in NFS-mounted file systems, as NFS clients may not be able to write to the shared keys directory, even as root. NFS clients should run the program as root or some other user and save the key files in a writable directory that can be read directly or indirectly by the NFS server. The NFS server can then copy them to the shared keys directory. Since the `ntp-genkeys` program does not write the random seed file, it is convenient to define the `$RANDFILE` environment variable used by the OpenSSL library as the path to the random seed file.

#### File Naming Conventions

All file names include the hostname of the generating host together with the NTP filestamp of creation. This insures uniqueness for each generation of keys throughout the NTP subnet. The hostname is the node name of the generating host as returned by the Unix `gethostname()` library routine. The filestamp is the NTP seconds in decimal ASCII format. Both the `ntp-genkeys` program and the Autokey protocol use these names to insure the cryptographic data are consistent and to avoid replay attacks. Since the file data are derived from random values seeded by the system clock and the file name includes the filestamp, every generation produces a different file and different file name. However, the NTP daemon looks for the generic file names without the filestamp extension on the assumption that soft links are installed from the generic name to the particular file generation name.

Files containing public-key cryptographic values depend upon selection of the message digest and signature encryption scheme. There are several schemes available in the OpenSSL software library, each identified by a specific string such as the default `RSA_MD5`, which stands for the MD5 message digest with RSA encryption scheme. The `ntp-genkeys` program can make public/private keys, certificates and certificate requests for all schemes supported by the OpenSSL library.

In its present form, the `ntp-genkeys` program generates files for all digest/signature schemes supported by the OpenSSL library and NTP daemon. The recommended practice is to copy all of these files to the default directory `/usr/local/etc` and install links to select which ones to use according to the default file names listed below. At its present level of OpenSSL development, the message digest algorithm is specifically bound to the signature encryption algorithm, so only a limited number of combinations are available. Further details are in the OpenSSL documentation.

#### Symmetric Key File

The `ntp-genkeys` program generates MD5 symmetric keys in a file named `ntpkey_MD5key_hostname.filestamp`. Since the file contains private shared values, it should be visible only to root and distributed by secure means to other servers and clients sharing the same security compartment. The NTP daemon expects this file with name `ntp.keys`, so a soft link is needed to direct this name to the particular file name generated. While this file is not used with the Autokey Version 2 protocol, it is needed to authenticate some remote configuration commands used by the `ntpq` and `ntpdc` utilities.

The symmetric key file contains 16 MD5 keys. Each key consists of 16 characters randomized over a ASCII 93-character printing subset. The file is read by the daemon at the location specified by the `keys` configuration file command. Additional keys consisting of easily remembered passwords should be added by hand for use with the `ntpq` and `ntpdc` programs. While the key identifiers for MD5 keys must be in the range 1-65,534, inclusive, the `ntp-genkeys` program uses only the identifiers from 1 to 16. The key identifier for each association is specified as the key argument in the `server` or peer configuration command.

#### Public/Private Key Files

The Autokey protocol requires every host to have a public/private host key pair and an optional public/private sign key pair. The `ntp-genkeys` program generates a public/private key pair in a file named `ntpkey_keynamekey_hostname.filestamp`, where keyname is the name of the public key algorithm. Currently, the program generates public/private key files for both RSA and DSA algorithms. Since the host key is used to encrypt some data, it must be an RSA type. The sign key file can be a DSA type or the same or different RSA type. Since these files contains private unshared values that are useful only to the machine that generated them, they should be visible only to root and never shared with any other system or application program. The NTP daemon expects the host key file with name `ntpkey_key_hostname` and the sign key file with name `ntpkey_sign_hostname`, so soft links are needed to direct these names to the particular file name generated.

The `ntp-genkeys` program generates the Diffie-Hellman parameters in a file named `ntpkey_dh_hostname.filestamp`. This file is not used by the current Autokey version, but might be useful in related applications. The file contains only public values and can be freely transmitted and stored anywhere without further cryptographic protection. A number of hosts can use the same file in a shared directory.

#### Public Certificates

The Autokey protocol requires every host to have a digitally signed public certificate. Security procedures require the public key and host credentials, such as host name, responsible person, mail address, etc., to be provided in the form of a X.509 certificate request to a trusted certificate authority or CA. The CA attaches a digital signature to the request and returns the certificate itself to the requesting party. The integrity of these procedures depend on the certificate trail that ultimately must end on a self-signed certificate provided by the ultimate CA. The OpenSSL software library provides routines that can automate this process. The reader is referred to the OpenSSL documentation for further details.

The `ntp-genkeys` program generates a X.509 public certificate request in a file named `ntpkey_digestnamereq_hostname.filestamp`, where digestname is the name of the digest/signature scheme. This file is not used by the current Autokey version, but might be useful in related applications. The file contains only public values and can be freely transmitted and stored anywhere without further cryptographic protection. The NTP daemon expects this file with name `ntpkey_req_hostname`, so a soft link is needed to direct this name to the particular file name generated. Where security considerations require, this file can be transmitted to a trusted certificate authority (CA) and returned as a signed public certificate for use in the Autokey protocol.

For convenience, the `ntp-genkeys` program also generates a self-signed X.509 public certificate in a file named `ntpkey_digestnamecert_hostname.filestamp`. The file contains only public values and can be freely transmitted and stored anywhere without further cryptographic protection. The NTP daemon expects this file with name `ntpkey_cert_hostname`, so a soft link is needed to direct this name to the particular file name used. This file can be used in lieu of a CA certificate and has compatible encoding and content.

The Autokey protocol supports all digest/signature schemes available in the OpenSSL library, including those using the MD2, MD5, SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme specified in the certificate must be compatible with the sign key. Certificates using any digest algorithm are compatible with RSA sign keys; however, only SHA and SHA1 certificates are compatible with DSA sign keys.

#### Leapseconds Table

The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers using `ftp` as the ASCII file `pub/leap-seconds`.

While not strictly a security function, the Autokey protocol provides means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the `crypto` command, with default `ntpkey_leap`, while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.

#### File Formats

The file formats begin with two lines, the first containing the actual file name, including the generated hostname and filestamp. The second line contains the datestamp in conventional format. Lines beginning with `#` are considered comments and ignored by the daemon. In the `ntp.keys` file, the next 16 lines contain the MD5 keys. If necessary, this file can be further customized using an ordinary text editor. The format is described below. For all other files the actual cryptographic value is encoded in PEM-encoded printable ASCII format preceded and followed by MIME content identifier lines. Some values such as certificates and Diffied-Hellman parameters are encoded using ASN.1 encoding rules.

The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since DES-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Keys are entered one per line in the format

`keyno type key`

where `keyno` is a positive integer in the range 1-65,535, `type` is the string `MD5` defining the key format and `key` is the key itself, which is a printable ASCII string 16 characters or less in length. Each character is chosen from the 93 printable characters in the range 0x21 through 0x7f excluding space and the '#' character.

Note that the keys used by the `ntpq` and `ntpdc` programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in human readable ASCII format.

#### Bugs

It can take quite a while to generate some cryptographic values, from one to several minutes with modern architectures such as UltraSPARC and up tens of minutes to an hour with older architectures such as SPARC IPC.