mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-13 10:02:38 +00:00
355 lines
21 KiB
HTML
355 lines
21 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<title>ntp-keygen - generate public and private keys</title>
|
|
<link href="scripts/style.css" type="text/css" rel="stylesheet">
|
|
</head>
|
|
<body>
|
|
<h3><tt>ntp-keygen</tt> - generate public and private keys</h3>
|
|
<p><img src="pic/alice23.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a></p>
|
|
<p>Alice holds the key.</p>
|
|
<p>Last update:
|
|
<!-- #BeginDate format:En2m -->24-Jul-2018 07:27<!-- #EndDate -->
|
|
UTC</p>
|
|
<br clear="left">
|
|
<h4>Related Links</h4>
|
|
<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
|
|
<h4>Table of Contents</h4>
|
|
<ul>
|
|
<li class="inline"><a href="#synop">Synopsis</a></li>
|
|
<li class="inline"><a href="#descrip">Description</a></li>
|
|
<li class="inline"><a href="#run">Running the program</a></li>
|
|
<li class="inline"><a href="#cmd">Command Line Options</a></li>
|
|
<li class="inline"><a href="#rand">Random Seed File</a></li>
|
|
<li class="inline"><a href="#fmt">Cryptographic Data Files</a></li>
|
|
<li class="inline"><a href="#bug">Bugs</a></li>
|
|
</ul>
|
|
<hr>
|
|
<h4 id="synop">Synopsis</h4>
|
|
<p id="intro"><tt>ntp-keygen [ -deGHIMPT ] [ -b <i>modulus</i> ] [ -c [ RSA-MD2 | RSA-MD5 | RSA-SHA
|
|
| RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ]
|
|
[ -C <i>cipher</i> ] [-i <i>group</i> ] [ -l <em>days</em>]
|
|
[ -m <i>modulus</i> ] [ -p <i>passwd1</i> ] [ -q <i>passwd2</i> ]
|
|
[ -S [ RSA | DSA ] ] [ -s <i>host</i> ] [ -V <i>nkeys</i> ]</tt></p>
|
|
<h4 id="descrip">Description</h4>
|
|
<p>This program generates cryptographic data files used by the NTPv4
|
|
authentication and identity schemes. 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, sign keys, certificates,
|
|
and identity keys and parameters used by the Autokey public key
|
|
cryptography. The message digest 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 mail to other
|
|
sites.</p>
|
|
<p>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, AES-128 CMAC, 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 <tt><a href="ntpq.html">ntpq</a></tt>
|
|
and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs.</p>
|
|
<p>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.</p>
|
|
<p>Some files used by this program are encrypted using a private
|
|
password. The <tt>-p</tt> option specifies the password for local
|
|
encrypted files and the <tt>-q</tt> option the password for encrypted
|
|
files sent to remote sites. If no password is specified, the host name
|
|
returned by the Unix <tt>gethostname()</tt> function, normally the DNS
|
|
name of the host, is used.</p>
|
|
<p>The <tt>pw</tt> option of the <tt>crypto</tt> 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 <tt>ntpd</tt>
|
|
without password, but only on the same host.</p>
|
|
<p>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 <tt>ntp.keys</tt>, is usually installed in <tt>/etc</tt>.
|
|
Other files and links are usually installed
|
|
in <tt>/usr/local/etc</tt>, 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 <tt>keysdir</tt>
|
|
configuration command in such cases. Normally, this is
|
|
in <tt>/etc</tt>.</p>
|
|
<p>This program directs commentary and error messages to the standard
|
|
error stream <tt>stderr</tt> and remote files to the standard output
|
|
stream <tt>stdout</tt> 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 <tt>ntpkey</tt> and include the file type,
|
|
generating host and filestamp, as described in
|
|
the <a href="#fmt">Cryptographic Data Files</a> section below</p>
|
|
<h4 id="run">Running the Program</h4>
|
|
<p>To test and gain experience with Autokey concepts, log in as root and
|
|
change to the keys directory, usually <tt>/usr/local/etc</tt>. When
|
|
run for the first time, or if all files with names
|
|
beginning <tt>ntpkey</tt> have been removed, use
|
|
the <tt>ntp-keygen</tt> 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.</p>
|
|
<p>Run the command on as many hosts as necessary. Designate one of them
|
|
as the trusted host (TH) using <tt>ntp-keygen</tt> with
|
|
the <tt>-T</tt> 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.</p>
|
|
<p>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 <tt>-S</tt> 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 <tt>-c</tt> option.</p>
|
|
<p>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.</p>
|
|
<p>Additional information on trusted groups and identity schemes is on
|
|
the <a href="autokey.html">Autokey Public-Key Authentication</a>
|
|
page.</p>
|
|
<h4 id="cmd">Command Line Options</h4>
|
|
<dl>
|
|
<dt><tt>-b <i>modulus</i></tt></dt>
|
|
<dd>Set the modulus for generating identity keys to <i>modulus</i>
|
|
bits. The modulus defaults to 256, but can be set from 256 (32
|
|
octets) to 2048 (256 octets). Use the larger moduli with caution,
|
|
as this can consume considerable computing resources and increases
|
|
the size of authenticated packets.</dd>
|
|
<dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt></dt>
|
|
<dd>Select certificate digital signature and message digest scheme.
|
|
Note that RSA schemes must be used with an RSA sign key and DSA
|
|
schemes must be used with a DSA sign key. The default without this
|
|
option is <tt>RSA-MD5</tt>. If compatibility with FIPS 140-2 is
|
|
required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme
|
|
must be used.</dd>
|
|
<dt><tt>-C <i>cipher</i></tt></dt>
|
|
<dd>Select the OpenSSL cipher to use for password-protected keys.
|
|
The <tt>openssl -h</tt> command provided with OpenSSL displays
|
|
available ciphers. The default without this option
|
|
is <tt>des-ede3-cbc</tt>.</dd>
|
|
<dt><tt>-d</tt></dt>
|
|
<dd>Enable debugging. This option displays the cryptographic data
|
|
produced for eye-friendly billboards.</dd>
|
|
<dt><tt>-e</tt></dt>
|
|
<dd>Extract the IFF or GQ public parameters from the <tt>IFFkey</tt>
|
|
or <tt>GQkey</tt> keys file previously specified. Send the
|
|
unencrypted data to the standard output stream <tt>stdout</tt>.</dd>
|
|
<dt><tt>-G</tt></dt>
|
|
<dd>Generate a new encrypted GQ key file for the Guillou-Quisquater
|
|
(GQ) identity scheme. This option is mutually exclusive with
|
|
the <tt>-I</tt> and <tt>-V</tt> options.</dd>
|
|
<dt><tt>-H</tt></dt>
|
|
<dd>Generate a new encrypted RSA public/private host key file.</dd>
|
|
<dt><tt>-i <i>group</i></tt></dt>
|
|
<dd>Set the optional Autokey group name to <tt><i>group</i></tt>. This
|
|
is used in the identity scheme parameter file names. In that role,
|
|
the default is the host name if no group is provided. The group
|
|
name, if specified using <tt>-i</tt> or using <tt>-s</tt> following
|
|
an <tt>@</tt> character, is also used in certificate subject and
|
|
issuer names in the form <tt><i>host</i>@<i>group</i></tt> and
|
|
should match the group specified via <tt>crypto ident</tt>
|
|
or <tt>server ident</tt> in ntpd's configuration file.</dd>
|
|
<dt><tt>-I</tt></dt>
|
|
<dd>Generate a new encrypted IFF key file for the Schnorr (IFF)
|
|
identity scheme. This option is mutually exclusive with
|
|
the <tt>-G</tt> and <tt>-V</tt> options.</dd>
|
|
<dt><tt>-l <i>days</i></tt></dt>
|
|
<dd>Set the lifetime for certificates to <tt><i>days</i></tt>. The
|
|
default lifetime is one year (365 d).</dd>
|
|
<dt><tt>-m <i>modulus</i></tt></dt>
|
|
<dd>Set the modulus for generating files to <i>modulus</i> bits. The
|
|
modulus defaults to 512, but can be set from 256 (32 octets) to 2048
|
|
(256 octets). Use the larger moduli with caution, as this can
|
|
consume considerable computing resources and increases the size of
|
|
authenticated packets.</dd>
|
|
<dt><tt>-M</tt></dt>
|
|
<dd>Generate a new keys file containing 10 MD5 keys and 10 SHA keys.
|
|
An MD5 key is a string of 20 random printable ASCII characters,
|
|
while a 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.</dd>
|
|
<dt><tt>-P</tt></dt>
|
|
<dd>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 installations.</dd>
|
|
<dt><tt>-p <i>passwd</i></tt></dt>
|
|
<dd>Set the password for reading and writing encrypted files
|
|
to <tt><i>passwd</i></tt>. These include the host, sign and
|
|
identify key files. By default, the password is the string returned
|
|
by the Unix <tt>gethostname()</tt> routine.</dd>
|
|
<dt><tt>-q <i>passwd</i></tt></dt>
|
|
<dd>Set the password for writing encrypted IFF, GQ and MV identity
|
|
files redirected to <tt>stdout</tt> to <tt><i>passwd</i></tt>=. In
|
|
effect, these files are decrypted with the <tt>-p</tt> password,
|
|
then encrypted with the <tt>-q</tt> password. By default, the
|
|
password is the string returned by the Unix <tt>gethostname()</tt>
|
|
routine.</dd>
|
|
<dt><tt>-S [ RSA | DSA ]</tt></dt>
|
|
<dd>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 compatibly with FIPS 140-2 is required, the sign
|
|
key type must be <tt>DSA</tt>.</dd>
|
|
<dt><tt>-s <i>host</i>[@<i>group</i>]</tt></dt>
|
|
<dd>Specify the Autokey host name, where <tt><i>host</i></tt> is the
|
|
host name and <tt><i>group</i></tt> is the optional group name. The
|
|
host name, and if provided, group name are used
|
|
in <tt><i>host</i>@<i>group</i></tt> form as certificate subject and
|
|
issuer. Specifying <tt>-s @<i>group</i></tt> is allowed, and
|
|
results in leaving the host name unchanged, as
|
|
with <tt>-i <i>group</i></tt>. The group name, or if no group is
|
|
provided, the host name are also used in the file names of IFF, GQ,
|
|
and MV identity scheme parameter files. If <tt><i>host</i></tt> is
|
|
not specified, the default host name is the string returned by
|
|
the <tt>gethostname()</tt> routine.</dd>
|
|
<dt><tt>-T</tt></dt>
|
|
<dd>Generate a trusted certificate. By default, the program generates
|
|
nontrusted certificates.</dd>
|
|
<dt><tt>-V <i>nkeys</i></tt></dt>
|
|
<dd>Generate <tt>nkeys</tt> encrypted server keys for the
|
|
Mu-Varadharajan (MV) identity scheme. This option is mutually
|
|
exclusive with the <tt>-I</tt> and <tt>-G</tt> options. Note:
|
|
support for this option should be considered a work in
|
|
progress.</dd>
|
|
</dl>
|
|
<h4 id="rand">Random Seed File</h4>
|
|
<p>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 OpenSSL library routines.
|
|
If a site supports <tt>ssh</tt>, it is very likely that means to do
|
|
this are already available. The entropy seed used by the OpenSSL
|
|
library is contained in a file, usually called <tt>.rnd</tt>, which
|
|
must be available when starting the <tt>ntp-keygen</tt> program
|
|
or <tt>ntpd</tt> daemon.</p>
|
|
<p>The OpenSSL library looks for the file using the path specified by
|
|
the <tt>RANDFILE</tt> environment variable in the user home directory,
|
|
whether root or some other user. If the <tt>RANDFILE</tt> environment
|
|
variable is not present, the library looks for the <tt>.rnd</tt> file
|
|
in the user home directory. Since both the <tt>ntp-keygen</tt>
|
|
program and <tt>ntpd</tt> daemon must run as root, the logical place
|
|
to put this file is in <tt>/.rnd</tt> or <tt>/root/.rnd</tt>. If the
|
|
file is not available or cannot be written, the program exits with a
|
|
message to the system log.</p>
|
|
<h4 id="fmt">Cryptographic Data Files</h4>
|
|
<p>File and link names are in the
|
|
form <tt>ntpkey_<i>key</i>_<i>name</i>.<i>fstamp</i></tt>,
|
|
where <tt><i>key</i></tt> is the key or parameter
|
|
type, <tt><i>name</i></tt> is the host or group name
|
|
and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the
|
|
file was created). By convention, <em><tt>key</tt></em> names in
|
|
generated file names include both upper and lower case characters,
|
|
while <em><tt>key</tt></em> names in generated link names include only
|
|
lower case characters. The filestamp is not used in generated link
|
|
names.</p>
|
|
<p>The <em><tt>key</tt></em> name is a string defining the cryptographic
|
|
key type. Key types include public/private keys <tt>host</tt>
|
|
and <tt>sign</tt>, certificate <tt>cert</tt> and several
|
|
challenge/response key types. By convention, client files used for
|
|
challenges have a <tt>par</tt> subtype, as in the IFF
|
|
challenge <tt>IFFpar</tt>, while server files for responses have
|
|
a <tt>key</tt> subtype, as in the GQ response <tt>GQkey</tt>.</p>
|
|
<p>All files begin with two nonencrypted lines. The first line contains
|
|
the file name in the
|
|
format <tt>ntpkey_<i>key</i>_<i>host</i>.<i>fstamp</i></tt>. The second
|
|
line contains the datestamp in conventional Unix <tt>date</tt> format.
|
|
Lines beginning with <tt>#</tt> are ignored.</p>
|
|
<p>The remainder of the file contains cryptographic data encoded first
|
|
using ASN.1 rules, then encrypted using the DES-CBC algorithm with
|
|
given password and finally written in PEM-encoded printable ASCII text
|
|
preceded and followed by MIME content identifier lines.</p>
|
|
<p>The format of the symmetric keys file, ordinarily
|
|
named <tt>ntp.keys,</tt> 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.</p>
|
|
<table>
|
|
<caption style="caption-side: bottom;">
|
|
Figure 1. Typical Symmetric Key File
|
|
</caption>
|
|
<tr><td style="border: 1px solid black; border-spacing: 0;">
|
|
<pre style="color:grey;">
|
|
# 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;fxlKgr/&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
|
|
21 MD5 sampo 10.1.2.3/24
|
|
</pre></td></tr></table>
|
|
<p>Figure 1 shows a typical symmetric keys file used by the reference
|
|
implementation. Each line of the file contains three or four fields,
|
|
first an integer between 1 and 65535, inclusive, representing the key
|
|
identifier used in the <tt>server</tt> and <tt>peer</tt> configuration
|
|
commands. Second is the key type for the message digest algorithm,
|
|
which in the absence of the OpenSSL library must be <tt>MD5</tt> 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 <tt>SHA</tt> or <tt>SHA1</tt>.
|
|
The key type can be changed using an ASCII text editor.</p>
|
|
<p>The third field is the key.</p>
|
|
<p>An MD5 key consists of a printable ASCII string less than or equal to
|
|
16 characters and terminated by whitespace or a # character. An
|
|
OpenSSL key consists of a hex-encoded ASCII string of 40 characters,
|
|
which is truncated as necessary.</p>
|
|
<p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt>
|
|
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.</p>
|
|
<p>The optional fourth field is one or more IPs, with each IP separated
|
|
with a comma. An IP may end with an optional <tt>/subnetbits</tt>
|
|
suffix, which limits the acceptance of the key identifier to packets
|
|
claiming to be from the described IP space.</p>
|
|
<p>The <tt>ntp-keygen</tt> program generates a MD5 symmetric keys
|
|
file <tt>ntpkey_MD5key_<i>hostname.filestamp</i></tt>. 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 <tt>ntp.keys</tt>, so <tt>ntp-keygen</tt> 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 <a href="ntpq.html"><tt>ntpq</tt></a>
|
|
and <a href="ntpdc.html"><tt>ntpdc</tt></a> utilities.</p>
|
|
<h4 id="bug">Bugs</h4>
|
|
<p>It can take quite a while to generate some cryptographic values.</p>
|
|
<hr>
|
|
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
|
|
</body>
|
|
</html>
|