// This is the body of the manual page for ntpkeygen.
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.

[[synop]]
== Synopsis ==
[verse]
+ntpkeygen+ [+-M+]

[[descrip]]
== 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 link:ntpq.html[+ntpq+] utility program.

[[cmd]]
== Command Line Options ==

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

[[run]]
== 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
+{prefixdir}/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.

[[access]]
== Key file access and location ==

The {ntpdman} 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
+{prefixdir}/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]]
== 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
https://docs.python.org/library/os.html#os.urandom[Python 3.5+].

[[crypto]]
== 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 {ntpqman}
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:

[options="header"]
|====================================================================
|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
|====================================================================

// Recheck.  The code does not check for ' '.  -- Sanjeev 20161203
// For type MD5, each character is chosen from the 93 printable
// characters in the range 0x21 through 0x7f excluding space and the ‘#’
// character.

// end
