308 lines
13 KiB
Plaintext
308 lines
13 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename ntp-keygen.info
|
|
@settitle Ntp-keygen User's Manual
|
|
@include ../sntp/include/version.texi
|
|
@paragraphindent 2
|
|
@c %**end of header
|
|
|
|
@ifinfo
|
|
This file documents the use of the NTP Project's @code{ntp-keygen}
|
|
program, which generates various keys for @code{ntpd},
|
|
@end ifinfo
|
|
|
|
@direntry
|
|
* ntp-keygen: (ntp-keygen). NTP Key Generation
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title NTP Key Generation User's Manual
|
|
@subtitle ntp-keygen, version @value{VERSION}, @value{UPDATED}
|
|
@c @author Max @email{foo@ntp.org}
|
|
@end titlepage
|
|
|
|
@c @page
|
|
@c @vskip 0pt plus 1filll
|
|
|
|
@shortcontents
|
|
|
|
@menu
|
|
* Description::
|
|
* ntp-keygen Invocation:: Invoking ntp-keygen
|
|
* Running the Program::
|
|
* Random Seed File::
|
|
* Cryptographic Data Files::
|
|
@end menu
|
|
|
|
@node Top, Description, (dir), (dir)
|
|
@top NTP Key Generation Program User Manual
|
|
|
|
This document describes the use of the NTP Project's @code{ntp-keygen}
|
|
program, that 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.
|
|
|
|
This document applies to version @value{VERSION} of @code{ntp-keygen}.
|
|
|
|
@node Description, Running the Program, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@section Description
|
|
|
|
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.
|
|
|
|
When used to generate message digest keys, the program produces a file
|
|
containing ten pseudo-random printable ASCII strings suitable for the
|
|
MD5 message digest algorithm included in the distribution.
|
|
If the
|
|
OpenSSL library is installed, it produces an additional ten hex-encoded
|
|
random bit strings suitable for the SHA1 and other message digest
|
|
algorithms.
|
|
The message digest keys file must be distributed and stored
|
|
using secure means beyond the scope of NTP itself.
|
|
Besides the keys
|
|
used for ordinary NTP associations, additional keys can be defined as
|
|
passwords for the ntpq and ntpdc utility programs.
|
|
|
|
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.
|
|
|
|
Some files used by this program are encrypted using a private password.
|
|
The @code{-p} option specifies the password for local encrypted files and the
|
|
@code{-q} option the password for encrypted files sent to remote sites.
|
|
If no password is specified, the host name returned by the Unix
|
|
@code{gethostname()} function, normally the DNS name of the host, is used.
|
|
|
|
The @kbd{pw} option of the @code{crypto} 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 ntpd without password, but only on the same
|
|
host.
|
|
|
|
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 @code{ntp.keys}, is
|
|
usually installed in @code{/etc}.
|
|
Other files and links are usually installed
|
|
in @code{/usr/local/etc}, 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 keysdir
|
|
configuration command in such cases.
|
|
Normally, this is in @code{/etc}.
|
|
|
|
This program directs commentary and error messages to the standard
|
|
error stream @code{stderr} and remote files to the standard output stream
|
|
@code{stdout} 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 @code{ntpkey} and include the file type,
|
|
generating host and filestamp,
|
|
as described in the @ref{Cryptographic Data Files} section below.
|
|
|
|
@node Running the Program, Random Seed File, Description, Top
|
|
@comment node-name, next, previous, up
|
|
@section Running the Program
|
|
|
|
To test and gain experience with Autokey concepts, log in as root and
|
|
change to the keys directory, usually @code{/usr/local/etc}.
|
|
When run for the
|
|
first time, or if all files with names beginning @code{ntpkey}] have been
|
|
removed, use the @code{ntp-keygen} 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.
|
|
|
|
Run the command on as many hosts as necessary.
|
|
Designate one of them as the trusted host (TH) using @code{ntp-keygen}
|
|
with the @code{-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.
|
|
|
|
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 @code{-S} 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 @code{-c} option.
|
|
|
|
The rules say cryptographic media should be generated with proventic
|
|
filestamps, which means the host should already be synchronized before
|
|
this program is run.
|
|
This of course creates a chicken-and-egg problem
|
|
when the host is started for the first time.
|
|
Accordingly, the host time
|
|
should be set by some other means, such as eyeball-and-wristwatch, at
|
|
least so that the certificate lifetime is within the current year.
|
|
After that and when the host is synchronized to a proventic source, the
|
|
certificate should be re-generated.
|
|
|
|
Additional information on trusted groups and identity schemes is on the
|
|
Autokey Public-Key Authentication page.
|
|
|
|
@include invoke-ntp-keygen.texi
|
|
|
|
@node Random Seed File, Cryptographic Data Files, Running the Program, Top
|
|
@comment node-name, next, previous, up
|
|
@section 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 OpenSSL library routines.
|
|
If a site supports ssh, 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 @code{.rnd}, which must be available when
|
|
starting the @code{ntp-keygen} program or @code{ntpd} daemon.
|
|
|
|
The OpenSSL library looks for the file using the path specified by the
|
|
@code{RANDFILE} environment variable in the user home directory, whether root
|
|
or some other user.
|
|
If the @code{RANDFILE} environment variable is not
|
|
present, the library looks for the @code{.rnd} file in the user home
|
|
directory.
|
|
Since both the @code{ntp-keygen} program and @code{ntpd} daemon must run
|
|
as root, the logical place to put this file is in @code{/.rnd} or
|
|
@code{/root/.rnd}.
|
|
If the file is not available or cannot be written, the program exits
|
|
with a message to the system log.
|
|
|
|
@node Cryptographic Data Files, , Random Seed File, Top
|
|
@comment node-name, next, previous, up
|
|
@section Cryptographic Data Files
|
|
|
|
File and link names are in the @code{form ntpkey_key_name.fstamp},
|
|
where @code{key} is the key or parameter type,
|
|
@code{name} is the host or group name and
|
|
@code{fstamp} is the filestamp (NTP seconds) when the file was created).
|
|
By convention, key names in generated file names include both upper and
|
|
lower case characters, while key names in generated link names include
|
|
only lower case characters. The filestamp is not used in generated link
|
|
names.
|
|
|
|
The key name is a string defining the cryptographic key type.
|
|
Key types include public/private keys host and sign, certificate cert
|
|
and several challenge/response key types.
|
|
By convention, client files used for
|
|
challenges have a par subtype, as in the IFF challenge IFFpar, while
|
|
server 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 @code{ntpkey_key_host.fstamp}.
|
|
The second line contains the datestamp in conventional Unix date format.
|
|
Lines beginning with @code{#} are ignored.
|
|
|
|
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.
|
|
|
|
The format of the symmetric keys file, ordinarily named @code{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.
|
|
|
|
@example
|
|
# ntpkey_MD5key_hms.local.3564038757
|
|
# Sun Dec 9 02:45:57 2012
|
|
|
|
1 MD5 "]!ghT%O;3)WJ,/Nc:>I # MD5 key
|
|
2 MD5 lu+H^tF46BKR-6~p{V_5 # MD5 key
|
|
3 MD5 :lnoVsE%Y}z*avh%EtNC # MD5 key
|
|
4 MD5 |fdZrf0sF~@PHZ;w-i^V # MD5 key
|
|
5 MD5 IyAG>O"}y"LmCRS!*bHC # MD5 key
|
|
6 MD5 ">e\A@>hT/661ri52,,H # MD5 key
|
|
7 MD5 c9x=M'CfLxax9v)PV-si # MD5 key
|
|
8 MD5 E|=jvFVov?Bn|Ev=&aK\ # MD5 key
|
|
9 MD5 T!c4UT&`(m$+m+B6,`Q0 # MD5 key
|
|
10 MD5 JVF/1=)=IFbHbJQz..Cd # MD5 key
|
|
11 SHA1 6dea311109529e436c2b4fccae9bc753c16d1b48 # SHA1 key
|
|
12 SHA1 7076f373d86c4848c59ff8046e49cb7d614ec394 # SHA1 key
|
|
13 SHA1 5f48b1b60591eb01b7cf1d33b7774f08d20262d3 # SHA1 key
|
|
14 SHA1 eed5ab9d9497319ec60cf3781d52607e76720178 # SHA1 key
|
|
15 SHA1 f283562611a04c964da8126296f5f8e58c3f85de # SHA1 key
|
|
16 SHA1 1930da171297dd63549af50b29449de17dcf341f # SHA1 key
|
|
17 SHA1 fee892110358cd4382322b889869e750db8e8a8f # SHA1 key
|
|
18 SHA1 b5520c9fadd7ad3fd8bfa061c8821b65d029bb37 # SHA1 key
|
|
19 SHA1 8c74fb440ec80f453ec6aaa62b9baed0ab723b92 # SHA1 key
|
|
20 SHA1 6bc05f734306a189326000970c19b3910f403795 # SHA1 key
|
|
@end example
|
|
|
|
Figure 1. Typical Symmetric Key File
|
|
|
|
Figure 1 shows a typical symmetric keys file used by the reference
|
|
implementation.
|
|
Each line of the file contains three fields, first an
|
|
integer between 1 and 65535, inclusive, representing the key identifier
|
|
used in the server and peer configuration commands.
|
|
Next is the key type for the message digest algorithm,
|
|
which in the absence of the
|
|
OpenSSL library must be 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
|
|
SHA or SHA1.
|
|
The key type can be changed using an ASCII text editor.
|
|
|
|
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.
|
|
|
|
Note that the keys used by the @code{ntpq} and @code{ntpdc} 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.
|
|
|
|
The @code{ntp-keygen} program generates a MD5 symmetric keys file
|
|
@code{ntpkey_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 @code{ntp.keys}, so @code{ntp-keygen}
|
|
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 @code{ntpq} and
|
|
@code{ntpdc} utilities.
|