ntp-keygen - Generate Public and Private Keys for NTP
/usr/sbin/ntp-keygen [-deGgHIMPTv?!] [-i issuername] [-q passwd1] [-p passwd2] [-s subjectname] [-V nkeys] [-v mvkeys] [-c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA=SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]] [-S [ RSA | DSA]]
System Administration Commands ntp-keygen(8)
NAME
ntp-keygen - Generate Public and Private Keys for NTP
SYNOPSIS
/usr/sbin/ntp-keygen [-deGgHIMPTv?!] [-i issuername] [-q passwd1] [-p
passwd2] [-s subjectname] [-V nkeys] [-v mvkeys] [-c [RSA-MD2 | RSA-MD5
| RSA-SHA | RSA=SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]]
[-S [ RSA | DSA]]
OPTIONS
-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 |
RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ], --certificate
[...]
Select certificate and 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.
-d, --debug-level
Enable debugging. This option displays the cryptographic data
produced for eye-friendly billboards.
-D debug-level, --debug-level=debug-level
Enable debugging and set the debug level to debug-level.
-e, --id-key
Generate unencrypted IFF or GQ parameters file from existing key
file IFFkey or GQkey file, respectively. The file contents are
sent to the standard output.
-G, --gq-params
Generate GQ key file GQkey and link gqkey for the Guillou-
Quisquater (GQ) identity scheme.
-g, --gq-keys
Update the GQ keys.
-H, --host-key
Generate a new public/private host keys RSAkey, and link host.
-I, --iffkey
Generate a new encrypted IFF key file IFFkey and link iffkey for
the Schnorr (IFF) identity scheme.
-i issuername, --issuer-name=issuername
Set the issuername name to issuername for generated identity
files. This is useful only if the TA is not a group member and
is generally considered not a good practice.
-M, --md5key
Generate a new MD5 key file.
-m modulus, --modulus=modulus
Set the modulus to modulus.
-P, --pvt-cert
Generate a new private certificate used by the PC identity
scheme. By default, the program generates public certificates.
Note: the PC identity scheme is not recommended for new instal-
lations.
-p passwd2, --pvt-passwd=passwd2
Set the password for writing encrypted files to passwd2. By
default, the write password is the read password.
-q passwd1, --get-pvt-passwd=passwd1
Set the password for reading encrypted files to passwd1. By
default, the read password is the host name.
-S [ RSA | DSA ], --sign-key=[ RSA | DSA]
Generate a new sign key of the designated type. By default, the
sign key is the host key.
-s name, --subject-name=name
Set the host name to name. This is used in the host and sign key
file names, as well as the subject and issuer names in the cer-
tificate. It must match the host name specified in the CRYPTO
configuration command.
-T, --trusted-cert
Generate a trusted certificate. By default, the program gener-
ates nontrusted certificates.
-V nkeys, --mv-params=nkeys
Generate server parameters MV and nkeys client keys for the Mu-
Varadharajan (MV) identity scheme. Note: support for this
option should be considered a work in progress.
-v, --version
Output version of program and exit.
--mv-keys=mvkeys
-?, --help
Print program help information.
-!, --more-help
Extended usages information passed through a pager.
-> rcfile, --save-opts=rcfile
Save the option state to rcfile.
-< rcfile, --load-opts=rcfile, --no-load-opts
Load options from rcfile. The no-load-opts form will disable
the loading of earlier RC/INI files. --no-load-opts is handled
early, out of order.
OPTION PRESETS
Most options may be preset by loading values from configuration file(s)
and values from environment variables named:
NTP_KEYGEN_<option-name> or NTP_KEYGEN
The environmental presets take precedence (are processed later than)
the configuration files. The option-name should be in all capital let-
ters. For example, to set the --command option, you would set the
NTP_KEYGEN_COMMAND environment variable. The users home directory and
the current directory are searched for a file named .ntprc.
DESCRIPTION
This program generates cryptographic data files used by the NTPv4
authentication and identity schemes. It generates MD5 keys used in sym-
metric key cryptography and generates encryption keys, certificates and
identity keys used in the Autokey public key cryptography. 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.
Generated files are compatible with other OpenSSL applications and
other Public Key Infrastructure (PKI) resources. Certificates or cer-
tificate requests generated by this or other programs should be compat-
ible with extant industry practice, although some users might find the
interpretation of X509v3 extension fields somewhat liberal. However,
the identity keys files are probably not compatible with anything other
than Autokey.
Most files written by this program are encrypted using a private pass-
word. The -p passwd2 option specifies the write password and the -q
passwd2 option the read password for previously encrypted files. If no
read password is specified, the host name returned by the Unix gethost-
name() function is used. If no write password is specified, the read
password is used as the write password.
The ntpd configuration command crypto pw passwd specifies the read
password for previously encrypted files. This must match the write
password used by this program. For convenience, if the ntpd password is
not specified, the host name returned by the Unix gethostname() func-
tion is used. Thus, if files are generated by this program without
password, they can be read back by ntpd without password, but only on
the same host.
All files and links are installed by default in the keys directory
/etc/inet, which is normally in a shared filesystem in NFS-mounted net-
works. The location of the keys directory can be changed by the keysdir
configuration command. 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.
This program directs commentary and error messages to the standard
error stream stderr and some files to the standard output stream stdout
where they can be piped to other applications or redirected to a file.
The names used for generated files and links all begin with the string
ntpkey and include the file type, generating host and filestamp, as
described in the "Cryptographic Data Files" section below
Running the Program
The safest way to run this program is log in as root and change to the
keys directory, /etc/inet. When run for the first time, or if all files
with names beginning ntpkey have been removed, use the ntp-keygen com-
mand without arguments to generate a default RSA host key file and
matching RSA-MD5 certificate file. The file names and password default
to the host name as described above. If run again with the same command
line, the program uses the same host key file, but generates a new cer-
tificate file.
Run the command on as many hosts as necessary. Designate one of them as
the trusted host (TH) using the -T option on the command line and con-
figure it to synchronize via reliable paths. THs have trusted, self-
signed certificates; all other hosts have nontrusted, self-signed cer-
tificates. Then configure the nontrusted hosts to synchronize to the TH
directly or indirectly. A certificate trail is created by asking the
immediately ascendant host towards the root 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.
By default the name used in the subject and issuer fields in the cer-
tificate is the host name. A different name can be assigned using the
-s host option on the command line, but the name must match the host
name specified by the crypto configuration command.
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 file name can be assigned using the -S
option 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.
Trusted Hosts and Secure Groups
As described on the "Authentication Options" page at
file:///usr/share/doc/ntp/authopt.html, an NTP secure group consists of
one or more low-stratum THs as the root from which all other group
hosts derive synchronization directly or indirectly. For authentication
purposes all THs in a group must have the same host and group name; all
other hosts have the same group name, but different host names. The
host name and group name must match the names specified by the crypto
configuratrion command. Host and group names are used only for authen-
tication purposes and have nothing to do with DNS names.
It is convenient to nominate a single TH acting as a trusted authority
(TA) to generate a set of files and links that are then copied intact
to all other THs in the group, most conveniently as a tar archive. This
means that it doesn't matter which certificate trail ends at which TH,
since the cryptographic media are the same.
To generate and install cryptographic media files, The TA uses the
ntp-keygen -q passwd1 -s host -T
command to specify the password, host/group name and trusted certifi-
cate. For THs the host and group names are the same and must match the
host and group names specified on the crypto configuration command. If
run again with the same command line, the program uses the same host
key file, but generates a new trusted certificate file. Group hosts
other than the THs use the same command line, but with a different host
name and without the -T option. On these hosts if the -s host option is
missing, the host name is the default described above.
Identity Schemes
As described on the "Authentication Options" page, there are five iden-
tity schemes, three of which - IFF, GQ and MV - require files specific
to each scheme and group. There are two files for each scheme, an
encrypted keys file and a nonencrypted parameters file. THs need only
the keys file; all the others need the parameters file. Other hosts
expecting to support a client population also need the keys file; hosts
acting only as clients need only the parameters file. Both files are
generated by the TA on behalf of all servers and clients in the group.
The parameters files are public; they can be stored in a public place
and sent in the clear. The keys files are encrypted with the host read
password. To retrieve the keys file, a host sends a mail request to the
TA including its private read password. The TA encrypts the keys file
with this password and returns it as an attachment. The attachment is
then copied intact to the keys directory with name given in the first
line of the file, but all in lower case and with the filestamp
deleted..
The TA can generate GQ keys, certificate and identity files for all
TH's using the command
ntp-keygen -q passwd1 -s host -T -G -e >parameters_file
where the redirected parameters_file can be piped to a mail application
or stored locally and renamed as above for later distribution. The pro-
cedure for IFF files is similar with -G replaced by -I.
The TA can generate an encrypted GQ keys file copy using the command
ntp-keygen -q passwd1 -p passwd2 -s host >keys_file
where passwd1 is the read password for the TA, passwd2 is the read
password for the requesting host and keys_file is sent or stored as
above. The program uses the keys and parameters of whatever scheme gen-
erated the keys file.
Cryptographic Data Files
File and link names are in the form ntpkey_key_name.fstamp, where key
is the key or parameter type, name is the host or group name and fstamp
is the filestamp (NTP seconds) when the file was created). By conven-
tion, key fields in generated file names include both upper and lower
case alphanumeric characters, while key fields in generated link names
include only lower case characters. The filestamp is not used in gener-
ated link names.
The key type is a string defining the cryptographic function. Key types
include public/private keys host and sign, certificate cert and several
challenge/response key types. By convention, files used for challenges
have a par subtype, as in the IFF challenge IFFpar, while files for
responses have a key subtype, as in the GQ response GQkey.
All files begin with two nonencrypted lines. The first line contains
the file name in the format ntpkey_key_host.fstamp. The second line
contains the datestamp in conventional Unix date format. Lines begin-
ning with # are ignored.
The remainder of the file contains cryptographic data encoded first
using ASN.1 rules, then encrypted using the DES-CBC algorithm and given
password and finally written in PEM-encoded printable ASCII text pre-
ceded and followed by MIME content identifier lines.
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 alphanu-
meric strings. Following the header the keys are entered one per line
in the format
keyno type key
where keyno is a positive integer in the range 1-65,535, type is the
string MD5 defining the key format and key is the key itself, which is
a printable ASCII string 16 characters or less in length. Each charac-
ter is chosen from the 93 printable characters in the range 0x21
through 0x7f excluding space and the '#' character.
Note that the keys used by the ntpq program are checked against pass-
words requested by the program and entered by hand, so it is generally
appropriate to specify these keys in human readable ASCII format.
The ntp-keygen program generates a MD5 symmetric keys file ntp-
key_MD5key_hostname.filestamp. Since the file contains private shared
keys, it should be visible only to root and distributed by secure means
to other subnet hosts. The NTP daemon loads the file ntp.keys, so ntp-
keygen installs a soft link from this name to the generated file. Sub-
sequently, 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 ntpq utility.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+---------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+---------------------+
|Availability | service/network/ntp |
+---------------+---------------------+
|Stability | Uncommitted |
+---------------+---------------------+
NOTES
The documentation available at /usr/share/doc/ntp is provided as is
from the NTP distribution and may contain information that is not
applicable to the software as provided in this partIcular distribution.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://ar-
chive.ntp.org/ntp4/ntp-4.2/ntp-4.2.8p15.tar.gz.
Further information about this software can be found on the open source
community website at http://www.ntp.org/.
SEE ALSO
ntpd(8), ntprc(5), attributes(7)
ntp-keygen(8)