freebsd-skq/usr.sbin/ntp/doc/ntp-genkeys.8

.\"
.\" $FreeBSD$
.\"
.Dd August  2, 2001
.Dt NTP_GENKEYS 8
.Os
.Sh NAME
.Nm ntp-genkeys
.Nd generate public and private keys
.Sh SYNOPSIS
.Nm
.Op Fl dfhlnt
.Op Fl c Ar conffile
.Op Fl g Ar target
.Op Fl k Ar keyfile
.Sh DESCRIPTION
The
.Nm
utility generates random keys used by either or both the
NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey)
cryptographic authentication schemes.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl c Ar conffile
Location of
.Xr ntp.conf 8
file.
.It Fl d
enable debug messages (can be used multiple times)
.It Fl f
force installation of generated keys.
.It Fl g target
Generate file or files indicated by the characters in the
.Ar target
string:
.Bl -tag -width X
.It Li d
Generate D-H parameter file.
.It Li m
Generate MD5 key file.
.It Li r
Generate RSA keys.
.El
.It Fl h
Build keys here (current directory).
Implies
.Fl l .
.It Fl k Ar keyfile
Location of key file.
.It Fl l
Do not make the symlinks.
.It Fl n
Do not actually do anything, just say what would be done.
.It Fl t
Trash the (old) files at the end of symlink.
.El
.Pp
By default the program
generates the
.Xr ntp.keys 5
file containing 16 random symmetric
keys.
In addition, if the
rsaref20
package is configured
for the software build, the program generates cryptographic values
used by the Autokey scheme.
These values are incorporated as a set
of three files,
.Pa ntpkey
containing the RSA private key,
.Pa ntpkey_ Ns Ar host
containing the RSA public key, where
.Ar host
is the DNS name of the generating machine, and
.Pa ntpkey_dh
containing the parameters for the Diffie-Hellman
key-agreement algorithm.
All files and are in printable ASCII
format.
A timestamp in NTP seconds is appended to each.
Since the
algorithms are seeded by the system clock, each run of this program
produces a different file and file name.
.Pp
The
.Xr ntp.keys 5
file contains 16 MD5 keys.
Each key
consists of 16 characters randomized over the ASCII 95-character
printing subset.
The file is read by the daemon at the location
specified by the
.Ic keys
configuration file command and made
visible only to root.
An additional key consisting of a easily
remembered password should be added by hand for use with the
.Xr ntpq 8
and
.Xr ntpdc 8
programs.
The file must be
distributed by secure means to other servers and clients sharing
the same security compartment.
While the key identifiers for MD5
and DES keys must be in the range 1-65534, inclusive, the
.Nm
utility uses only the identifiers from 1 to
16.
The key identifier for each association is specified as the key
argument in the
.Ic server
or
.Ic peer
configuration file command.
.Pp
The
.Pa ntpkey
file contains the RSA private key.
It is
read by the daemon at the location specified by the
.Ar privatekey
argument of the
.Ic crypto
configuration
file command and made visible only to root.
This file is useful
only to the machine that generated it and never shared with any
other daemon or application program.
.Pp
The
.Pa ntpkey_ Ns Ar host
file contains the RSA public
key, where
.Ar host
is the DNS name of the host that
generated it.
The file is read by the daemon at the location
specified by the
.Ar publickey
argument to the
.Ic server
or
.Ic peer
configuration file command.
This file can be
widely distributed and stored without using secure means, since the
data are public values.
.Pp
The
.Pa ntp_dh
file contains two Diffie-Hellman parameters:
the prime modulus and the generator.
The file is read by the daemon
at the location specified by the
.Ar dhparams
argument of the
.Ic crypto
configuration file command.
The file can be
distributed by insecure means to other servers and clients sharing
the same key agreement compartment, since the data are public
values.
.Pp
The file formats begin with two lines, the first containing the
generating system DNS name and the second the datestamp.
Lines
beginning with
.Ql #
are considered comments and ignored by
the daemon.
In the
.Xr ntp.keys 5
file, the next 16 lines
contain the MD5 keys in order.
If necessary, this file can be
further customized by an ordinary text editor.
The format is
described in the following section.
In the
.Pa ntpkey
and
.Pa ntpkey_ Ns Ar host
files, the next line contains the
modulus length in bits followed by the key as a PEM encoded string.
In the
.Pa ntpkey_dh
file, the next line contains the prime
length in bytes followed by the prime as a PEM encoded string, and
the next and final line contains the generator length in bytes
followed by the generator as a PEM encoded string.
.Pp
Note: See the file
.Pa ./source/rsaref.h
in the
rsaref20
package for explanation of return values, if
necessary.
.Sh SEE ALSO
.Xr ntp.keys 5 ,
.Xr ntpdc 8 ,
.Xr ntpq 8
.Sh BUGS
It can take quite a while to generate the RSA public/private key
pair and Diffie-Hellman parameters, from a few seconds on a modern
workstation to several minutes on older machines.