ntp-keygen Command for NTPv4

Purpose

Generate public and private keys.

Syntax

ntp-keygen [ -deGHIMPT ][ -b modulus ] [ -c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] [ -C cipher ] [ -i group ] [ -l days ] [ -m modulus ] [ -p passwd ] [ -q passwd ] [ -S [ RSA | DSA ] ] [ -s host ] [ -V nkeys ]

Description

The ntp-keygen command generates cryptographic data files that are used by the Network Time Protocol (NTP) version 4 authentication and identification schemes. It generates message digest keys that are used in symmetric key cryptography.

If the OpenSSL software library is installed, the ntp-keygen command performs the following additional tasks:

Generate host keys, sign keys, certificates.
Identify keys and parameters that are used by the Autokey public key cryptography.

The ntp-keygen command generates the message digest keys file in a format compatible with NTP version 3 (NTPv3). All other files are in privacy enhanced mail encoded (PEM-encoded) printable ASCII format that enables them to be embedded as Multipurpose Internet Mail Extensions (MIME) attachments in emails to other sites.

To generate message digest keys, the ntp-keygen command creates a file with ten pseudo-random printable ASCII strings compatible with the Message-Digest algorithm 5 (MD5) that is provided in the distribution. If the OpenSSL library is installed, it generates an extra ten hex-encoded random bit strings suitable for the Secure Hash Algorithm 1 (SHA1), AES-128 Cipher-based Message Authentication Code (CMAC), and other message digest algorithms. The file that contains message digest keys must be distributed and stored securely, beyond the scope of NTP. In addition to the keys used for ordinary NTP associations, additional keys can be defined as passwords for the ntpq and ntpdc utility commands.

The remaining generated files are compatible with other OpenSSL applications and Public Key Infrastructure (PKI) resources. The ntp-keygen command generates certificates compatible with current industry practice, although some users find the interpretation of X509v3 extension fields flexible. However, the identity keys are not compatible with anything other than Autokey.

The ntp-keygen command encrypts some files by using a private password. The -p password option specifies the password for the local encrypted files and -q password option specifies the password for encrypted files that are sent to remote sites. If no password is provided, Unix uses the hostname that is returned by the gethostname subroutine, which typically corresponds to the Domain Name System (DNS) name of the host.

The pw option in the crypto configuration command specifies the password to read the files for previously encrypted local files. It must match the local password that is used by the ntp-keygen command. If not specified, the hostname is used. Therefore, if this program generates files without a password, the ntpd command can read them back without a password, but only on the same host.

Each host generates encrypted files for its own use and restricts their usage to that specific host, with few exceptions. The symmetric keys file ntp.keys is commonly installed in /etc directory. Other files and links are installed in the /usr/local/etc directory, which is normally located in a shared filesystem in NFS-mounted networks and cannot be changed by shared clients. The keys directory location can be modified by using the keysdir configuration command. The keysdir command is located in the /etc directory.

This program sends comments and error messages to the stderr error stream and outputs remote files to the stdout output stream. The stderr error stream and stdout output stream allows the comments, error messages, and output files to be piped to other applications or redirected to other files. Generated files and links use names that begin with the string ntpkey and include the file type, generating host, and file stamp. For more information about the cryptographic data files, see the Cryptographic Data Files page.

Running the program

Perform the following steps to test and learn the Autokey concepts:

Log in as the root user.
Navigate to the /usr/local/etc keys directory.
If you run the process for the first time, or if the files that start with ntpkey are removed, use the ntp-keygen command without any arguments. The ntp-keygen command without any arguments creates a default Rivest-Shamir-Adleman algorithm (RSA) host key and an RSA-MD5 certificate that expires in one year.

Note: If you run the ntp-keygen command again without any arguments, it uses the existing keys and settings to generate a new certificate with a new expiration date set for one year from the certificate generation date.

Perform the following steps to create a certificate trail:

Run the ntp-keygen command on as many hosts as needed.
Designate one of the hosts to be the trusted host (TH) by using the ntp-keygen command with the -T option.
Configure the TH to sync with reliable Internet servers.
Configure the other hosts to sync directly or indirectly with the TH. A certificate trail is created when Autokey requests a host in the hierarchy toward the TH to sign the certificate. This signed certificate is then passed on to the host that is after the host that signed the certificate in hierarchy upon request.

Note: All group hosts must have open-chain certificate trails that end at the TH.

The host key, which must be an RSA type, is used to encrypt the cookie when needed. By default, the host key also functions as the sign key that is used to encrypt signatures. You can assign a different sign key by using the -S option, and it can be either RSA or Digital Signature Algorithm (DSA) type. The default type of the signature message digest is MD5. However, you can specify any combination of the sign key type and message digest that the OpenSSL library supports by using the -c option.

The rules state that cryptographic media must be generated with proven timestamps, which means that the host must be synchronized before the net-keygen command is used. This rule creates a chicken-and-egg problem when starting the host for the first time. Therefore, initially set the host time manually to ensure that the certificate lifetime falls within the current year. Once the host is synchronized to a proventic source, regenerate the certificate.

For more information about trusted groups and identity schemes, see the Autokey Public-Key Authentication page.

Flags

