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

from Alice's Adventures in Wonderland, Lewis Carroll

Alice holds the key.

Last update: 02:48 UTC Monday, September 10, 2007

#### Related Links

#### Table of Contents

- Synopsis
- Description
- Running the program
- Trusted Hosts and Secure Groups
- Identity Schemes
- Command Line Options
- Random Seed File
- Cryptographic Data Files
- Bugs

#### Synopsis

`ntp-keygen [ -cdeMPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -H } [ -i issuername ] [ -p passwd2 ] [ -q passwd1 ] [ -S [ RSA | DSA ] ] [ -s subjectame ] [ -V nkeys ]`

#### Description

This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It generates MD5 key files used in symmetric key cryptography and, if the OpenSSL software library has been installed, it generates encryption keys, certificates and identity parameters used by the Autokey cryptographic algorithms. 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.

Generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates or certificate requests generated by this or other programs should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity parameter files are probably not compatible with anything other than Autokey.

All files written by this program are encrypted using a private password. The `-p passwd2` option specifies the write password and the `-q passwd2` option the read password for previously encrypted files. If no read password is specified, the host name returned by the Unix `gethostname()` function is used. If no write password is specified, the read password is used as the write password.

The `ntpd` configuration command `crypto pw passwd` specifies the read password for previously encrypted files. The daemon expires on the spot if a file fails to decrypt properly. For convenience, if the `ntpd` password is not specified, the host name returned by the Unix `gethostname()` function is used. Thus, if files are generated by this program without password, they can be read back by `ntpd` without password, but only on the same machine.

All files and links are installed by default in the keys directory `/usr/local/etc`, which is normally in a shared filesystem in NFS-mounted networks. The actual location of the keys directory can be changed by a configuration command. Normally, the files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page.

File and link names are in the form `ntpkey_key_name.fstamp`, where `key` is the key type, `name` is the host or group name and `fstamp` is the filestamp (NTP seconds) when the file was created. The key type is a string defining the cryptographic function as described in the command line options below. The filestamp is not used in generated link names. Key types include `host`, `sign`, certificate `cert` and several challenge/response key types. By convention, files used for challenges have a `par` subtype, as in the IFF challenge `iffpar`, while files for responses have a `key` subtype, as in the GQ response `gqkey`.

#### Running the Program

For conciseness in the following discussion, only the key type portion of the name is used and the prefix and suffix are omitted. The safest way to run this program is log in as root and change to the keys directory, usually `/usr/local/etc.` When run for the first time, or if all `ntpkey` files have been removed, use the

`ntp-keygen -q passwd1`

command, where `passwd1` is the password also used by `ntpd`. All `ntp-keygen` commands must include the `-q passwd1` as the explicit read password and implicit write password.

The program generates an RSA host key file `RSAkey` and link `host`, and matching RSA-MD5 certificate file `RSA-MD5cert` and link `cert`. This is all that is necessary for the Trusted Certificate (TC) identity scheme, which does not use a challenge/response identity scheme. Identity schemes will be described later. If run again with the same command line, the program uses the same host key file, but generates a new certificate file and link. Include the `-H` option to generate all new files and links.

Run the command on as many machines as necessary. Designate one of them the trusted host and configure it to synchronize via reliable paths. Then configure the nontrusted servers to synchronize s to the trusted host directly or indirectly but avoid cyclic paths.

By default the name used in the host key and certificate file is the string returned by the Unix `gethostname()` function. A different name can be assigned using the `-s host` option on the command line. The name must match the `host` name specified in the `crypto` command in the configuration file. The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. A different sign key file name can be assigned using the `-S sign` option and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified.

#### Trusted Hosts and Secure Groups

As described on the Authentication Options page, an NTP secure group consists of one or more low-stratum trusted hosts as the root from which all other group hosts derive synchronization directly or indirectly via acyclic certificate trails. For cryptographic purposes all trusted hosts in a group have the same name, which is also the name of the group. Trusted hosts have trusted, self-signed certificates; all other hosts have nontrusted, self-signed certificates. A certificate trail is constructed by asking the immediately ascendant host toward the root to sign its certificate, which is then provided to the immediately descendant host on request.

It is convenient to nominate a single trusted host acting as a trusted authority (TA) to generate a set of files that are then copied intact to all other trusted hosts in the group, most conveniently as a tar archive. This means that it doesn't matter which certificate trail ends at which trusted host, since the rootcertificate and identity data are the same. To generate and install cryptographic media files on the TA as root, use the `-s host` option to specify the host name and the `-T` option to specify a trusted certificate. If run again with the same command line, the program uses the same host key file, but generates a new certificate file and link. Include the `-H` option to generate all new files and links.

To generate and install cryptgrahic media files on nontrusted hosts as root, use the `-i group` option to specify the group name and nontrusted certificate. This option has no effect unless one of the identity schemes described in the next section is used, but it does help to minimize errors when configuriong certificate trails.

#### Identity Schemes

As described on the Authentication Options page, there are five identity schemes, three of which, IFF, GQ and MV, have password protected identity files. A file specific to each scheme and group is generated by the TA and then copied to all trusted hosts. In the intended model a group host sends a mail request message to the TA including its private key. The TA encrypts the identity file with that key an returns it in a mail message. The attachment is then copied intact to the keys director and renamed as directed below.

