1 files changed, 206 insertions, 0 deletions
diff --git a/usr.sbin/ntp/doc/ntp-genkeys.8 b/usr.sbin/ntp/doc/ntp-genkeys.8
new file mode 100644
index 0000000..3af0f47
--- /dev/null
+++ b/usr.sbin/ntp/doc/ntp-genkeys.8
@@ -0,0 +1,206 @@
+.\"
+.\" $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
+This program 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
+program 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.