Table 1. Flags
Item	Description
-b `modulus`	Sets the modulus to generate identity keys. The value of the modulus is specified by the `modulus` variable in bits. The default value is 512. It can be set from 512 (64 octets) to 2048 (256 octets). Note: Use the larger moduli with caution as a larger `modulus` value can consume considerable computing resources and increases the size of authenticated packets.
-c [ RSA-MD2 \| RSA-MD5 \| RSA-SHA \| RSA-SHA1 \| RSA-MDC2 \| RSA-RIPEMD160 \| DSA-SHA \| DSA-SHA1 ]	Selects the certificate message digest or the signature encryption scheme. The default value is RSA-MD5. To ensure compatibility with Federal Information Processing Standard (FIPS) 140-2, use either the DSA-SHA or DSA-SHA1 scheme. Note: Use an RSA signing key with the RSA schemes and a DSA signing key with the DSA schemes.
-C `cipher`	Selects the OpenSSL cipher to use for password-protected keys. The `openssl -h` command that is provided with OpenSSL, displays available ciphers. The default value is `des-ede3-cbc`.
-d	Enables debugging. This option displays the cryptographic data that is produced in eye-friendly billboards.
-e	Extracts the IFF or Guillou-Quisquater (GQ) public parameters from the previously specified `IFFkey` or `GQkey` keys file. Sends the unencrypted data to the `stdout` output stream.
-G	Generates a new encrypted GQ key file for the GQ identity scheme. This option cannot be used with the -I and -V options.
-H	Generates a new encrypted RSA public or private host key file.
-i `group`	Sets the optional Autokey group name to the name specified by the `group` variable. This name is used in file names of the identity scheme parameter. If no group name is provided, the hostname is considered as the default group name. When the group name is specified by using the -i or -s option followed by an @ character, the group name is also included in the certificate subject and issuer names in the format `host@group`. The group name must match the group that is specified by the `crypto ident` or `server ident` in the configuration file of the `ntpd` function.
-I	Generates a new encrypted IFF key file for the Schnorr identity scheme. This option cannot be used with the -G and -V options.
-l `days`	Sets the lifetime for certificates to the number of days specified by the `days` variable. The default value is 365 days.
-m `modulus`	Sets the modulus to generate files. The value of the modulus is specified by the `modulus` variable in bits. The default value is 512. It can be set from 512 (64 octets) to 2048 (256 octets). Note: Use the larger moduli with caution as a larger `modulus` value can consume considerable computing resources and increases the size of authenticated packets.
-M	Generates a new key file that contains 10 MD5 keys and 10 SHA keys. An MD5 key is a string of 20 random printable ASCII characters, while an SHA key is a string of 40 random hex digits. The file can be edited by using a text editor to change the key type or key content. This option cannot be used with any other options.
-P	Generates a new private certificate that is used by the PC identity scheme. By default, the program generates public certificates. Note: The PC identity scheme is not recommended for new installations.
-p `passwd`	Sets the password to read and write encrypted files to the password specified by the `passwd` variable. Such files include the host, sign, and identify key files. By default, the Unix gethostname subroutine returns the password string.
-q `passwd`	Sets the password for writing encrypted IFF, GQ, and MV identity files that are redirected to the `stdout` output file, as the password specified by the `passwd` variable. Such files are decrypted with the `-p passwd` command, then encrypted with the `-q passwd` command. By default, the Unix gethostname subroutine returns the password string.
-S [ RSA \| DSA ]	Generates a new encrypted public or private sign key file of the specified type. By default, the sign key is the host key and has the same type. If FIPS 140-2 compatibility is required, the sign key type must be DSA.
-s `host[ @group]`	Specifies the Autokey hostname, where `host` is the hostname and `group` is the optional group name. The Autokeys are used in the form `host@group` for the certificate subject and issuer. You can specify `-s @group` to leave the hostname unchanged. The group name, or the hostname if no group is provided, is also used in the file names of IFF, GQ, and MV identity scheme parameter files. If the host is not specified, the default is the string that is returned by the gethostname subroutine.
-T	Generates a trusted certificate. By default, the program generates a nontrusted certificate.
-V `nkeys`	Generates encrypted server keys for the Mu-Varadharajan (MV) identity scheme by using the encrypted server keys. The number of encrypted server keys that must be generated is specified by the `nkeys` variable. This option excludes the -I and -G options. Note: Support for this option is considered as a work in progress.

Exit Status

The ntp-keygen command returns the following exit values:

Table 2. Exit Status
Item	Description
`0`	Successful completion.
`>0`	An error occurred.

Security

Access Control: You must have root authority to run this command.
Auditing Events: N/A

Examples

To generate RSA-SHA cryptographic keys, enter the following command:
```
ntp-keygen -c RSA-SHA
```
To print a list of the peers that are known to the server and a summary of their state, enter the following command:
```
ntpdc -p
```

An output similar to the following example is displayed:

            Using OpenSSL version 90804f

            Generating RSA keys (512 bits)...

            RSA                                             3 1 2

            Generating new host file and link

            ntpkey_host_aixfvt12->ntpkey_RSAkey_aixfvt12.3444540821

            Using host key as sign key

            Generating certificate RSA-SHA

            X509v3 Basic Constraints: critical,CA:TRUE

            X509v3 Key Usage: digitalSignature,keyCertSign

            Generating new cert file and link

            ntpkey_cert_aixfvt12->ntpkey_RSA-SHAcert_aixfvt12.3444540821

Files

Table 3. Files
Item	Description
/usr/sbin/ntp4/ntp-keygen4	Contains the ntp-keygen command for NTPv4.
/usr/sbin/ntp-keygen -->/usr/sbin/ntp4/ntp-keygen4	The default symbolic link to the NTPv4 binary from `/usr/sbin` directory.