Table of Contents

Synopsis

ntpkeygen [-M]

Description

This program generates the keys used in NTP’s symmetric key cryptography.

The program produces a file containing ten pseudo-random printable ASCII strings suitable for the MD5 message digest algorithm included in the distribution. It also produces an additional ten hex-encoded random bit strings suitable for the SHA-1 and other message digest algorithms. The message digest keys file must be distributed and stored using secure means beyond the scope of NTP itself. Besides the keys used for ordinary NTP associations, additional keys can be defined as passwords for the ntpq utility program.

Command Line Options

-M, --md5key

Dummy option for backward compatibility in old scripts. This program always runs in -M mode.

Running the program

The safest way to run the ntpkeygen program is logged in directly as root. The recommended procedure is change to the keys directory, usually /usr/local/etc, then run the program.

Installing the keys as root might not work in NFS-mounted shared file systems, as NFS clients may not be able to write to the shared keys directory, even as root. In this case, NFS clients can specify the files in another directory such as /etc using the keys command.

Warning
ntpkeygen uses the system randomness source. On a POSIX system this is usually /dev/urandom. Immediately after a reboot, on any OS, there may not be sufficient entropy available for this program to perform well. Do not run this program from any startup scripts. Only run this program on an active host with a lot of available entropy.

Key file access and location

The ntpd(8) configuration command crypto pw password specifies the read password for previously encrypted files. The daemon expires on the spot if the password is missing or incorrect. For convenience, if a file has been previously encrypted, the default read password is the name of the host running the program. If the previous write password is specified as the host name, these files can be read by that host with no explicit password.

File names begin with the prefix ntpkey and end with the postfix hostname.filestamp, where hostname is the owner name, usually the string returned by the Unix gethostname() routine, and filestamp is the NTP seconds when the file was generated, in decimal digits. This both guarantees uniqueness and simplifies maintenance procedures, since all files can be quickly removed by a rm ntpkey* command or all files generated at a specific time can be removed by a rm *filestamp command.

All files 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 and each file can be overridden by configuration commands, but this is not recommended. 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.

Random Seed File

All key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the library routines.

It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources.

This implementation uses Python’s random.SystemRandom class, which relies on os.urandom(). The security of os.urandom() is improved in Python 3.5+.

Cryptographic Data Files

The ntpkeygen program generates a file of symmetric keys 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 ntpkeygen 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. This file is needed to authenticate some remote configuration commands used by the ntpq(1) utility.

Comments may appear in the file, and are preceded with the # character.

Following any headers the keys are entered one per line in the format:

Field Meaning

keyno

Positive integer in the range 1-65,535

type

MD5 or SHA-1 , type of key

key

the actual key, printable ASCII

pic/sx5.gif

Figure 1. Typical Symmetric Key File

Figure 1 shows a typical symmetric keys file used by the reference implementation. Each line of the file contains three fields, first an integer between 1 and 65534, inclusive, representing the key identifier used in the server and peer configuration commands. Next is the key type for the message digest algorithm, which in the absence of the OpenSSL library must be MD5 to designate the MD5 message digest algorithm. If the OpenSSL library is installed, the key type can be any message digest algorithm supported by that library. However, if compatibility with FIPS 140-2 is required, the key type must be SHA1. The key type can be changed using an ASCII text editor.

An MD5 key consists of a printable ASCII string less than or equal to 16 characters and terminated by whitespace or a # character. An OpenSSL key consists of a hex-encoded ASCII string of 40 characters, which is truncated as necessary.


icons/home.gif Home Page

icons/sitemap.png Site Map

icons/mail2.gif Contacts