2020-06-24 00:20:45 +00:00
|
|
|
.Dd June 23 2020
|
2014-12-20 22:52:39 +00:00
|
|
|
.Dt NTP_KEYGEN @NTP_KEYGEN_MS@ User Commands
|
|
|
|
.Os
|
|
|
|
.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc)
|
|
|
|
.\"
|
2020-06-24 00:20:45 +00:00
|
|
|
.\" It has been AutoGen-ed June 23, 2020 at 02:21:05 AM by AutoGen 5.18.5
|
2014-12-20 22:52:39 +00:00
|
|
|
.\" From the definitions ntp-keygen-opts.def
|
|
|
|
.\" and the template file agmdoc-cmd.tpl
|
|
|
|
.Sh NAME
|
|
|
|
.Nm ntp-keygen
|
|
|
|
.Nd Create a NTP host key
|
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm
|
|
|
|
.\" Mixture of short (flag) options and long options
|
|
|
|
.Op Fl flags
|
|
|
|
.Op Fl flag Op Ar value
|
|
|
|
.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
|
|
|
|
.Pp
|
|
|
|
All arguments must be options.
|
|
|
|
.Pp
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
This program generates cryptographic data files used by the NTPv4
|
|
|
|
authentication and identification schemes.
|
2018-02-28 06:23:12 +00:00
|
|
|
It can generate message digest keys used in symmetric key cryptography and,
|
|
|
|
if the OpenSSL software library has been installed, it can generate host keys,
|
|
|
|
signing keys, certificates, and identity keys and parameters used in Autokey
|
|
|
|
public key cryptography.
|
2014-12-20 22:52:39 +00:00
|
|
|
These files are used for cookie encryption,
|
2018-02-28 06:23:12 +00:00
|
|
|
digital signature, and challenge/response identification algorithms
|
2014-12-20 22:52:39 +00:00
|
|
|
compatible with the Internet standard security infrastructure.
|
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
The message digest symmetric keys file is generated in a format
|
|
|
|
compatible with NTPv3.
|
|
|
|
All other files are in PEM\-encoded printable ASCII format,
|
|
|
|
so they can be embedded as MIME attachments in email to other sites
|
2014-12-20 22:52:39 +00:00
|
|
|
and certificate authorities.
|
|
|
|
By default, files are not encrypted.
|
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
When used to generate message digest symmetric keys, the program
|
|
|
|
produces a file containing ten pseudo\-random printable ASCII strings
|
|
|
|
suitable for the MD5 message digest algorithm included in the
|
|
|
|
distribution.
|
2014-12-20 22:52:39 +00:00
|
|
|
If the OpenSSL library is installed, it produces an additional ten
|
2018-02-28 06:23:12 +00:00
|
|
|
hex\-encoded random bit strings suitable for SHA1, AES\-128\-CMAC, and
|
|
|
|
other message digest algorithms.
|
|
|
|
The message digest symmetric keys file must be distributed and stored
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
|
|
|
.Xr ntpq @NTPQ_MS@
|
|
|
|
and
|
|
|
|
.Xr ntpdc @NTPDC_MS@
|
|
|
|
utility programs.
|
|
|
|
.Pp
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
Some files used by this program are encrypted using a private password.
|
|
|
|
The
|
|
|
|
.Fl p
|
2018-02-28 06:23:12 +00:00
|
|
|
option specifies the read password for local encrypted files and the
|
2014-12-20 22:52:39 +00:00
|
|
|
.Fl q
|
2018-02-28 06:23:12 +00:00
|
|
|
option the write password for encrypted files sent to remote sites.
|
2014-12-20 22:52:39 +00:00
|
|
|
If no password is specified, the host name returned by the Unix
|
2018-02-28 06:23:12 +00:00
|
|
|
.Xr hostname 1
|
|
|
|
command, normally the DNS name of the host, is used as the the default read
|
|
|
|
password, for convenience.
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
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.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
The
|
2018-02-28 06:23:12 +00:00
|
|
|
.Cm pw
|
2014-12-20 22:52:39 +00:00
|
|
|
option of the
|
2018-02-28 06:23:12 +00:00
|
|
|
.Ic crypto
|
|
|
|
.Xr ntpd @NTPD_MS@
|
2014-12-20 22:52:39 +00:00
|
|
|
configuration command specifies the read
|
|
|
|
password for previously encrypted local files.
|
2018-02-28 06:23:12 +00:00
|
|
|
This must match the local read password used by this program.
|
2014-12-20 22:52:39 +00:00
|
|
|
If not specified, the host name is used.
|
2018-02-28 06:23:12 +00:00
|
|
|
Thus, if files are generated by this program without an explicit password,
|
2014-12-20 22:52:39 +00:00
|
|
|
they can be read back by
|
2018-02-28 06:23:12 +00:00
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
without specifying an explicit password but only on the same host.
|
|
|
|
If the write password used for encryption is specified as the host name,
|
|
|
|
these files can be read by that host with no explicit password.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntp.keys ,
|
2014-12-20 22:52:39 +00:00
|
|
|
is usually installed in
|
|
|
|
.Pa /etc .
|
|
|
|
Other files and links are usually installed in
|
|
|
|
.Pa /usr/local/etc ,
|
|
|
|
which is normally in a shared filesystem in
|
|
|
|
NFS\-mounted networks and cannot be changed by shared clients.
|
2018-02-28 06:23:12 +00:00
|
|
|
In these cases, NFS clients can specify the files in another
|
|
|
|
directory such as
|
|
|
|
.Pa /etc
|
|
|
|
using the
|
|
|
|
.Ic keysdir
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
configuration file command.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
This program directs commentary and error messages to the standard
|
|
|
|
error stream
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa stderr
|
2014-12-20 22:52:39 +00:00
|
|
|
and remote files to the standard output stream
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa stdout
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey\&*
|
2014-12-20 22:52:39 +00:00
|
|
|
and include the file type, generating host and filestamp,
|
|
|
|
as described in the
|
2018-02-28 06:23:12 +00:00
|
|
|
.Sx "Cryptographic Data Files"
|
2014-12-20 22:52:39 +00:00
|
|
|
section below.
|
|
|
|
.Ss Running the Program
|
|
|
|
The safest way to run the
|
|
|
|
.Nm
|
|
|
|
program is logged in directly as root.
|
2018-02-28 06:23:12 +00:00
|
|
|
The recommended procedure is change to the
|
|
|
|
.Ar keys
|
|
|
|
directory, usually
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pa /usr/local/etc ,
|
|
|
|
then run the program.
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pp
|
|
|
|
To test and gain experience with Autokey concepts, log in as root and
|
|
|
|
change to the
|
|
|
|
.Ar keys
|
|
|
|
directory, usually
|
|
|
|
.Pa /usr/local/etc .
|
|
|
|
When run for the first time, or if all files with names beginning with
|
|
|
|
.Pa ntpkey\&*
|
|
|
|
have been removed, use the
|
|
|
|
.Nm
|
|
|
|
command without arguments to generate a default
|
|
|
|
.Cm RSA
|
|
|
|
host key and matching
|
|
|
|
.Cm RSA\-MD5
|
|
|
|
certificate file with expiration date one year hence,
|
2014-12-20 22:52:39 +00:00
|
|
|
which is all that is necessary in many cases.
|
|
|
|
The program also generates soft links from the generic names
|
|
|
|
to the respective files.
|
2018-02-28 06:23:12 +00:00
|
|
|
If run again without options, the program uses the
|
|
|
|
existing keys and parameters and generates a new certificate file with
|
|
|
|
new expiration date one year hence, and soft link.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
The host key is used to encrypt the cookie when required and so must be
|
|
|
|
.Cm RSA
|
|
|
|
type.
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
either
|
|
|
|
.Cm RSA
|
|
|
|
or
|
|
|
|
.Cm DSA
|
|
|
|
type.
|
|
|
|
By default, the message digest type is
|
|
|
|
.Cm MD5 ,
|
|
|
|
but any combination
|
2014-12-20 22:52:39 +00:00
|
|
|
of sign key type and message digest type supported by the OpenSSL library
|
2018-02-28 06:23:12 +00:00
|
|
|
can be specified, including those using the
|
|
|
|
.Cm AES128CMAC , MD2 , MD5 , MDC2 , SHA , SHA1
|
|
|
|
and
|
|
|
|
.Cm RIPE160
|
|
|
|
message digest algorithms.
|
2014-12-20 22:52:39 +00:00
|
|
|
However, the scheme specified in the certificate must be compatible
|
|
|
|
with the sign key.
|
2018-02-28 06:23:12 +00:00
|
|
|
Certificates using any digest algorithm are compatible with
|
|
|
|
.Cm RSA
|
|
|
|
sign keys;
|
|
|
|
however, only
|
|
|
|
.Cm SHA
|
|
|
|
and
|
|
|
|
.Cm SHA1
|
|
|
|
certificates are compatible with
|
|
|
|
.Cm DSA
|
|
|
|
sign keys.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
Running the program as other than root and using the Unix
|
2018-02-28 06:23:12 +00:00
|
|
|
.Xr su 1
|
2014-12-20 22:52:39 +00:00
|
|
|
command
|
|
|
|
to assume root may not work properly, since by default the OpenSSL library
|
|
|
|
looks for the random seed file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa .rnd
|
2014-12-20 22:52:39 +00:00
|
|
|
in the user home directory.
|
|
|
|
However, there should be only one
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa .rnd ,
|
2014-12-20 22:52:39 +00:00
|
|
|
most conveniently
|
|
|
|
in the root directory, so it is convenient to define the
|
2018-02-28 06:23:12 +00:00
|
|
|
.Ev RANDFILE
|
2014-12-20 22:52:39 +00:00
|
|
|
environment variable used by the OpenSSL library as the path to
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa .rnd .
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
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
|
|
|
|
.Pa /etc
|
|
|
|
using the
|
|
|
|
.Ic keysdir
|
2018-02-28 06:23:12 +00:00
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
configuration file command.
|
2014-12-20 22:52:39 +00:00
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
All files are installed by default in the keys directory
|
|
|
|
.Pa /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.
|
|
|
|
.Pp
|
|
|
|
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.
|
2018-02-28 06:23:12 +00:00
|
|
|
Since uniqueness is insured by the
|
|
|
|
.Ar hostname
|
|
|
|
and
|
|
|
|
.Ar filestamp
|
|
|
|
file name extensions, the files for an NTP server and
|
2014-12-20 22:52:39 +00:00
|
|
|
dependent clients can all be installed in the same shared directory.
|
|
|
|
.Pp
|
|
|
|
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.
|
2018-02-28 06:23:12 +00:00
|
|
|
If a link is present,
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
follows it to the file name to extract the
|
|
|
|
.Ar filestamp .
|
2014-12-20 22:52:39 +00:00
|
|
|
If a link is not present,
|
|
|
|
.Xr ntpd @NTPD_MS@
|
2018-02-28 06:23:12 +00:00
|
|
|
extracts the
|
|
|
|
.Ar filestamp
|
|
|
|
from the file itself.
|
2014-12-20 22:52:39 +00:00
|
|
|
This allows clients to verify that the file and generation times
|
|
|
|
are always current.
|
|
|
|
The
|
|
|
|
.Nm
|
2018-02-28 06:23:12 +00:00
|
|
|
program uses the same
|
|
|
|
.Ar filestamp
|
|
|
|
extension for all files generated
|
2014-12-20 22:52:39 +00:00
|
|
|
at one time, so each generation is distinct and can be readily
|
|
|
|
recognized in monitoring data.
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pp
|
|
|
|
Run the command on as many hosts as necessary.
|
|
|
|
Designate one of them as the trusted host (TH) using
|
2014-12-20 22:52:39 +00:00
|
|
|
.Nm
|
2018-02-28 06:23:12 +00:00
|
|
|
with the
|
|
|
|
.Fl T
|
|
|
|
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.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
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
|
|
|
|
.Fl S
|
|
|
|
option and this can be either
|
|
|
|
.Cm RSA
|
|
|
|
or
|
|
|
|
.Cm DSA
|
|
|
|
type.
|
|
|
|
By default, the signature
|
|
|
|
message digest type is
|
|
|
|
.Cm MD5 ,
|
|
|
|
but any combination of sign key type and
|
|
|
|
message digest type supported by the OpenSSL library can be specified
|
|
|
|
using the
|
|
|
|
.Fl c
|
|
|
|
option.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
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.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
Additional information on trusted groups and identity schemes is on the
|
|
|
|
.Dq Autokey Public\-Key Authentication
|
|
|
|
page.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
File names begin with the prefix
|
|
|
|
.Pa ntpkey Ns _
|
|
|
|
and end with the suffix
|
|
|
|
.Pa _ Ns Ar hostname . Ar filestamp ,
|
|
|
|
where
|
|
|
|
.Ar hostname
|
|
|
|
is the owner name, usually the string returned
|
|
|
|
by the Unix
|
|
|
|
.Xr hostname 1
|
|
|
|
command, and
|
|
|
|
.Ar 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
|
|
|
|
.Ic rm Pa ntpkey\&*
|
|
|
|
command or all files generated
|
|
|
|
at a specific time can be removed by a
|
|
|
|
.Ic rm Pa \&* Ns Ar filestamp
|
2014-12-20 22:52:39 +00:00
|
|
|
command.
|
2018-02-28 06:23:12 +00:00
|
|
|
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.
|
|
|
|
.Ss Trusted Hosts and Groups
|
2014-12-20 22:52:39 +00:00
|
|
|
Each cryptographic configuration involves selection of a signature scheme
|
|
|
|
and identification scheme, called a cryptotype,
|
|
|
|
as explained in the
|
|
|
|
.Sx Authentication Options
|
|
|
|
section of
|
|
|
|
.Xr ntp.conf 5 .
|
2018-02-28 06:23:12 +00:00
|
|
|
The default cryptotype uses
|
|
|
|
.Cm RSA
|
|
|
|
encryption,
|
|
|
|
.Cm MD5
|
|
|
|
message digest
|
|
|
|
and
|
|
|
|
.Cm TC
|
|
|
|
identification.
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
|
|
|
.Sx Automatic NTP Configuration Options
|
|
|
|
section of
|
|
|
|
.Xr ntp.conf 5 .
|
|
|
|
.Pp
|
|
|
|
On each trusted host as root, change to the keys directory.
|
|
|
|
To insure a fresh fileset, remove all
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey
|
2014-12-20 22:52:39 +00:00
|
|
|
files.
|
|
|
|
Then run
|
|
|
|
.Nm
|
|
|
|
.Fl T
|
|
|
|
to generate keys and a trusted certificate.
|
|
|
|
On all other hosts do the same, but leave off the
|
|
|
|
.Fl T
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
If it is necessary to use a different sign key or different digest/signature
|
|
|
|
scheme than the default, run
|
|
|
|
.Nm
|
|
|
|
with the
|
|
|
|
.Fl S Ar type
|
|
|
|
option, where
|
|
|
|
.Ar type
|
|
|
|
is either
|
|
|
|
.Cm RSA
|
|
|
|
or
|
|
|
|
.Cm DSA .
|
2018-02-28 06:23:12 +00:00
|
|
|
The most frequent need to do this is when a
|
|
|
|
.Cm DSA Ns \-signed
|
|
|
|
certificate is used.
|
2014-12-20 22:52:39 +00:00
|
|
|
If it is necessary to use a different certificate scheme than the default,
|
|
|
|
run
|
|
|
|
.Nm
|
|
|
|
with the
|
|
|
|
.Fl c Ar scheme
|
|
|
|
option and selected
|
|
|
|
.Ar scheme
|
|
|
|
as needed.
|
2018-02-28 06:23:12 +00:00
|
|
|
If
|
2014-12-20 22:52:39 +00:00
|
|
|
.Nm
|
|
|
|
is run again without these options, it generates a new certificate
|
2018-02-28 06:23:12 +00:00
|
|
|
using the same scheme and sign key, and soft link.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
After setting up the environment it is advisable to update certificates
|
|
|
|
from time to time, if only to extend the validity interval.
|
|
|
|
Simply run
|
|
|
|
.Nm
|
|
|
|
with the same flags as before to generate new certificates
|
2018-02-28 06:23:12 +00:00
|
|
|
using existing keys, and soft links.
|
2014-12-20 22:52:39 +00:00
|
|
|
However, if the host or sign key is changed,
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
should be restarted.
|
|
|
|
When
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
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,
|
2018-02-28 06:23:12 +00:00
|
|
|
the default
|
|
|
|
.Cm TC
|
|
|
|
identity scheme is vulnerable to a middleman attack.
|
2014-12-20 22:52:39 +00:00
|
|
|
However, there are more secure identity schemes available,
|
2018-02-28 06:23:12 +00:00
|
|
|
including
|
|
|
|
.Cm PC , IFF , GQ
|
|
|
|
and
|
|
|
|
.Cm MV
|
|
|
|
schemes described below.
|
2014-12-20 22:52:39 +00:00
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
The PC scheme supports only one trusted host in the group.
|
|
|
|
On trusted host alice run
|
|
|
|
.Nm
|
|
|
|
.Fl P
|
|
|
|
.Fl p Ar password
|
|
|
|
to generate the host key file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey Ns _ Cm RSA Pa key_alice. Ar filestamp
|
2014-12-20 22:52:39 +00:00
|
|
|
and trusted private certificate file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey Ns _ Cm RSA\-MD5 _ Pa cert_alice. Ar filestamp ,
|
|
|
|
and soft links.
|
2014-12-20 22:52:39 +00:00
|
|
|
Copy both files to all group hosts;
|
|
|
|
they replace the files which would be generated in other schemes.
|
2018-02-28 06:23:12 +00:00
|
|
|
On each host
|
|
|
|
.Ar bob
|
|
|
|
install a soft link from the generic name
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pa ntpkey_host_ Ns Ar bob
|
|
|
|
to the host key file and soft link
|
|
|
|
.Pa ntpkey_cert_ Ns Ar bob
|
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
to all other hosts in the group, and recreating the soft links.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
For the
|
|
|
|
.Cm IFF
|
|
|
|
scheme proceed as in the
|
|
|
|
.Cm TC
|
|
|
|
scheme to generate keys
|
2014-12-20 22:52:39 +00:00
|
|
|
and certificates for all group hosts, then for every trusted host in the group,
|
2018-02-28 06:23:12 +00:00
|
|
|
generate the
|
|
|
|
.Cm IFF
|
|
|
|
parameter file.
|
2014-12-20 22:52:39 +00:00
|
|
|
On trusted host alice run
|
|
|
|
.Nm
|
|
|
|
.Fl T
|
|
|
|
.Fl I
|
|
|
|
.Fl p Ar password
|
|
|
|
to produce her parameter file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_IFFpar_alice. Ns Ar filestamp ,
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_iff_alice
|
2014-12-20 22:52:39 +00:00
|
|
|
to this file.
|
|
|
|
If there are no hosts restricted to operate only as clients,
|
|
|
|
there is nothing further to do.
|
2018-02-28 06:23:12 +00:00
|
|
|
As the
|
|
|
|
.Cm IFF
|
|
|
|
scheme is independent
|
2014-12-20 22:52:39 +00:00
|
|
|
of keys and certificates, these files can be refreshed as needed.
|
|
|
|
.Pp
|
|
|
|
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
|
|
|
|
.Nm
|
|
|
|
.Fl e
|
2018-02-28 06:23:12 +00:00
|
|
|
and pipe the output to a file or email program.
|
|
|
|
Copy or email this file to all restricted clients.
|
2014-12-20 22:52:39 +00:00
|
|
|
On these clients install a soft link from the generic
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_iff_alice
|
2014-12-20 22:52:39 +00:00
|
|
|
to this file.
|
|
|
|
To further protect the integrity of the keys,
|
|
|
|
each file can be encrypted with a secret password.
|
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
For the
|
|
|
|
.Cm GQ
|
|
|
|
scheme proceed as in the
|
|
|
|
.Cm TC
|
|
|
|
scheme to generate keys
|
2014-12-20 22:52:39 +00:00
|
|
|
and certificates for all group hosts, then for every trusted host
|
2018-02-28 06:23:12 +00:00
|
|
|
in the group, generate the
|
|
|
|
.Cm IFF
|
|
|
|
parameter file.
|
2014-12-20 22:52:39 +00:00
|
|
|
On trusted host alice run
|
|
|
|
.Nm
|
|
|
|
.Fl T
|
|
|
|
.Fl G
|
|
|
|
.Fl p Ar password
|
|
|
|
to produce her parameter file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_GQpar_alice. Ns Ar filestamp ,
|
2014-12-20 22:52:39 +00:00
|
|
|
which includes both server and client keys.
|
|
|
|
Copy this file to all group hosts and install a soft link
|
|
|
|
from the generic
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_gq_alice
|
2014-12-20 22:52:39 +00:00
|
|
|
to this file.
|
2018-02-28 06:23:12 +00:00
|
|
|
In addition, on each host
|
|
|
|
.Ar bob
|
|
|
|
install a soft link
|
2014-12-20 22:52:39 +00:00
|
|
|
from generic
|
|
|
|
.Pa ntpkey_gq_ Ns Ar bob
|
|
|
|
to this file.
|
2018-02-28 06:23:12 +00:00
|
|
|
As the
|
|
|
|
.Cm GQ
|
|
|
|
scheme updates the
|
|
|
|
.Cm GQ
|
|
|
|
parameters file and certificate
|
2014-12-20 22:52:39 +00:00
|
|
|
at the same time, keys and certificates can be regenerated as needed.
|
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
For the
|
|
|
|
.Cm MV
|
|
|
|
scheme, proceed as in the
|
|
|
|
.Cm TC
|
|
|
|
scheme to generate keys
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
|
|
|
.Nm
|
|
|
|
.Fl V Ar n
|
|
|
|
.Fl p Ar password ,
|
|
|
|
where
|
|
|
|
.Ar n
|
|
|
|
is the number of revokable keys (typically 5) to produce
|
|
|
|
the parameter file
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkeys_MVpar_trish. Ns Ar filestamp
|
2014-12-20 22:52:39 +00:00
|
|
|
and client key files
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkeys_MVkey Ns Ar d _ Pa trish. Ar filestamp
|
2014-12-20 22:52:39 +00:00
|
|
|
where
|
|
|
|
.Ar d
|
|
|
|
is the key number (0 \&<
|
|
|
|
.Ar d
|
|
|
|
\&<
|
|
|
|
.Ar n ) .
|
|
|
|
Copy the parameter file to alice and install a soft link
|
|
|
|
from the generic
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_mv_alice
|
2014-12-20 22:52:39 +00:00
|
|
|
to this file.
|
|
|
|
Copy one of the client key files to alice for later distribution
|
|
|
|
to her clients.
|
2018-02-28 06:23:12 +00:00
|
|
|
It does not matter which client key file goes to alice,
|
2014-12-20 22:52:39 +00:00
|
|
|
since they all work the same way.
|
2018-02-28 06:23:12 +00:00
|
|
|
Alice copies the client key file to all of her clients.
|
2014-12-20 22:52:39 +00:00
|
|
|
On client bob install a soft link from generic
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa ntpkey_mvkey_bob
|
2014-12-20 22:52:39 +00:00
|
|
|
to the client key file.
|
2018-02-28 06:23:12 +00:00
|
|
|
As the
|
|
|
|
.Cm MV
|
|
|
|
scheme is independent of keys and certificates,
|
2014-12-20 22:52:39 +00:00
|
|
|
these files can be refreshed as needed.
|
|
|
|
.Ss Command Line Options
|
|
|
|
.Bl -tag -width indent
|
2018-02-28 06:23:12 +00:00
|
|
|
.It Fl b Fl \-imbits Ns = Ar modulus
|
|
|
|
Set the number of bits in the identity modulus for generating identity keys to
|
|
|
|
.Ar modulus
|
|
|
|
bits.
|
|
|
|
The number of bits in the identity modulus defaults to 256, but can be set to
|
|
|
|
values from 256 to 2048 (32 to 256 octets).
|
|
|
|
Use the larger moduli with caution, as this can consume considerable computing
|
|
|
|
resources and increases the size of authenticated packets.
|
|
|
|
.It Fl c Fl \-certificate Ns = Ar scheme
|
|
|
|
Select certificate signature encryption/message digest scheme.
|
2014-12-20 22:52:39 +00:00
|
|
|
The
|
|
|
|
.Ar scheme
|
|
|
|
can be one of the following:
|
2018-02-28 06:23:12 +00:00
|
|
|
.Cm RSA\-MD2 , RSA\-MD5 , RSA\-MDC2 , RSA\-SHA , RSA\-SHA1 , RSA\-RIPEMD160 , DSA\-SHA ,
|
2014-12-20 22:52:39 +00:00
|
|
|
or
|
|
|
|
.Cm DSA\-SHA1 .
|
2018-02-28 06:23:12 +00:00
|
|
|
Note that
|
|
|
|
.Cm RSA
|
|
|
|
schemes must be used with an
|
|
|
|
.Cm RSA
|
|
|
|
sign key and
|
|
|
|
.Cm DSA
|
|
|
|
schemes must be used with a
|
|
|
|
.Cm DSA
|
|
|
|
sign key.
|
2014-12-20 22:52:39 +00:00
|
|
|
The default without this option is
|
|
|
|
.Cm RSA\-MD5 .
|
2018-02-28 06:23:12 +00:00
|
|
|
If compatibility with FIPS 140\-2 is required, either the
|
|
|
|
.Cm DSA\-SHA
|
|
|
|
or
|
|
|
|
.Cm DSA\-SHA1
|
|
|
|
scheme must be used.
|
|
|
|
.It Fl C Fl \-cipher Ns = Ar cipher
|
|
|
|
Select the OpenSSL cipher to encrypt the files containing private keys.
|
|
|
|
The default without this option is three\-key triple DES in CBC mode,
|
|
|
|
.Cm des\-ede3\-cbc .
|
|
|
|
The
|
|
|
|
.Ic openssl Fl h
|
|
|
|
command provided with OpenSSL displays available ciphers.
|
|
|
|
.It Fl d Fl \-debug\-level
|
|
|
|
Increase debugging verbosity level.
|
2014-12-20 22:52:39 +00:00
|
|
|
This option displays the cryptographic data produced in eye\-friendly billboards.
|
2018-02-28 06:23:12 +00:00
|
|
|
.It Fl D Fl \-set\-debug\-level Ns = Ar level
|
|
|
|
Set the debugging verbosity to
|
|
|
|
.Ar level .
|
|
|
|
This option displays the cryptographic data produced in eye\-friendly billboards.
|
|
|
|
.It Fl e Fl \-id\-key
|
|
|
|
Write the
|
|
|
|
.Cm IFF
|
|
|
|
or
|
|
|
|
.Cm GQ
|
|
|
|
public parameters from the
|
|
|
|
.Ar IFFkey or GQkey
|
|
|
|
client keys file previously specified
|
|
|
|
as unencrypted data to the standard output stream
|
|
|
|
.Pa stdout .
|
|
|
|
This is intended for automatic key distribution by email.
|
|
|
|
.It Fl G Fl \-gq\-params
|
|
|
|
Generate a new encrypted
|
|
|
|
.Cm GQ
|
|
|
|
parameters and key file for the Guillou\-Quisquater (GQ) identity scheme.
|
|
|
|
This option is mutually exclusive with the
|
|
|
|
.Fl I
|
|
|
|
and
|
|
|
|
.Fl V
|
|
|
|
options.
|
|
|
|
.It Fl H Fl \-host\-key
|
|
|
|
Generate a new encrypted
|
|
|
|
.Cm RSA
|
|
|
|
public/private host key file.
|
|
|
|
.It Fl I Fl \-iffkey
|
|
|
|
Generate a new encrypted
|
|
|
|
.Cm IFF
|
|
|
|
key file for the Schnorr (IFF) identity scheme.
|
|
|
|
This option is mutually exclusive with the
|
|
|
|
.Fl G
|
|
|
|
and
|
|
|
|
Fl V
|
|
|
|
options.
|
|
|
|
.It Fl i Fl \-ident Ns = Ar group
|
|
|
|
Set the optional Autokey group name to
|
|
|
|
.Ar group .
|
|
|
|
This is used in the identity scheme parameter file names of
|
|
|
|
.Cm IFF , GQ ,
|
|
|
|
and
|
|
|
|
.Cm MV
|
|
|
|
client parameters files.
|
|
|
|
In that role, the default is the host name if no group is provided.
|
|
|
|
The group name, if specified using
|
|
|
|
.Fl i
|
|
|
|
or
|
|
|
|
.Fl s
|
|
|
|
following an
|
|
|
|
.Ql @
|
|
|
|
character, is also used in certificate subject and issuer names in the form
|
|
|
|
.Ar host @ group
|
|
|
|
and should match the group specified via
|
|
|
|
.Ic crypto Cm ident
|
|
|
|
or
|
|
|
|
.Ic server Cm ident
|
|
|
|
in the ntpd configuration file.
|
|
|
|
.It Fl l Fl \-lifetime Ns = Ar days
|
|
|
|
Set the lifetime for certificate expiration to
|
|
|
|
.Ar days .
|
|
|
|
The default lifetime is one year (365 days).
|
|
|
|
.It Fl m Fl \-modulus Ns = Ar bits
|
|
|
|
Set the number of bits in the prime modulus for generating files to
|
|
|
|
.Ar bits .
|
|
|
|
The modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets).
|
|
|
|
Use the larger moduli with caution, as this can consume considerable computing
|
|
|
|
resources and increases the size of authenticated packets.
|
|
|
|
.It Fl M Fl \-md5key
|
|
|
|
Generate a new symmetric keys file containing 10
|
|
|
|
.Cm MD5
|
|
|
|
keys, and if OpenSSL is available, 10
|
|
|
|
.Cm SHA
|
|
|
|
keys.
|
|
|
|
An
|
|
|
|
.Cm MD5
|
|
|
|
key is a string of 20 random printable ASCII characters, while a
|
|
|
|
.Cm SHA
|
|
|
|
key is a string of 40 random hex digits.
|
|
|
|
The file can be edited using a text editor to change the key type or key content.
|
|
|
|
This option is mutually exclusive with all other options.
|
|
|
|
.It Fl p Fl \-password Ns = Ar passwd
|
|
|
|
Set the password for reading and writing encrypted files to
|
|
|
|
.Ar passwd .
|
|
|
|
These include the host, sign and identify key files.
|
|
|
|
By default, the password is the string returned by the Unix
|
|
|
|
.Ic hostname
|
|
|
|
command.
|
|
|
|
.It Fl P Fl \-pvt\-cert
|
|
|
|
Generate a new private certificate used by the
|
|
|
|
.Cm PC
|
|
|
|
identity scheme.
|
2014-12-20 22:52:39 +00:00
|
|
|
By default, the program generates public certificates.
|
2018-02-28 06:23:12 +00:00
|
|
|
Note: the PC identity scheme is not recommended for new installations.
|
|
|
|
.It Fl q Fl \-export\-passwd Ns = Ar passwd
|
|
|
|
Set the password for writing encrypted
|
|
|
|
.Cm IFF , GQ and MV
|
|
|
|
identity files redirected to
|
|
|
|
.Pa stdout
|
|
|
|
to
|
|
|
|
.Ar passwd .
|
|
|
|
In effect, these files are decrypted with the
|
|
|
|
.Fl p
|
|
|
|
password, then encrypted with the
|
|
|
|
.Fl q
|
|
|
|
password.
|
|
|
|
By default, the password is the string returned by the Unix
|
|
|
|
.Ic hostname
|
|
|
|
command.
|
|
|
|
.It Fl s Fl \-subject\-key Ns = Ar Oo host Oc Op @ Ar group
|
|
|
|
Specify the Autokey host name, where
|
|
|
|
.Ar host
|
|
|
|
is the optional host name and
|
|
|
|
.Ar group
|
|
|
|
is the optional group name.
|
|
|
|
The host name, and if provided, group name are used in
|
|
|
|
.Ar host @ group
|
|
|
|
form as certificate subject and issuer.
|
|
|
|
Specifying
|
|
|
|
.Fl s @ Ar group
|
|
|
|
is allowed, and results in leaving the host name unchanged, as with
|
|
|
|
.Fl i Ar group .
|
|
|
|
The group name, or if no group is provided, the host name are also used in the
|
|
|
|
file names of
|
|
|
|
.Cm IFF , GQ ,
|
|
|
|
and
|
|
|
|
.Cm MV
|
|
|
|
identity scheme client parameter files.
|
|
|
|
If
|
|
|
|
.Ar host
|
|
|
|
is not specified, the default host name is the string returned by the Unix
|
|
|
|
.Ic hostname
|
|
|
|
command.
|
|
|
|
.It Fl S Fl \-sign\-key Ns = Op Cm RSA | DSA
|
|
|
|
Generate a new encrypted public/private sign key file of the specified type.
|
|
|
|
By default, the sign key is the host key and has the same type.
|
|
|
|
If compatibility with FIPS 140\-2 is required, the sign key type must be
|
|
|
|
.Cm DSA .
|
|
|
|
.It Fl T Fl \-trusted\-cert
|
2014-12-20 22:52:39 +00:00
|
|
|
Generate a trusted certificate.
|
|
|
|
By default, the program generates a non\-trusted certificate.
|
2018-02-28 06:23:12 +00:00
|
|
|
.It Fl V Fl \-mv\-params Ar nkeys
|
|
|
|
Generate
|
|
|
|
.Ar nkeys
|
|
|
|
encrypted server keys and parameters for the Mu\-Varadharajan (MV)
|
|
|
|
identity scheme.
|
|
|
|
This option is mutually exclusive with the
|
|
|
|
.Fl I
|
|
|
|
and
|
|
|
|
.Fl G
|
|
|
|
options.
|
|
|
|
Note: support for this option should be considered a work in progress.
|
2014-12-20 22:52:39 +00:00
|
|
|
.El
|
|
|
|
.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
|
|
|
|
.Nm
|
|
|
|
program.
|
|
|
|
If a site supports OpenSSL or its companion OpenSSH,
|
|
|
|
it is very likely that means to do this are already available.
|
|
|
|
.Pp
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
The entropy seed used by the OpenSSL library is contained in a file,
|
|
|
|
usually called
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa .rnd ,
|
2014-12-20 22:52:39 +00:00
|
|
|
which must be available when starting the NTP daemon
|
|
|
|
or the
|
|
|
|
.Nm
|
|
|
|
program.
|
|
|
|
The NTP daemon will first look for the file
|
|
|
|
using the path specified by the
|
2018-02-28 06:23:12 +00:00
|
|
|
.Cm randfile
|
2014-12-20 22:52:39 +00:00
|
|
|
subcommand of the
|
|
|
|
.Ic crypto
|
|
|
|
configuration command.
|
|
|
|
If not specified in this way, or when starting the
|
|
|
|
.Nm
|
|
|
|
program,
|
|
|
|
the OpenSSL library will look for the file using the path specified
|
|
|
|
by the
|
|
|
|
.Ev RANDFILE
|
|
|
|
environment variable in the user home directory,
|
|
|
|
whether root or some other user.
|
|
|
|
If the
|
|
|
|
.Ev RANDFILE
|
|
|
|
environment variable is not present,
|
|
|
|
the library will look for the
|
2018-02-28 06:23:12 +00:00
|
|
|
.Pa .rnd
|
2014-12-20 22:52:39 +00:00
|
|
|
file in the user home directory.
|
2018-02-28 06:23:12 +00:00
|
|
|
Since both the
|
|
|
|
.Nm
|
|
|
|
program and
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
daemon must run as root, the logical place to put this file is in
|
|
|
|
.Pa /.rnd
|
|
|
|
or
|
|
|
|
.Pa /root/.rnd .
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
All file formats begin with two nonencrypted lines.
|
|
|
|
The first line contains the file name, including the generated host name
|
|
|
|
and filestamp, in the format
|
|
|
|
.Pa ntpkey_ Ns Ar key _ Ar name . Ar filestamp ,
|
|
|
|
where
|
|
|
|
.Ar key
|
|
|
|
is the key or parameter type,
|
|
|
|
.Ar name
|
|
|
|
is the host or group name and
|
|
|
|
.Ar filestamp
|
|
|
|
is the filestamp (NTP seconds) when the file was created.
|
|
|
|
By convention,
|
|
|
|
.Ar key
|
|
|
|
names in generated file names include both upper and lower case
|
|
|
|
characters, while
|
|
|
|
.Ar key
|
|
|
|
names in generated link names include only lower case characters.
|
|
|
|
The filestamp is not used in generated link names.
|
|
|
|
The second line contains the datestamp in conventional Unix
|
|
|
|
.Pa date
|
|
|
|
format.
|
|
|
|
Lines beginning with
|
|
|
|
.Ql #
|
|
|
|
are considered comments and ignored by the
|
2014-12-20 22:52:39 +00:00
|
|
|
.Nm
|
|
|
|
program and
|
|
|
|
.Xr ntpd @NTPD_MS@
|
|
|
|
daemon.
|
|
|
|
.Pp
|
2018-02-28 06:23:12 +00:00
|
|
|
The remainder of the file contains cryptographic data, encoded first using ASN.1
|
|
|
|
rules, then encrypted if necessary, and finally written in PEM\-encoded
|
|
|
|
printable ASCII text, preceded and followed by MIME content identifier lines.
|
|
|
|
.Pp
|
|
|
|
The format of the symmetric keys file, ordinarily named
|
|
|
|
.Pa ntp.keys ,
|
|
|
|
is somewhat different than the other files in the interest of backward compatibility.
|
|
|
|
Ordinarily, the file is generated by this program, but it can be constructed
|
|
|
|
and edited using an ordinary text editor.
|
|
|
|
.Bd -literal -unfilled -offset center
|
|
|
|
# ntpkey_MD5key_bk.ntp.org.3595864945
|
|
|
|
# Thu Dec 12 19:22:25 2013
|
|
|
|
1 MD5 L";Nw<\`.I<f4U0)247"i # MD5 key
|
|
|
|
2 MD5 &>l0%XXK9O'51VwV<xq~ # MD5 key
|
|
|
|
3 MD5 lb4zLW~d^!K:]RsD'qb6 # MD5 key
|
|
|
|
4 MD5 Yue:tL[+vR)M\`n~bY,'? # MD5 key
|
|
|
|
5 MD5 B;fx'Kgr/&4ZTbL6=RxA # MD5 key
|
|
|
|
6 MD5 4eYwa\`o}3i@@V@..R9!l # MD5 key
|
|
|
|
7 MD5 \`A.([h+;wTQ|xfi%Sn_! # MD5 key
|
|
|
|
8 MD5 45:V,r4]l6y^JH6"Sh?F # MD5 key
|
|
|
|
9 MD5 3\-5vcn*6l29DS?Xdsg)* # MD5 key
|
|
|
|
10 MD5 2late4Me # MD5 key
|
|
|
|
11 SHA1 a27872d3030a9025b8446c751b4551a7629af65c # SHA1 key
|
|
|
|
12 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74 # SHA1 key
|
|
|
|
13 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9 # SHA1 key
|
|
|
|
14 SHA a5332809c8878dd3a5b918819108a111509aeceb # SHA key
|
|
|
|
15 MD2 2fe16c88c760ff2f16d4267e36c1aa6c926e6964 # MD2 key
|
|
|
|
16 MD4 b2691811dc19cfc0e2f9bcacd74213f29812183d # MD4 key
|
|
|
|
17 MD5 e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c # MD5 key
|
|
|
|
18 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc # MDC2 key
|
|
|
|
19 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2 # RIPEMD160 key
|
|
|
|
20 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878 # AES128CMAC key
|
|
|
|
.Ed
|
|
|
|
.D1 Figure 1. Typical Symmetric Key File
|
|
|
|
.Pp
|
|
|
|
Figure 1 shows a typical symmetric keys file used by the reference
|
|
|
|
implementation.
|
|
|
|
Following the header the keys are entered one per line in the format
|
|
|
|
.D1 Ar keyno Ar type Ar key
|
2014-12-20 22:52:39 +00:00
|
|
|
where
|
|
|
|
.Ar keyno
|
2018-08-20 06:07:33 +00:00
|
|
|
is a positive integer in the range 1\-65535;
|
2014-12-20 22:52:39 +00:00
|
|
|
.Ar type
|
2018-02-28 06:23:12 +00:00
|
|
|
is the key type for the message digest algorithm, which in the absence of the
|
|
|
|
OpenSSL library must be
|
|
|
|
.Cm 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 either
|
|
|
|
.Cm SHA
|
|
|
|
or
|
|
|
|
.Cm SHA1 ;
|
2014-12-20 22:52:39 +00:00
|
|
|
.Ar key
|
|
|
|
is the key itself,
|
2018-02-28 06:23:12 +00:00
|
|
|
which is a printable ASCII string 20 characters or less in length:
|
|
|
|
each character is chosen from the 93 printable characters
|
|
|
|
in the range 0x21 through 0x7e (
|
|
|
|
.Ql !
|
|
|
|
through
|
|
|
|
.Ql ~
|
|
|
|
\&) excluding space and the
|
|
|
|
.Ql #
|
|
|
|
character, and terminated by whitespace or a
|
2014-12-20 22:52:39 +00:00
|
|
|
.Ql #
|
|
|
|
character.
|
2018-02-28 06:23:12 +00:00
|
|
|
An OpenSSL key consists of a hex\-encoded ASCII string of 40 characters, which
|
|
|
|
is truncated as necessary.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
Note that the keys used by the
|
|
|
|
.Xr ntpq @NTPQ_MS@
|
|
|
|
and
|
|
|
|
.Xr ntpdc @NTPDC_MS@
|
|
|
|
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.
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Nm
|
2018-02-28 06:23:12 +00:00
|
|
|
program generates a symmetric keys file
|
|
|
|
.Pa ntpkey_MD5key_ Ns Ar hostname Ns . Ns Ar filestamp .
|
2014-12-20 22:52:39 +00:00
|
|
|
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
|
|
|
|
.Pa ntp.keys ,
|
|
|
|
so
|
|
|
|
.Nm
|
|
|
|
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
|
|
|
|
.Xr ntpq @NTPQ_MS@
|
|
|
|
and
|
|
|
|
.Xr ntpdc @NTPDC_MS@
|
|
|
|
utilities.
|
|
|
|
.Sh "OPTIONS"
|
|
|
|
.Bl -tag
|
|
|
|
.It Fl b Ar imbits , Fl \-imbits Ns = Ns Ar imbits
|
|
|
|
identity modulus bits.
|
|
|
|
This option takes an integer number as its argument.
|
|
|
|
The value of
|
|
|
|
.Ar imbits
|
|
|
|
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.
|
|
|
|
.It Fl c Ar scheme , Fl \-certificate Ns = Ns Ar scheme
|
|
|
|
certificate scheme.
|
|
|
|
.sp
|
|
|
|
scheme is one of
|
2018-02-28 06:23:12 +00:00
|
|
|
RSA\-MD2, RSA\-MD5, RSA\-MDC2, RSA\-SHA, RSA\-SHA1, RSA\-RIPEMD160,
|
2014-12-20 22:52:39 +00:00
|
|
|
DSA\-SHA, or DSA\-SHA1.
|
|
|
|
.sp
|
2018-02-28 06:23:12 +00:00
|
|
|
Select the certificate signature encryption/message digest scheme.
|
2014-12-20 22:52:39 +00:00
|
|
|
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.
|
|
|
|
.It Fl C Ar cipher , Fl \-cipher Ns = Ns Ar cipher
|
|
|
|
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,
|
2018-02-28 06:23:12 +00:00
|
|
|
equivalent to "\fB\-C des\-ede3\-cbc\fP". The openssl tool lists ciphers
|
2014-12-20 22:52:39 +00:00
|
|
|
available in "\fBopenssl \-h\fP" output.
|
|
|
|
.It Fl d , Fl \-debug\-level
|
|
|
|
Increase debug verbosity level.
|
|
|
|
This option may appear an unlimited number of times.
|
|
|
|
.sp
|
|
|
|
.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
|
|
|
|
Set the debug verbosity level.
|
|
|
|
This option may appear an unlimited number of times.
|
|
|
|
This option takes an integer number as its argument.
|
|
|
|
.sp
|
|
|
|
.It Fl e , Fl \-id\-key
|
|
|
|
Write IFF or GQ identity keys.
|
|
|
|
.sp
|
2018-02-28 06:23:12 +00:00
|
|
|
Write the public parameters from the IFF or GQ client keys to
|
|
|
|
the standard output.
|
|
|
|
This is intended for automatic key distribution by email.
|
2014-12-20 22:52:39 +00:00
|
|
|
.It Fl G , Fl \-gq\-params
|
|
|
|
Generate GQ parameters and keys.
|
|
|
|
.sp
|
|
|
|
Generate parameters and keys for the GQ identification scheme,
|
|
|
|
obsoleting any that may exist.
|
|
|
|
.It Fl H , Fl \-host\-key
|
|
|
|
generate RSA host key.
|
|
|
|
.sp
|
|
|
|
Generate new host keys, obsoleting any that may exist.
|
|
|
|
.It Fl I , Fl \-iffkey
|
|
|
|
generate IFF parameters.
|
|
|
|
.sp
|
|
|
|
Generate parameters for the IFF identification scheme, obsoleting
|
|
|
|
any that may exist.
|
|
|
|
.It Fl i Ar group , Fl \-ident Ns = Ns Ar group
|
|
|
|
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,
|
2018-02-28 06:23:12 +00:00
|
|
|
is also a part of the self\-signed host certificate subject and
|
2014-12-20 22:52:39 +00:00
|
|
|
issuer names in the form \fBhost@group\fP and should match the
|
2018-02-28 06:23:12 +00:00
|
|
|
\'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in the
|
|
|
|
\fBntpd\fP configuration file.
|
2014-12-20 22:52:39 +00:00
|
|
|
.It Fl l Ar lifetime , Fl \-lifetime Ns = Ns Ar lifetime
|
|
|
|
set certificate lifetime.
|
|
|
|
This option takes an integer number as its argument.
|
|
|
|
.sp
|
|
|
|
Set the certificate expiration to lifetime days from now.
|
|
|
|
.It Fl m Ar modulus , Fl \-modulus Ns = Ns Ar modulus
|
2018-02-28 06:23:12 +00:00
|
|
|
prime modulus.
|
2014-12-20 22:52:39 +00:00
|
|
|
This option takes an integer number as its argument.
|
|
|
|
The value of
|
|
|
|
.Ar modulus
|
|
|
|
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.
|
2018-02-28 06:23:12 +00:00
|
|
|
.It Fl M , Fl \-md5key
|
|
|
|
generate symmetric keys.
|
|
|
|
.sp
|
|
|
|
Generate symmetric keys, obsoleting any that may exist.
|
2014-12-20 22:52:39 +00:00
|
|
|
.It Fl P , Fl \-pvt\-cert
|
|
|
|
generate PC private certificate.
|
|
|
|
.sp
|
|
|
|
Generate a private certificate. By default, the program generates
|
|
|
|
public certificates.
|
|
|
|
.It Fl p Ar passwd , Fl \-password Ns = Ns Ar passwd
|
|
|
|
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.
|
|
|
|
.It Fl q Ar passwd , Fl \-export\-passwd Ns = Ns Ar passwd
|
|
|
|
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.
|
|
|
|
.It Fl s Ar host@group , Fl \-subject\-name Ns = Ns Ar host@group
|
|
|
|
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
|
2018-02-28 06:23:12 +00:00
|
|
|
in \fBhost@group\fP form for the host certificate subject and issuer
|
2014-12-20 22:52:39 +00:00
|
|
|
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.
|
2018-02-28 06:23:12 +00:00
|
|
|
.It Fl S Ar sign , Fl \-sign\-key Ns = Ns Ar sign
|
|
|
|
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.
|
2014-12-20 22:52:39 +00:00
|
|
|
.It Fl T , Fl \-trusted\-cert
|
|
|
|
trusted certificate (TC scheme).
|
|
|
|
.sp
|
|
|
|
Generate a trusted certificate. By default, the program generates
|
|
|
|
a non\-trusted certificate.
|
|
|
|
.It Fl V Ar num , Fl \-mv\-params Ns = Ns Ar num
|
|
|
|
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.
|
|
|
|
.It Fl v Ar num , Fl \-mv\-keys Ns = Ns Ar num
|
|
|
|
update <num> MV keys.
|
|
|
|
This option takes an integer number as its argument.
|
|
|
|
.sp
|
|
|
|
This option has not been fully documented.
|
|
|
|
.It Fl \&? , Fl \-help
|
|
|
|
Display usage information and exit.
|
|
|
|
.It Fl \&! , Fl \-more\-help
|
|
|
|
Pass the extended usage information through a pager.
|
|
|
|
.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
|
|
|
|
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.
|
|
|
|
.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
|
|
|
|
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.
|
|
|
|
.It Fl \-version Op Brq Ar v|c|n
|
|
|
|
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.
|
|
|
|
.El
|
|
|
|
.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
|
|
|
|
.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:
|
|
|
|
.Bl -tag
|
|
|
|
.It 0 " (EXIT_SUCCESS)"
|
|
|
|
Successful program execution.
|
|
|
|
.It 1 " (EXIT_FAILURE)"
|
|
|
|
The operation failed or the command syntax was not valid.
|
|
|
|
.It 66 " (EX_NOINPUT)"
|
|
|
|
A specified configuration file could not be loaded.
|
|
|
|
.It 70 " (EX_SOFTWARE)"
|
|
|
|
libopts had an internal operational error. Please report
|
|
|
|
it to autogen\-users@lists.sourceforge.net. Thank you.
|
|
|
|
.El
|
|
|
|
.Sh "AUTHORS"
|
2015-02-05 20:53:33 +00:00
|
|
|
The University of Delaware and Network Time Foundation
|
2014-12-20 22:52:39 +00:00
|
|
|
.Sh "COPYRIGHT"
|
2020-03-04 13:59:29 +00:00
|
|
|
Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved.
|
2014-12-20 22:52:39 +00:00
|
|
|
This program is released under the terms of the NTP license, <http://ntp.org/license>.
|
|
|
|
.Sh BUGS
|
2018-02-28 06:23:12 +00:00
|
|
|
It can take quite a while to generate some cryptographic values.
|
2014-12-20 22:52:39 +00:00
|
|
|
.Pp
|
|
|
|
Please report bugs to http://bugs.ntp.org .
|
|
|
|
.Pp
|
|
|
|
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
|
|
|
|
.Sh NOTES
|
|
|
|
Portions of this document came from FreeBSD.
|
|
|
|
.Pp
|
|
|
|
This manual page was \fIAutoGen\fP\-erated from the \fBntp\-keygen\fP
|
|
|
|
option definitions.
|