MFV ntp 4.2.8p1 (r258945, r275970, r276091, r276092, r276093, r278284)

Thanks to roberto for providing pointers to wedge this into HEAD.

Approved by:	roberto

1 files changed, 1221 insertions, 0 deletions

diff --git a/contrib/ntp/util/ntp-keygen.man.in b/contrib/ntp/util/ntp-keygen.man.in
new file mode 100644
index 000000000000..6242382b020c
--- /dev/null
+++ b/contrib/ntp/util/ntp-keygen.man.in
@@ -0,0 +1,1221 @@
+.de1 NOP
+.  it 1 an-trap
+.  if \\n[.$] \,\\$*\/
+..
+.ie t \
+.ds B-Font [CB]
+.ds I-Font [CI]
+.ds R-Font [CR]
+.el \
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+.TH ntp-keygen @NTP_KEYGEN_MS@ "04 Feb 2015" "ntp (4.2.8p1)" "User Commands"
+.\"
+.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-Xkaqsu/ag-9kairu)
+.\"
+.\" It has been AutoGen-ed February 4, 2015 at 02:43:55 AM by AutoGen 5.18.5pre4
+.\" From the definitions ntp-keygen-opts.def
+.\" and the template file agman-cmd.tpl
+.SH NAME
+\f\*[B-Font]ntp-keygen\fP
+\- Create a NTP host key
+.SH SYNOPSIS
+\f\*[B-Font]ntp-keygen\fP
+.\" Mixture of short (flag) options and long options
+[\f\*[B-Font]\-flags\f[]]
+[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
+[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
+.sp \n(Ppu
+.ne 2
+
+All arguments must be options.
+.sp \n(Ppu
+.ne 2
+
+.SH DESCRIPTION
+This program generates cryptographic data files used by the NTPv4
+authentication and identification schemes.
+It generates MD5 key files used in symmetric key cryptography.
+In addition, if the OpenSSL software library has been installed,
+it generates keys, certificate and identity files used in public key
+cryptography.
+These files are used for cookie encryption,
+digital signature and challenge/response identification algorithms
+compatible with the Internet standard security infrastructure.
+.sp \n(Ppu
+.ne 2
+
+All files are in PEM-encoded printable ASCII format,
+so they can be embedded as MIME attachments in mail to other sites
+and certificate authorities.
+By default, files are not encrypted.
+.sp \n(Ppu
+.ne 2
+
+When used to generate message digest keys, the program produces a file
+containing ten pseudo-random printable ASCII strings suitable for the
+MD5 message digest algorithm included in the distribution.
+If the OpenSSL library is installed, it produces an additional ten
+hex-encoded random bit strings suitable for the SHA1 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
+\fCntpq\fR(@NTPQ_MS@)\f[]
+and
+\fCntpdc\fR(@NTPDC_MS@)\f[]
+utility programs.
+.sp \n(Ppu
+.ne 2
+
+The remaining generated files are compatible with other OpenSSL
+applications and other Public Key Infrastructure (PKI) resources.
+Certificates generated by this program are compatible with extant
+industry practice, although some users might find the interpretation of
+X509v3 extension fields somewhat liberal.
+However, the identity keys are probably not compatible with anything
+other than Autokey.
+.sp \n(Ppu
+.ne 2
+
+Some files used by this program are encrypted using a private password.
+The
+\f\*[B-Font]\-p\f[]
+option specifies the password for local encrypted files and the
+\f\*[B-Font]\-q\f[]
+option the password for encrypted files sent to remote sites.
+If no password is specified, the host name returned by the Unix
+\fBgethostname\fR()\f[]
+function, normally the DNS name of the host is used.
+.sp \n(Ppu
+.ne 2
+
+The
+\f\*[I-Font]pw\f[]
+option of the
+\f\*[I-Font]crypto\f[]
+configuration command specifies the read
+password for previously encrypted local files.
+This must match the local password used by this program.
+If not specified, the host name is used.
+Thus, if files are generated by this program without password,
+they can be read back by
+\f\*[I-Font]ntpd\f[]
+without password but only on the same host.
+.sp \n(Ppu
+.ne 2
+
+Normally, encrypted files for each host are generated by that host and
+used only by that host, although exceptions exist as noted later on
+this page.
+The symmetric keys file, normally called
+\f\*[I-Font]ntp.keys\f[],
+is usually installed in
+\fI/etc\f[].
+Other files and links are usually installed in
+\fI/usr/local/etc\f[],
+which is normally in a shared filesystem in
+NFS-mounted networks and cannot be changed by shared clients.
+The location of the keys directory can be changed by the
+\f\*[I-Font]keysdir\f[]
+configuration command in such cases.
+Normally, this is in
+\fI/etc\f[].
+.sp \n(Ppu
+.ne 2
+
+This program directs commentary and error messages to the standard
+error stream
+\f\*[I-Font]stderr\f[]
+and remote files to the standard output stream
+\f\*[I-Font]stdout\f[]
+where they can be piped to other applications or redirected to files.
+The names used for generated files and links all begin with the
+string
+\f\*[I-Font]ntpkey\f[]
+and include the file type, generating host and filestamp,
+as described in the
+\*[Lq]Cryptographic Data Files\*[Rq]
+section below.
+.SS Running the Program
+To test and gain experience with Autokey concepts, log in as root and
+change to the keys directory, usually
+\fI/usr/local/etc\f[]
+When run for the first time, or if all files with names beginning with
+\f\*[I-Font]ntpkey\f[]
+have been removed, use the
+\f\*[B-Font]ntp-keygen\fP
+command without arguments to generate a
+default RSA host key and matching RSA-MD5 certificate with expiration
+date one year hence.
+If run again without options, the program uses the
+existing keys and parameters and generates only a new certificate with
+new expiration date one year hence.
+.sp \n(Ppu
+.ne 2
+
+Run the command on as many hosts as necessary.
+Designate one of them as the trusted host (TH) using
+\f\*[B-Font]ntp-keygen\fP
+with the
+\f\*[B-Font]\-T\f[]
+option and configure it to synchronize from reliable Internet servers.
+Then configure the other hosts to synchronize to the TH directly or
+indirectly.
+A certificate trail is created when Autokey asks the immediately
+ascendant host towards the TH to sign its certificate, which is then
+provided to the immediately descendant host on request.
+All group hosts should have acyclic certificate trails ending on the TH.
+.sp \n(Ppu
+.ne 2
+
+The host key is used to encrypt the cookie when required and so must be
+RSA type.
+By default, the host key is also the sign key used to encrypt
+signatures.
+A different sign key can be assigned using the
+\f\*[B-Font]\-S\f[]
+option and this can be either RSA or DSA type.
+By default, the signature
+message digest type is MD5, but any combination of sign key type and
+message digest type supported by the OpenSSL library can be specified
+using the
+\f\*[B-Font]\-c\f[]
+option.
+The rules say cryptographic media should be generated with proventic
+filestamps, which means the host should already be synchronized before
+this program is run.
+This of course creates a chicken-and-egg problem
+when the host is started for the first time.
+Accordingly, the host time
+should be set by some other means, such as eyeball-and-wristwatch, at
+least so that the certificate lifetime is within the current year.
+After that and when the host is synchronized to a proventic source, the
+certificate should be re-generated.
+.sp \n(Ppu
+.ne 2
+
+Additional information on trusted groups and identity schemes is on the
+\*[Lq]Autokey Public-Key Authentication\*[Rq]
+page.
+.sp \n(Ppu
+.ne 2
+
+The
+\fCntpd\fR(@NTPD_MS@)\f[]
+configuration command
+\f\*[B-Font]crypto\f[] \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[]
+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.
+.sp \n(Ppu
+.ne 2
+
+File names begin with the prefix
+\f\*[B-Font]ntpkey_\f[]
+and end with the postfix
+\f\*[I-Font]_hostname.filestamp\f[],
+where
+\f\*[I-Font]hostname\f[]
+is the owner name, usually the string returned
+by the Unix gethostname() routine, and
+\f\*[I-Font]filestamp\f[]
+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
+\f\*[B-Font]rm\f[] \f\*[B-Font]ntpkey\&*\f[]
+command or all files generated
+at a specific time can be removed by a
+\f\*[B-Font]rm\f[]
+\f\*[I-Font]\&*filestamp\f[]
+command.
+To further reduce the risk of misconfiguration,
+the first two lines of a file contain the file name
+and generation date and time as comments.
+.sp \n(Ppu
+.ne 2
+
+All files are installed by default in the keys directory
+\fI/usr/local/etc\f[],
+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.
+.sp \n(Ppu
+.ne 2
+
+Normally, files containing private values,
+including the host key, sign key and identification parameters,
+are permitted root read/write-only;
+while others containing public values are permitted world readable.
+Alternatively, files containing private values can be encrypted
+and these files permitted world readable,
+which simplifies maintenance in shared file systems.
+Since uniqueness is insured by the hostname and
+file name extensions, the files for a NFS server and
+dependent clients can all be installed in the same shared directory.
+.sp \n(Ppu
+.ne 2
+
+The recommended practice is to keep the file name extensions
+when installing a file and to install a soft link
+from the generic names specified elsewhere on this page
+to the generated files.
+This allows new file generations to be activated simply
+by changing the link.
+If a link is present, ntpd follows it to the file name
+to extract the filestamp.
+If a link is not present,
+\fCntpd\fR(@NTPD_MS@)\f[]
+extracts the filestamp from the file itself.
+This allows clients to verify that the file and generation times
+are always current.
+The
+\f\*[B-Font]ntp-keygen\fP
+program uses the same timestamp extension for all files generated
+at one time, so each generation is distinct and can be readily
+recognized in monitoring data.
+.SS Running the program
+The safest way to run the
+\f\*[B-Font]ntp-keygen\fP
+program is logged in directly as root.
+The recommended procedure is change to the keys directory,
+usually
+\fI/usr/local/etc\f[],
+then run the program.
+When run for the first time,
+or if all
+\f\*[B-Font]ntpkey\f[]
+files have been removed,
+the program generates a RSA host key file and matching RSA-MD5 certificate file,
+which is all that is necessary in many cases.
+The program also generates soft links from the generic names
+to the respective files.
+If run again, the program uses the same host key file,
+but generates a new certificate file and link.
+.sp \n(Ppu
+.ne 2
+
+The host key is used to encrypt the cookie when required and so must be RSA type.
+By default, the host key is also the sign key used to encrypt signatures.
+When necessary, a different sign key can be specified and this can be
+either RSA or DSA type.
+By default, the message digest type is MD5, but any combination
+of sign key type and message digest type supported by the OpenSSL library
+can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
+and RIPE160 message digest algorithms.
+However, the scheme specified in the certificate must be compatible
+with the sign key.
+Certificates using any digest algorithm are compatible with RSA sign keys;
+however, only SHA and SHA1 certificates are compatible with DSA sign keys.
+.sp \n(Ppu
+.ne 2
+
+Private/public key files and certificates are compatible with
+other OpenSSL applications and very likely other libraries as well.
+Certificates or certificate requests derived from them should be compatible
+with extant industry practice, although some users might find
+the interpretation of X509v3 extension fields somewhat liberal.
+However, the identification parameter files, although encoded
+as the other files, are probably not compatible with anything other than Autokey.
+.sp \n(Ppu
+.ne 2
+
+Running the program as other than root and using the Unix
+\f\*[B-Font]su\f[]
+command
+to assume root may not work properly, since by default the OpenSSL library
+looks for the random seed file
+\f\*[B-Font].rnd\f[]
+in the user home directory.
+However, there should be only one
+\f\*[B-Font].rnd\f[],
+most conveniently
+in the root directory, so it is convenient to define the
+\f\*[B-Font]$RANDFILE\f[]
+environment variable used by the OpenSSL library as the path to
+\f\*[B-Font]/.rnd\f[].
+.sp \n(Ppu
+.ne 2
+
+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
+\fI/etc\f[]
+using the
+\f\*[B-Font]keysdir\f[]
+command.
+There is no need for one client to read the keys and certificates
+of other clients or servers, as these data are obtained automatically
+by the Autokey protocol.
+.sp \n(Ppu
+.ne 2
+
+Ordinarily, cryptographic files are generated by the host that uses them,
+but it is possible for a trusted agent (TA) to generate these files
+for other hosts; however, in such cases files should always be encrypted.
+The subject name and trusted name default to the hostname
+of the host generating the files, but can be changed by command line options.
+It is convenient to designate the owner name and trusted name
+as the subject and issuer fields, respectively, of the certificate.
+The owner name is also used for the host and sign key files,
+while the trusted name is used for the identity files.
+.sp \n(Ppu
+.ne 2
+
+All files are installed by default in the keys directory
+\fI/usr/local/etc\f[],
+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.
+.sp \n(Ppu
+.ne 2
+
+Normally, files containing private values,
+including the host key, sign key and identification parameters,
+are permitted root read/write-only;
+while others containing public values are permitted world readable.
+Alternatively, files containing private values can be encrypted
+and these files permitted world readable,
+which simplifies maintenance in shared file systems.
+Since uniqueness is insured by the hostname and
+file name extensions, the files for a NFS server and
+dependent clients can all be installed in the same shared directory.
+.sp \n(Ppu
+.ne 2
+
+The recommended practice is to keep the file name extensions
+when installing a file and to install a soft link
+from the generic names specified elsewhere on this page
+to the generated files.
+This allows new file generations to be activated simply
+by changing the link.
+If a link is present, ntpd follows it to the file name
+to extract the filestamp.
+If a link is not present,
+\fCntpd\fR(@NTPD_MS@)\f[]
+extracts the filestamp from the file itself.
+This allows clients to verify that the file and generation times
+are always current.
+The
+\f\*[B-Font]ntp-keygen\fP
+program uses the same timestamp extension for all files generated
+at one time, so each generation is distinct and can be readily
+recognized in monitoring data.
+.SS Running the program
+The safest way to run the
+\f\*[B-Font]ntp-keygen\fP
+program is logged in directly as root.
+The recommended procedure is change to the keys directory,
+usually
+\fI/usr/local/etc\f[],
+then run the program.
+When run for the first time,
+or if all
+\f\*[B-Font]ntpkey\f[]
+files have been removed,
+the program generates a RSA host key file and matching RSA-MD5 certificate file,
+which is all that is necessary in many cases.
+The program also generates soft links from the generic names
+to the respective files.
+If run again, the program uses the same host key file,
+but generates a new certificate file and link.
+.sp \n(Ppu
+.ne 2
+
+The host key is used to encrypt the cookie when required and so must be RSA type.
+By default, the host key is also the sign key used to encrypt signatures.
+When necessary, a different sign key can be specified and this can be
+either RSA or DSA type.
+By default, the message digest type is MD5, but any combination
+of sign key type and message digest type supported by the OpenSSL library
+can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
+and RIPE160 message digest algorithms.
+However, the scheme specified in the certificate must be compatible
+with the sign key.
+Certificates using any digest algorithm are compatible with RSA sign keys;
+however, only SHA and SHA1 certificates are compatible with DSA sign keys.
+.sp \n(Ppu
+.ne 2
+
+Private/public key files and certificates are compatible with
+other OpenSSL applications and very likely other libraries as well.
+Certificates or certificate requests derived from them should be compatible
+with extant industry practice, although some users might find
+the interpretation of X509v3 extension fields somewhat liberal.
+However, the identification parameter files, although encoded
+as the other files, are probably not compatible with anything other than Autokey.
+.sp \n(Ppu
+.ne 2
+
+Running the program as other than root and using the Unix
+\f\*[B-Font]su\f[]
+command
+to assume root may not work properly, since by default the OpenSSL library
+looks for the random seed file
+\f\*[B-Font].rnd\f[]
+in the user home directory.
+However, there should be only one
+\f\*[B-Font].rnd\f[],
+most conveniently
+in the root directory, so it is convenient to define the
+\f\*[B-Font]$RANDFILE\f[]
+environment variable used by the OpenSSL library as the path to
+\f\*[B-Font]/.rnd\f[].
+.sp \n(Ppu
+.ne 2
+
+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
+\fI/etc\f[]
+using the
+\f\*[B-Font]keysdir\f[]
+command.
+There is no need for one client to read the keys and certificates
+of other clients or servers, as these data are obtained automatically
+by the Autokey protocol.
+.sp \n(Ppu
+.ne 2
+
+Ordinarily, cryptographic files are generated by the host that uses them,
+but it is possible for a trusted agent (TA) to generate these files
+for other hosts; however, in such cases files should always be encrypted.
+The subject name and trusted name default to the hostname
+of the host generating the files, but can be changed by command line options.
+It is convenient to designate the owner name and trusted name
+as the subject and issuer fields, respectively, of the certificate.
+The owner name is also used for the host and sign key files,
+while the trusted name is used for the identity files.
+seconds.
+seconds.
+s Trusted Hosts and Groups
+Each cryptographic configuration involves selection of a signature scheme
+and identification scheme, called a cryptotype,
+as explained in the
+\fIAuthentication\f[] \fIOptions\f[]
+section of
+\fCntp.conf\fR(5)\f[].
+The default cryptotype uses RSA encryption, MD5 message digest
+and TC identification.
+First, configure a NTP subnet including one or more low-stratum
+trusted hosts from which all other hosts derive synchronization
+directly or indirectly.
+Trusted hosts have trusted certificates;
+all other hosts have nontrusted certificates.
+These hosts will automatically and dynamically build authoritative
+certificate trails to one or more trusted hosts.
+A trusted group is the set of all hosts that have, directly or indirectly,
+a certificate trail ending at a trusted host.
+The trail is defined by static configuration file entries
+or dynamic means described on the
+\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[]
+section of
+\fCntp.conf\fR(5)\f[].
+.sp \n(Ppu
+.ne 2
+
+On each trusted host as root, change to the keys directory.
+To insure a fresh fileset, remove all
+\f\*[B-Font]ntpkey\f[]
+files.
+Then run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-T\f[]
+to generate keys and a trusted certificate.
+On all other hosts do the same, but leave off the
+\f\*[B-Font]\-T\f[]
+flag to generate keys and nontrusted certificates.
+When complete, start the NTP daemons beginning at the lowest stratum
+and working up the tree.
+It may take some time for Autokey to instantiate the certificate trails
+throughout the subnet, but setting up the environment is completely automatic.
+.sp \n(Ppu
+.ne 2
+
+If it is necessary to use a different sign key or different digest/signature
+scheme than the default, run
+\f\*[B-Font]ntp-keygen\fP
+with the
+\f\*[B-Font]\-S\f[] \f\*[I-Font]type\f[]
+option, where
+\f\*[I-Font]type\f[]
+is either
+\f\*[B-Font]RSA\f[]
+or
+\f\*[B-Font]DSA\f[].
+The most often need to do this is when a DSA-signed certificate is used.
+If it is necessary to use a different certificate scheme than the default,
+run
+\f\*[B-Font]ntp-keygen\fP
+with the
+\f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[]
+option and selected
+\f\*[I-Font]scheme\f[]
+as needed.
+f
+\f\*[B-Font]ntp-keygen\fP
+is run again without these options, it generates a new certificate
+using the same scheme and sign key.
+.sp \n(Ppu
+.ne 2
+
+After setting up the environment it is advisable to update certificates
+from time to time, if only to extend the validity interval.
+Simply run
+\f\*[B-Font]ntp-keygen\fP
+with the same flags as before to generate new certificates
+using existing keys.
+However, if the host or sign key is changed,
+\fCntpd\fR(@NTPD_MS@)\f[]
+should be restarted.
+When
+\fCntpd\fR(@NTPD_MS@)\f[]
+is restarted, it loads any new files and restarts the protocol.
+Other dependent hosts will continue as usual until signatures are refreshed,
+at which time the protocol is restarted.
+.SS Identity Schemes
+As mentioned on the Autonomous Authentication page,
+the default TC identity scheme is vulnerable to a middleman attack.
+However, there are more secure identity schemes available,
+including PC, IFF, GQ and MV described on the
+"Identification Schemes"
+page
+(maybe available at
+\f[C]http://www.eecis.udel.edu/%7emills/keygen.html\f[]).
+These schemes are based on a TA, one or more trusted hosts
+and some number of nontrusted hosts.
+Trusted hosts prove identity using values provided by the TA,
+while the remaining hosts prove identity using values provided
+by a trusted host and certificate trails that end on that host.
+The name of a trusted host is also the name of its sugroup
+and also the subject and issuer name on its trusted certificate.
+The TA is not necessarily a trusted host in this sense, but often is.
+.sp \n(Ppu
+.ne 2
+
+In some schemes there are separate keys for servers and clients.
+A server can also be a client of another server,
+but a client can never be a server for another client.
+In general, trusted hosts and nontrusted hosts that operate
+as both server and client have parameter files that contain
+both server and client keys.
+Hosts that operate
+only as clients have key files that contain only client keys.
+.sp \n(Ppu
+.ne 2
+
+The PC scheme supports only one trusted host in the group.
+On trusted host alice run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-P\f[]
+\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[]
+to generate the host key file
+\fIntpkey_RSAkey_\f[]\f\*[I-Font]alice.filestamp\f[]
+and trusted private certificate file
+\fIntpkey_RSA-MD5_cert_\f[]\f\*[I-Font]alice.filestamp\f[].
+Copy both files to all group hosts;
+they replace the files which would be generated in other schemes.
+On each host bob install a soft link from the generic name
+\fIntpkey_host_\f[]\f\*[I-Font]bob\f[]
+to the host key file and soft link
+\fIntpkey_cert_\f[]\f\*[I-Font]bob\f[]
+to the private certificate file.
+Note the generic links are on bob, but point to files generated
+by trusted host alice.
+In this scheme it is not possible to refresh
+either the keys or certificates without copying them
+to all other hosts in the group.
+.sp \n(Ppu
+.ne 2
+
+For the IFF scheme proceed as in the TC scheme to generate keys
+and certificates for all group hosts, then for every trusted host in the group,
+generate the IFF parameter file.
+On trusted host alice run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-T\f[]
+\f\*[B-Font]\-I\f[]
+\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[]
+to produce her parameter file
+\fIntpkey_IFFpar_\f[]\f\*[I-Font]alice.filestamp\f[],
+which includes both server and client keys.
+Copy this file to all group hosts that operate as both servers
+and clients and install a soft link from the generic
+\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[]
+to this file.
+If there are no hosts restricted to operate only as clients,
+there is nothing further to do.
+As the IFF scheme is independent
+of keys and certificates, these files can be refreshed as needed.
+.sp \n(Ppu
+.ne 2
+
+If a rogue client has the parameter file, it could masquerade
+as a legitimate server and present a middleman threat.
+To eliminate this threat, the client keys can be extracted
+from the parameter file and distributed to all restricted clients.
+After generating the parameter file, on alice run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-e\f[]
+and pipe the output to a file or mail program.
+Copy or mail this file to all restricted clients.
+On these clients install a soft link from the generic
+\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[]
+to this file.
+To further protect the integrity of the keys,
+each file can be encrypted with a secret password.
+.sp \n(Ppu
+.ne 2
+
+For the GQ scheme proceed as in the TC scheme to generate keys
+and certificates for all group hosts, then for every trusted host
+in the group, generate the IFF parameter file.
+On trusted host alice run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-T\f[]
+\f\*[B-Font]\-G\f[]
+\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[]
+to produce her parameter file
+\fIntpkey_GQpar_\f[]\f\*[I-Font]alice.filestamp\f[],
+which includes both server and client keys.
+Copy this file to all group hosts and install a soft link
+from the generic
+\fIntpkey_gq_\f[]\f\*[I-Font]alice\f[]
+to this file.
+In addition, on each host bob install a soft link
+from generic
+\fIntpkey_gq_\f[]\f\*[I-Font]bob\f[]
+to this file.
+As the GQ scheme updates the GQ parameters file and certificate
+at the same time, keys and certificates can be regenerated as needed.
+.sp \n(Ppu
+.ne 2
+
+For the MV scheme, proceed as in the TC scheme to generate keys
+and certificates for all group hosts.
+For illustration assume trish is the TA, alice one of several trusted hosts
+and bob one of her clients.
+On TA trish run
+\f\*[B-Font]ntp-keygen\fP
+\f\*[B-Font]\-V\f[] \f\*[I-Font]n\f[]
+\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[],
+where
+\f\*[I-Font]n\f[]
+is the number of revokable keys (typically 5) to produce
+the parameter file
+\fIntpkeys_MVpar_\f[]\f\*[I-Font]trish.filestamp\f[]
+and client key files
+\fIntpkeys_MVkeyd_\f[]\f\*[I-Font]trish.filestamp\f[]
+where
+\f\*[I-Font]d\f[]
+is the key number (0 \&<
+\f\*[I-Font]d\f[]
+\&<
+\f\*[I-Font]n\f[]).
+Copy the parameter file to alice and install a soft link
+from the generic
+\fIntpkey_mv_\f[]\f\*[I-Font]alice\f[]
+to this file.
+Copy one of the client key files to alice for later distribution
+to her clients.
+It doesn't matter which client key file goes to alice,
+since they all work the same way.
+Alice copies the client key file to all of her cliens.
+On client bob install a soft link from generic
+\fIntpkey_mvkey_\f[]\f\*[I-Font]bob\f[]
+to the client key file.
+As the MV scheme is independent of keys and certificates,
+these files can be refreshed as needed.
+.SS Command Line Options
+.TP 7
+.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[]
+Select certificate message digest/signature encryption scheme.
+The
+\f\*[I-Font]scheme\f[]
+can be one of the following:
+. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA ,
+or
+\f\*[B-Font]DSA-SHA1\f[].
+Note that RSA schemes must be used with a RSA sign key and DSA
+schemes must be used with a DSA sign key.
+The default without this option is
+\f\*[B-Font]RSA-MD5\f[].
+.TP 7
+.NOP \f\*[B-Font]\-d\f[]
+Enable debugging.
+This option displays the cryptographic data produced in eye-friendly billboards.
+.TP 7
+.NOP \f\*[B-Font]\-e\f[]
+Write the IFF client keys to the standard output.
+This is intended for automatic key distribution by mail.
+.TP 7
+.NOP \f\*[B-Font]\-G\f[]
+Generate parameters and keys for the GQ identification scheme,
+obsoleting any that may exist.
+.TP 7
+.NOP \f\*[B-Font]\-g\f[]
+Generate keys for the GQ identification scheme
+using the existing GQ parameters.
+If the GQ parameters do not yet exist, create them first.
+.TP 7
+.NOP \f\*[B-Font]\-H\f[]
+Generate new host keys, obsoleting any that may exist.
+.TP 7
+.NOP \f\*[B-Font]\-I\f[]
+Generate parameters for the IFF identification scheme,
+obsoleting any that may exist.
+.TP 7
+.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]name\f[]
+Set the suject name to
+\f\*[I-Font]name\f[].
+This is used as the subject field in certificates
+and in the file name for host and sign keys.
+.TP 7
+.NOP \f\*[B-Font]\-M\f[]
+Generate MD5 keys, obsoleting any that may exist.
+.TP 7
+.NOP \f\*[B-Font]\-P\f[]
+Generate a private certificate.
+By default, the program generates public certificates.
+.TP 7
+.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[]
+Encrypt generated files containing private data with
+\f\*[I-Font]password\f[]
+and the DES-CBC algorithm.
+.TP 7
+.NOP \f\*[B-Font]\-q\f[]
+Set the password for reading files to password.
+.TP 7
+.NOP \f\*[B-Font]\-S\f[] [\f\*[B-Font]RSA\f[] | \f\*[B-Font]DSA\f[]]
+Generate a new sign key of the designated type,
+obsoleting any that may exist.
+By default, the program uses the host key as the sign key.
+.TP 7
+.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]name\f[]
+Set the issuer name to
+\f\*[I-Font]name\f[].
+This is used for the issuer field in certificates
+and in the file name for identity files.
+.TP 7
+.NOP \f\*[B-Font]\-T\f[]
+Generate a trusted certificate.
+By default, the program generates a non-trusted certificate.
+.TP 7
+.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]nkeys\f[]
+Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme.
+.PP
+.SS Random Seed File
+All cryptographically sound 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.
+The OpenSSL library uses a designated random seed file for this purpose.
+The file must be available when starting the NTP daemon and
+\f\*[B-Font]ntp-keygen\fP
+program.
+If a site supports OpenSSL or its companion OpenSSH,
+it is very likely that means to do this are already available.
+.sp \n(Ppu
+.ne 2
+
+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.
+Suitable means are described in the OpenSSL software documentation,
+but are outside the scope of this page.
+.sp \n(Ppu
+.ne 2
+
+The entropy seed used by the OpenSSL library is contained in a file,
+usually called
+\f\*[B-Font].rnd\f[],
+which must be available when starting the NTP daemon
+or the
+\f\*[B-Font]ntp-keygen\fP
+program.
+The NTP daemon will first look for the file
+using the path specified by the
+\f\*[B-Font]randfile\f[]
+subcommand of the
+\f\*[B-Font]crypto\f[]
+configuration command.
+If not specified in this way, or when starting the
+\f\*[B-Font]ntp-keygen\fP
+program,
+the OpenSSL library will look for the file using the path specified
+by the
+RANDFILE
+environment variable in the user home directory,
+whether root or some other user.
+If the
+RANDFILE
+environment variable is not present,
+the library will look for the
+\f\*[B-Font].rnd\f[]
+file in the user home directory.
+If the file is not available or cannot be written,
+the daemon exits with a message to the system log and the program
+exits with a suitable error message.
+.SS Cryptographic Data Files
+All other file formats begin with two lines.
+The first contains the file name, including the generated host name
+and filestamp.
+The second contains the datestamp in conventional Unix date format.
+Lines beginning with # are considered comments and ignored by the
+\f\*[B-Font]ntp-keygen\fP
+program and
+\fCntpd\fR(@NTPD_MS@)\f[]
+daemon.
+Cryptographic values are encoded first using ASN.1 rules,
+then encrypted if necessary, and finally written PEM-encoded
+printable ASCII format preceded and followed by MIME content identifier lines.
+.sp \n(Ppu
+.ne 2
+
+The format of the symmetric keys file is somewhat different
+than the other files in the interest of backward compatibility.
+Since DES-CBC is deprecated in NTPv4, the only key format of interest
+is MD5 alphanumeric strings.
+Following hte heard the keys are
+entered one per line in the format
+.in +4
+\f\*[I-Font]keyno\f[] \f\*[I-Font]type\f[] \f\*[I-Font]key\f[]
+.in -4
+where
+\f\*[I-Font]keyno\f[]
+is a positive integer in the range 1-65,535,
+\f\*[I-Font]type\f[]
+is the string MD5 defining the key format and
+\f\*[I-Font]key\f[]
+is the key itself,
+which is a printable ASCII string 16 characters or less in length.
+Each character is chosen from the 93 printable characters
+in the range 0x21 through 0x7f excluding space and the
+\[oq]#\[cq]
+character.
+.sp \n(Ppu
+.ne 2
+
+Note that the keys used by the
+\fCntpq\fR(@NTPQ_MS@)\f[]
+and
+\fCntpdc\fR(@NTPDC_MS@)\f[]
+programs
+are checked against passwords requested by the programs
+and entered by hand, so it is generally appropriate to specify these keys
+in human readable ASCII format.
+.sp \n(Ppu
+.ne 2
+
+The
+\f\*[B-Font]ntp-keygen\fP
+program generates a MD5 symmetric keys file
+\fIntpkey_MD5key_\f[]\f\*[I-Font]hostname.filestamp\f[].
+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
+\fIntp.keys\f[],
+so
+\f\*[B-Font]ntp-keygen\fP
+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.
+While this file is not used with the Autokey Version 2 protocol,
+it is needed to authenticate some remote configuration commands
+used by the
+\fCntpq\fR(@NTPQ_MS@)\f[]
+and
+\fCntpdc\fR(@NTPDC_MS@)\f[]
+utilities.
+.SH "OPTIONS"
+.TP
+.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]imbits\f[], \f\*[B-Font]\-\-imbits\f[]=\f\*[I-Font]imbits\f[]
+identity modulus bits.
+This option takes an integer number as its argument.
+The value of
+\f\*[I-Font]imbits\f[]
+is constrained to being:
+.in +4
+.nf
+.na
+in the range  256 through 2048
+.fi
+.in -4
+.sp
+The number of bits in the identity modulus.  The default is 256.
+.TP
+.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[], \f\*[B-Font]\-\-certificate\f[]=\f\*[I-Font]scheme\f[]
+certificate scheme.
+.sp
+scheme is one of
+RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160,
+DSA-SHA, or DSA-SHA1.
+.sp
+Select the certificate message digest/signature encryption scheme.
+Note that RSA schemes must be used with a RSA sign key and DSA
+schemes must be used with a DSA sign key.  The default without
+this option is RSA-MD5.
+.TP
+.NOP \f\*[B-Font]\-C\f[] \f\*[I-Font]cipher\f[], \f\*[B-Font]\-\-cipher\f[]=\f\*[I-Font]cipher\f[]
+privatekey cipher.
+.sp
+Select the cipher which is used to encrypt the files containing
+private keys.  The default is three-key triple DES in CBC mode,
+equivalent to "@code{-C des-ede3-cbc".  The openssl tool lists ciphers
+available in "\fBopenssl \-h\fP" output.
+.TP
+.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[]
+Increase debug verbosity level.
+This option may appear an unlimited number of times.
+.sp
+.TP
+.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[]
+Set the debug verbosity level.
+This option may appear an unlimited number of times.
+This option takes an integer number as its argument.
+.sp
+.TP
+.NOP \f\*[B-Font]\-e\f[], \f\*[B-Font]\-\-id\-key\f[]
+Write IFF or GQ identity keys.
+.sp
+Write the IFF or GQ client keys to the standard output.  This is
+intended for automatic key distribution by mail.
+.TP
+.NOP \f\*[B-Font]\-G\f[], \f\*[B-Font]\-\-gq\-params\f[]
+Generate GQ parameters and keys.
+.sp
+Generate parameters and keys for the GQ identification scheme,
+obsoleting any that may exist.
+.TP
+.NOP \f\*[B-Font]\-H\f[], \f\*[B-Font]\-\-host\-key\f[]
+generate RSA host key.
+.sp
+Generate new host keys, obsoleting any that may exist.
+.TP
+.NOP \f\*[B-Font]\-I\f[], \f\*[B-Font]\-\-iffkey\f[]
+generate IFF parameters.
+.sp
+Generate parameters for the IFF identification scheme, obsoleting
+any that may exist.
+.TP
+.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]group\f[], \f\*[B-Font]\-\-ident\f[]=\f\*[I-Font]group\f[]
+set Autokey group name.
+.sp
+Set the optional Autokey group name to name.  This is used in
+the file name of IFF, GQ, and MV client parameters files.  In
+that role, the default is the host name if this option is not
+provided.  The group name, if specified using \fB-i/--ident\fP or
+using \fB-s/--subject-name\fP following an '\fB@\fP' character,
+is also a part of the self-signed host certificate's subject and
+issuer names in the form \fBhost@group\fP and should match the
+'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in
+\fBntpd\fP's configuration file. 
+.TP
+.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]lifetime\f[], \f\*[B-Font]\-\-lifetime\f[]=\f\*[I-Font]lifetime\f[]
+set certificate lifetime.
+This option takes an integer number as its argument.
+.sp
+Set the certificate expiration to lifetime days from now.
+.TP
+.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-md5key\f[]
+generate MD5 keys.
+.sp
+Generate MD5 keys, obsoleting any that may exist.
+.TP
+.NOP \f\*[B-Font]\-m\f[] \f\*[I-Font]modulus\f[], \f\*[B-Font]\-\-modulus\f[]=\f\*[I-Font]modulus\f[]
+modulus.
+This option takes an integer number as its argument.
+The value of
+\f\*[I-Font]modulus\f[]
+is constrained to being:
+.in +4
+.nf
+.na
+in the range  256 through 2048
+.fi
+.in -4
+.sp
+The number of bits in the prime modulus.  The default is 512.
+.TP
+.NOP \f\*[B-Font]\-P\f[], \f\*[B-Font]\-\-pvt\-cert\f[]
+generate PC private certificate.
+.sp
+Generate a private certificate.  By default, the program generates
+public certificates.
+.TP
+.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-password\f[]=\f\*[I-Font]passwd\f[]
+local private password.
+.sp
+Local files containing private data are encrypted with the
+DES-CBC algorithm and the specified password.  The same password
+must be specified to the local ntpd via the "crypto pw password"
+configuration command.  The default password is the local
+hostname.
+.TP
+.NOP \f\*[B-Font]\-q\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-export\-passwd\f[]=\f\*[I-Font]passwd\f[]
+export IFF or GQ group keys with password.
+.sp
+Export IFF or GQ identity group keys to the standard output,
+encrypted with the DES-CBC algorithm and the specified password.
+The same password must be specified to the remote ntpd via the
+"crypto pw password" configuration command.  See also the option
+--id-key (-e) for unencrypted exports.
+.TP
+.NOP \f\*[B-Font]\-S\f[] \f\*[I-Font]sign\f[], \f\*[B-Font]\-\-sign\-key\f[]=\f\*[I-Font]sign\f[]
+generate sign key (RSA or DSA).
+.sp
+Generate a new sign key of the designated type, obsoleting any
+that may exist.  By default, the program uses the host key as the
+sign key.
+.TP
+.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]host@group\f[], \f\*[B-Font]\-\-subject\-name\f[]=\f\*[I-Font]host@group\f[]
+set host and optionally group name.
+.sp
+Set the Autokey host name, and optionally, group name specified
+following an '\fB@\fP' character.  The host name is used in the file
+name of generated host and signing certificates, without the
+group name.  The host name, and if provided, group name are used
+in \fBhost@group\fP form for the host certificate's subject and issuer
+fields.  Specifying '\fB-s @group\fP' is allowed, and results in
+leaving the host name unchanged while appending \fB@group\fP to the
+subject and issuer fields, as with \fB-i group\fP.  The group name, or
+if not provided, the host name are also used in the file names
+of IFF, GQ, and MV client parameter files.
+.TP
+.NOP \f\*[B-Font]\-T\f[], \f\*[B-Font]\-\-trusted\-cert\f[]
+trusted certificate (TC scheme).
+.sp
+Generate a trusted certificate.  By default, the program generates
+a non-trusted certificate.
+.TP
+.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-params\f[]=\f\*[I-Font]num\f[]
+generate <num> MV parameters.
+This option takes an integer number as its argument.
+.sp
+Generate parameters and keys for the Mu-Varadharajan (MV)
+identification scheme.
+.TP
+.NOP \f\*[B-Font]\-v\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-keys\f[]=\f\*[I-Font]num\f[]
+update <num> MV keys.
+This option takes an integer number as its argument.
+.sp
+This option has not been fully documented.
+.TP
+.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[]
+Display usage information and exit.
+.TP
+.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
+Pass the extended usage information through a pager.
+.TP
+.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
+Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+The command will exit after updating the config file.
+.TP
+.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
+Load options from \fIcfgfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
+out of order.
+.TP
+.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]
+Output version of program and exit.  The default mode is `v', a simple
+version.  The `c' mode will print copyright information and `n' will
+print the full copyright notice.
+.PP
+.SH "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from configuration ("RC" or ".INI") file(s) and values from
+environment variables named:
+.nf
+  \fBNTP_KEYGEN_<option-name>\fP or \fBNTP_KEYGEN\fP
+.fi
+.ad
+The environmental presets take precedence (are processed later than)
+the configuration files.
+The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
+If any of these are directories, then the file \fI.ntprc\fP
+is searched for within those directories.
+.SH USAGE
+The
+\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[]
+option specifies the write password and
+\f\*[B-Font]\-q\f[] \f\*[I-Font]password\f[]
+option the read password for previously encrypted files.
+The
+\f\*[B-Font]ntp-keygen\fP
+program prompts for the password if it reads an encrypted file
+and the password is missing or incorrect.
+If an encrypted file is read successfully and
+no write password is specified, the read password is used
+as the write password by default.
+.SH "ENVIRONMENT"
+See \fBOPTION PRESETS\fP for configuration environment variables.
+.SH "FILES"
+See \fBOPTION PRESETS\fP for configuration files.
+.SH "EXIT STATUS"
+One of the following exit values will be returned:
+.TP
+.NOP 0 " (EXIT_SUCCESS)"
+Successful program execution.
+.TP
+.NOP 1 " (EXIT_FAILURE)"
+The operation failed or the command syntax was not valid.
+.TP
+.NOP 66 " (EX_NOINPUT)"
+A specified configuration file could not be loaded.
+.TP
+.NOP 70 " (EX_SOFTWARE)"
+libopts had an internal operational error.  Please report
+it to autogen-users@lists.sourceforge.net.  Thank you.
+.PP
+.SH "AUTHORS"
+The University of Delaware and Network Time Foundation
+.SH "COPYRIGHT"
+Copyright (C) 1992-2015 The University of Delaware and Network Time Foundation all rights reserved.
+This program is released under the terms of the NTP license, <http://ntp.org/license>.
+.SH BUGS
+It can take quite a while to generate some cryptographic values,
+from one to several minutes with modern architectures
+such as UltraSPARC and up to tens of minutes to an hour
+with older architectures such as SPARC IPC.
+.sp \n(Ppu
+.ne 2
+
+Please report bugs to http://bugs.ntp.org .
+.sp \n(Ppu
+.ne 2
+
+Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
+.SH NOTES
+Portions of this document came from FreeBSD.
+.sp \n(Ppu
+.ne 2
+
+This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP
+option definitions.