Use the following procedure to produce IFF parameters for nontrusted group hosts. The procedure is similar for the GQ parameters. The TA uses the

`intp-keygen -q passwd1 -p passwd2 -i group`

command to generate IFF parameters, where `passwd1` is the trusted host password and `passwd2` is the intended recipient password and must be different from `passwd1`. The particular identity scheme selected and the parmeter file type will match the scheme selected by the TA when first generating its own files.

The group parameters are written to the standard output stream `stdout` where they can be piped to an application that sends the contents to the intended recipient as a MIME attachment. The identity parameters are installed in the keys directory and renamed as in the first line of the file, but without the filestamp.

The NTP secure group rules require that a all hsts have the same name; however, a trusted host can be a client of one or more other groups operating at a lower stratum. The trusted host or hosts have identity keys for their group as well as identity parameters for each of the lower stratum groups. These parameters can be obtained from the TA of each group.

During the Autokey protocol with the selected lower stratum hosts, the trusted host hikes the certificate trail to obtain and install the trusted host certificate of the lower stratum group. The subject name on this certificate is used to load the identity parameters for that group.

In the IFF scheme the TA generates the IFF key file including a private key and the parameters needed to verify identity to a dependent client. The parameter file is normally a copy of this file; however, using the `-e` option on the `ntp-keygen` command line, the parameter file includes only the parameters and not the private key. A client without the private key cannot prove identity to dependent client.

In the GQ scheme the TA generates the key and parameter files in separate steps and provides only the parameter file to other group hosts. However, any host can use `ntp-keygen` to create a new GQ key file to prove identity to dependent client.

#### Command Line Options

`-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]`
  Select certificate and message digest/signature encryption scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is `RSA-MD5`.
`-d`
  Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.
`-e`
  Generate IFF parameter file `IFFpar` from an existing IFF key file `IFFkey`. This is commonly done to produce IFF parameters for hosts acting only as clients without revealing the private key. Note: This option is active only when the write password is different than the read password.
`-G`
  Generate GQ key file `GQkey` and link `gqkey` for the Guillou-Quisquater (GQ) identity scheme, obsoleting any that may exist.
`-g`
  Generate GQ parameter file `GQpar` for the Guillou-Quisquater (GQ) identity scheme, obsoleting any that may exist. This option is normally used when the read pasword and write password are different.
`-H`
  Generate public/private host keys `RSAkey`, and link `host,` obsoleting any that may exist.
`-I`
  Generate parameters `IFFpar` and link `iff` for the Schnorr (IFF) identity scheme, obsoleting any that may exist.
`-i name`
  Set the group name to `name`. This is used as the file name for identity parameters. If this option is not present, the group name defaults to the host name.
`-M`
  Generate MD5 keys, obsoleting any that may exist.
`-P`
  Generate a private certificate used by the PC identity scheme. By default, the program generates public certificates.
`-p password`
  Set the password for writing encrypted files to `password`.
`-q password`
  Set the password for reading encrypted files to `password`.
`-S [ RSA | DSA ]`
  Generate a new sign key of the designated type, obsoleting any that may exist. By default, the program uses the host key as the sign key.
`-s name`
  Set the host name to `name`. This is used for the host key as well as the subject and issuer names in certificates.
`-T`
  Generate a trusted certificate. By default, the program generates a non-trusted certificate.
`-V nkeys`
  Generate server parameters `MV` and `nkeys` client keys for the Mu-Varadharajan (MV) identity scheme. Note: support for this option should be considered a work in progress.

#### Random Seed File

All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the OpenSSL library routines. If a site supports `ssh`, it is very likely that means to do this are already available. The entropy seed used by the OpenSSL library is contained in a file, usually called `.rnd`, which must be available when starting the `ntp-keygen` program or `ntpd` daemon.

The OpenSSL library looks for the file using the path specified by the `RANDFILE` environment variable in the user home directory, whether root or some other user. If the `RANDFILE` environment variable is not present, the library looks for the `.rnd` file in the user home directory. Since both the `ntp-keygen` program and `ntpd` daemon must run as root, the logical place to put this file is in `/.rnd` or `/root/.rnd`. If the file is not available or cannot be written, the program exits with a message to the system log.

#### Cryptographic Data Files

All file formats begin with two lines. The first line contains the file name, in the format `ntpkey_key_host.fstamp`, where `key` is the key type, `host` is the group or host name and `fstamp` is the filestamp (NTP seconds) when the file was created. The second line contains the datestamp in conventional Unix `date` format. Lines beginning with `#` are ignored.

The remainder of the file contains cryptographic data encoded first using ASN.1 rules, then encrypted using the DES-CBC algorithm and given password and finally written in PEM-encoded printable ASCII text preceded and followed by MIME content identifier lines.

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. Following the header the 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.

The `ntp-keygen` program generates a MD5 symmetric keys file `ntpkey_MD5key_hostname.filestamp`. Since the file contains private shared keys, it should be visible only to root and distributed by secure means to other subnet hosts. The NTP daemon loads the file `ntp.keys`, so `ntp-keygen` installs a soft link from this name to the generated file. Subsequently, similar soft links must be installed by manual or automated means on the other subnet hosts. 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.

#### 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 to tens of minutes to an hour with older architectures such as SPARC IPC.