From: Harlan Stenn Date: Mon, 10 Dec 2012 09:23:36 +0000 (-0500) Subject: Create ntp-keygen.{html,texi} X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bfcde54d702dbb356b0782df1d41f501f77e6d29;p=thirdparty%2Fntp.git Create ntp-keygen.{html,texi} bk: 50c5aa18nPtmJAW9lW8q6N2KV8hLsw --- diff --git a/.point-changed-filelist b/.point-changed-filelist index b3a37470d3..250a3ee62b 100644 --- a/.point-changed-filelist +++ b/.point-changed-filelist @@ -60,5 +60,6 @@ util/ntp-keygen-opts.c util/ntp-keygen-opts.h util/ntp-keygen.1ntp-keygenman util/ntp-keygen.1ntp-keygenmdoc +util/ntp-keygen.html util/ntp-keygen.man.in util/ntp-keygen.mdoc.in diff --git a/ChangeLog b/ChangeLog index 6c00a1d6a3..f36708ed59 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Create ntp-keygen.{html,texi}. (4.2.7p333) 2012/12/07 Released by Harlan Stenn * Autogen documentation cleanup. (4.2.7p332) 2012/12/06 Released by Harlan Stenn diff --git a/util/Makefile.am b/util/Makefile.am index 696790d423..4843ba41ac 100644 --- a/util/Makefile.am +++ b/util/Makefile.am @@ -32,11 +32,19 @@ EXTRA_DIST= \ ntp-keygen.1ntp-keygenmdoc \ ntp-keygen.man.in \ ntp-keygen.mdoc.in \ + ntp-keygen.mdoc.in \ + ntp-keygen.html \ + ntp-keygen.texi \ $(NULL) BUILT_SOURCES= ntp-keygen-opts.c ntp-keygen-opts.h CLEANFILES= DISTCLEANFILES= .version version.c config.log $(man_MANS) + +html_DATA= \ + $(srcdir)/ntp-keygen.html \ + $(NULL) + noinst_DATA= \ $(srcdir)/invoke-ntp-keygen.menu \ $(srcdir)/invoke-ntp-keygen.texi \ @@ -99,6 +107,9 @@ $(srcdir)/invoke-ntp-keygen.texi: $(srcdir)/ntp-keygen-opts.def $(std_def_list) $(run_ag) -Tagtexi-cmd.tpl -DLEVEL=section ntp-keygen-opts.def $(top_srcdir)/scripts/check--help $@ +$(srcdir)/ntp-keygen.html: $(srcdir)/ntp-keygen.texi $(top_srcdir)/sntp/include/version.texi + cd $(srcdir) && ( makeinfo --force --html --no-split -o ntp-keygen.html ntp-keygen.texi || true ) + jitter_SOURCES= jitter.c jitter.h jitter_LDADD= diff --git a/util/ntp-keygen-opts.def b/util/ntp-keygen-opts.def index 35a2bf208c..4be2efb8df 100644 --- a/util/ntp-keygen-opts.def +++ b/util/ntp-keygen-opts.def @@ -286,6 +286,136 @@ All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. By default, files are not encrypted. +.Pp +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. +.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 +option specifies the password for local encrypted files and the +.Fl -q +option the password for encrypted files sent to remote sites. +If no password is specified, the host name returned by the Unix +.Fn gethostname +function, normally the DNS name of the host is used. +.Pp +The +.Ar pw +option of the +.Ar 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 +.Ar ntpd +without password but only on the same host. +.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 +.Ar ntp.keys , +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. +The location of the keys directory can be changed by the +.Ar keysdir +configuration command in such cases. +Normally, this is in +.Pa /etc . +.Pp +This program directs commentary and error messages to the standard +error stream +.Ar stderr +and remote files to the standard output stream +.Ar 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 +.Ar ntpkey +and include the file type, generating host and filestamp, +as described in the +.Dq Cryptographic Data Files +section below. +.Ss Running the Program +To test and gain experience with Autokey concepts, log in as root and +change to the keys directory, usually +.Pa /usr/local/etc +When run for the first time, or if all files with names beginning with +.Ar ntpkey +have been removed, use the +.Nm +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. +.Pp +Run the command on as many hosts as necessary. +Designate one of them as the trusted host (TH) using +.Nm +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. +.Pp +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 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 +.Fl 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. +.Pp +Additional information on trusted groups and identity schemes is on the +.Dq Autokey Public-Key Authentication +page. + + .Pp The .Xr ntpd 8 diff --git a/util/ntp-keygen.html b/util/ntp-keygen.html new file mode 100644 index 0000000000..9de2e08441 --- /dev/null +++ b/util/ntp-keygen.html @@ -0,0 +1,1874 @@ + + +Ntp-keygen User's Manual + + + + + + + + + +

Ntp-keygen User's Manual

+
+

Short Contents

+ +
+ + + +
+ +

+Up: (dir) + +
+ +

Top

+ + + +
+ +

+Next: , +Previous: (dir), +Up: (dir) + +
+ +

NTP Key Generation Program User Manual

+ +

This document describes the use of the NTP Project's 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 4.2.7p333 of ntp-keygen. + +

+ +

+Next: , +Previous: Top, +Up: Top + +
+ + +

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 -p option specifies the password for local encrypted files and the +-q option the password for encrypted files sent to remote sites. If no +password is specified, the host name returned by the Unix gethostname() +function, normally the DNS name of the host, is used. + +

The pw option of the 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 ntp.keys, is +usually installed in /etc. Other files and links are usually installed +in /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 /etc. + +

This program directs commentary and error messages to the standard +error stream stderr and remote files to the standard output stream +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 ntpkey and include the file type, generating host and filestamp, +as described in the Cryptographic Data Files section below. + +

+ +

+Next: , +Previous: Description, +Up: Top + +
+ + +

Running the Program

+ +

To test and gain experience with Autokey concepts, log in as root and +change to the keys directory, usually /usr/local/etc. When run for the +first time, or if all files with names beginning ntpkey have been +removed, use the 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 ntp-keygen with the -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 -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 -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. + +

+ + +

+ + +
+ +

Invoking ntp-keygen

+ +

+ +

This program generates cryptographic data files used by the NTPv4 +authentication and identification schemes. +It generates MD5 key files used in symmetric key cryptography. +In addition, if the OpenSSL software library has been installed, +it generates keys, certificate and identity files used in public key +cryptography. +These files are used for cookie encryption, +digital signature and challenge/response identification algorithms +compatible with the Internet standard security infrastructure. + +

All files are in PEM-encoded printable ASCII format, +so they can be embedded as MIME attachments in mail to other sites +and certificate authorities. +By default, files are not encrypted. + +

The +ntpd(8) +configuration command +.Ic +crypto +pw +Ar +password +specifies the read password for previously encrypted files. +The daemon expires on the spot if the password is missing +or incorrect. +For convenience, if a file has been previously encrypted, +the default read password is the name of the host running +the program. +If the previous write password is specified as the host name, +these files can be read by that host with no explicit password. + +

File names begin with the prefix +.Cm +ntpkey_ +and end with the postfix +.Ar +_hostname.filestamp +, +where +.Ar +hostname +is the owner name, usually the string returned +by the Unix gethostname() routine, 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 +ntpkey\&* +command or all files generated +at a specific time can be removed by a +.Ic +rm +.Ar +\&*filestamp +command. +To further reduce the risk of misconfiguration, +the first two lines of a file contain the file name +and generation date and time as comments. + +

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. + +

Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. + +

The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +ntpd(8) +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +ntp-keygen +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss +Running +the +program +The safest way to run the +ntp-keygen +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa +/usr/local/etc +, +then run the program. +When run for the first time, +or if all +.Cm +ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. + +

The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. + +

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. + +

Running the program as other than root and using the Unix +.Ic +su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm +.rnd +in the user home directory. +However, there should be only one +.Cm +.rnd +, +most conveniently +in the root directory, so it is convenient to define the +.Cm +$RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm +/.rnd +. + +

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 +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. + +

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. + +

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. + +

Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. + +

The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +ntpd(8) +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +ntp-keygen +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss +Running +the +program +The safest way to run the +ntp-keygen +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa +/usr/local/etc +, +then run the program. +When run for the first time, +or if all +.Cm +ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. + +

The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. + +

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. + +

Running the program as other than root and using the Unix +.Ic +su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm +.rnd +in the user home directory. +However, there should be only one +.Cm +.rnd +, +most conveniently +in the root directory, so it is convenient to define the +.Cm +$RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm +/.rnd +. + +

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 +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. + +

Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +seconds. +seconds. + +

s Trusted Hosts and Groups +Each cryptographic configuration involves selection of a signature scheme +and identification scheme, called a cryptotype, +as explained in the +.Sx +Authentication +Options +section of +ntp.conf(5). +The default cryptotype uses RSA encryption, MD5 message digest +and TC identification. +First, configure a NTP subnet including one or more low-stratum +trusted hosts from which all other hosts derive synchronization +directly or indirectly. +Trusted hosts have trusted certificates; +all other hosts have nontrusted certificates. +These hosts will automatically and dynamically build authoritative +certificate trails to one or more trusted hosts. +A trusted group is the set of all hosts that have, directly or indirectly, +a certificate trail ending at a trusted host. +The trail is defined by static configuration file entries +or dynamic means described on the +.Sx +Automatic +NTP +Configuration +Options +section of +ntp.conf(5). + +

On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm +ntpkey +files. +Then run +ntp-keygen +-T to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +-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. + +

If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +ntp-keygen +with the +-S -Ar -type option, where +.Ar +type +is either +.Cm +RSA +or +.Cm +DSA +. +The most often need to do this is when a DSA-signed certificate is used. +If it is necessary to use a different certificate scheme than the default, +run +ntp-keygen +with the +-c -Ar -scheme option and selected +.Ar +scheme +as needed. +f +ntp-keygen +is run again without these options, it generates a new certificate +using the same scheme and sign key. + +

After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +ntp-keygen +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +ntpd(8) +should be restarted. +When +ntpd(8) +is restarted, it loads any new files and restarts the protocol. +Other dependent hosts will continue as usual until signatures are refreshed, +at which time the protocol is restarted. +.Ss +Identity +Schemes +As mentioned on the Autonomous Authentication page, +the default TC identity scheme is vulnerable to a middleman attack. +However, there are more secure identity schemes available, +including PC, IFF, GQ and MV described on the +.Qq +Identification +Schemes +page +(maybe available at +.Li +http://www.eecis.udel.edu/%7emills/keygen.html +) +. +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. + +

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. + +

The PC scheme supports only one trusted host in the group. +On trusted host alice run +ntp-keygen +-P -p -Ar -password to generate the host key file +.Pa +ntpkey_RSAkey_ +Ns +Ar +alice.filestamp +and trusted private certificate file +.Pa +ntpkey_RSA-MD5_cert_ +Ns +Ar +alice.filestamp +. +Copy both files to all group hosts; +they replace the files which would be generated in other schemes. +On each host bob install a soft link from the generic name +.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 +to all other hosts in the group. + +

For the IFF scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host in the group, +generate the IFF parameter file. +On trusted host alice run +ntp-keygen +-T -I -p -Ar -password to produce her parameter file +.Pa +ntpkey_IFFpar_ +Ns +Ar +alice.filestamp +, +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 +.Pa +ntpkey_iff_ +Ns +Ar +alice +to this file. +If there are no hosts restricted to operate only as clients, +there is nothing further to do. +As the IFF scheme is independent +of keys and certificates, these files can be refreshed as needed. + +

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 +ntp-keygen +-e and pipe the output to a file or mail program. +Copy or mail this file to all restricted clients. +On these clients install a soft link from the generic +.Pa +ntpkey_iff_ +Ns +Ar +alice +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. + +

For the GQ scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host +in the group, generate the IFF parameter file. +On trusted host alice run +ntp-keygen +-T -G -p -Ar -password to produce her parameter file +.Pa +ntpkey_GQpar_ +Ns +Ar +alice.filestamp +, +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +.Pa +ntpkey_gq_ +Ns +Ar +alice +to this file. +In addition, on each host bob install a soft link +from generic +.Pa +ntpkey_gq_ +Ns +Ar +bob +to this file. +As the GQ scheme updates the GQ parameters file and certificate +at the same time, keys and certificates can be regenerated as needed. + +

For the MV scheme, proceed as in the TC scheme to generate keys +and certificates for all group hosts. +For illustration assume trish is the TA, alice one of several trusted hosts +and bob one of her clients. +On TA trish run +ntp-keygen +-V -Ar -n -p -Ar -password, where +.Ar +n +is the number of revokable keys (typically 5) to produce +the parameter file +.Pa +ntpkeys_MVpar_ +Ns +Ar +trish.filestamp +and client key files +.Pa +ntpkeys_MVkeyd_ +Ns +Ar +trish.filestamp +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 +.Pa +ntpkey_mv_ +Ns +Ar +alice +to this file. +Copy one of the client key files to alice for later distribution +to her clients. +It doesn't matter which client key file goes to alice, +since they all work the same way. +Alice copies the client key file to all of her cliens. +On client bob install a soft link from generic +.Pa +ntpkey_mvkey_ +Ns +Ar +bob +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +.Ss +Command +Line +Options +

+
‘Fl’
Select certificate message digest/signature encryption scheme. +The +.Ar +scheme +can be one of the following: +. +Cm +RSA-MD2 +, +RSA-MD5 +, +RSA-SHA +, +RSA-SHA1 +, +RSA-MDC2 +, +RSA-RIPEMD160 +, +DSA-SHA +, +or +.Cm +DSA-SHA1 +. +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 +.Cm +RSA-MD5 +. +
‘Fl’
Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +
‘Fl’
Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +
‘Fl’
Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +
‘Fl’
Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +
‘Fl’
Generate new host keys, obsoleting any that may exist. +
‘Fl’
Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +
‘Fl’
Set the suject name to +.Ar +name +. +This is used as the subject field in certificates +and in the file name for host and sign keys. +
‘Fl’
Generate MD5 keys, obsoleting any that may exist. +
‘Fl’
Generate a private certificate. +By default, the program generates public certificates. +
‘Fl’
Encrypt generated files containing private data with +.Ar +password +and the DES-CBC algorithm. +
‘Fl’
Set the password for reading files to password. +
‘Fl’
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. +
‘Fl’
Set the issuer name to +.Ar +name +. +This is used for the issuer field in certificates +and in the file name for identity files. +
‘Fl’
Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +
‘Fl’
Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. + +

.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 +ntp-keygen +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. + +

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. + +

The entropy seed used by the OpenSSL library is contained in a file, +usually called +.Cm +.rnd +, +which must be available when starting the NTP daemon +or the +ntp-keygen +program. +The NTP daemon will first look for the file +using the path specified by the +.Ic +randfile +subcommand of the +.Ic +crypto +configuration command. +If not specified in this way, or when starting the +ntp-keygen +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 +.Cm +.rnd +file in the user home directory. +If the file is not available or cannot be written, +the daemon exits with a message to the system log and the program +exits with a suitable error message. +.Ss +Cryptographic +Data +Files +All other file formats begin with two lines. +The first contains the file name, including the generated host name +and filestamp. +The second contains the datestamp in conventional Unix date format. +Lines beginning with # are considered comments and ignored by the +ntp-keygen +program and +ntpd(8) +daemon. +Cryptographic values are encoded first using ASN.1 rules, +then encrypted if necessary, and finally written PEM-encoded +printable ASCII format preceded and followed by MIME content identifier lines. + +

The format of the symmetric keys file is somewhat different +than the other files in the interest of backward compatibility. +Since DES-CBC is deprecated in NTPv4, the only key format of interest +is MD5 alphanumeric strings. +Following hte heard the keys are +entered one per line in the format +.D1 +Ar +keyno +type +key +where +.Ar +keyno +is a positive integer in the range 1-65,535, +.Ar +type +is the string MD5 defining the key format and +.Ar +key +is the key itself, +which is a printable ASCII string 16 characters or less in length. +Each character is chosen from the 93 printable characters +in the range 0x21 through 0x7f excluding space and the +.Ql +# +character. + +

Note that the keys used by the +ntpq(8) +and +ntpdc(8) +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 +ntp-keygen +program generates a MD5 symmetric keys file +.Pa +ntpkey_MD5key_ +Ns +Ar +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 +.Pa +ntp.keys +, +so +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 +ntpq(8) +and +ntpdc(8) +utilities. + +

This section was generated by AutoGen, +using the agtexi-cmd template and the option descriptions for the ntp-keygen program. +This software is released under the NTP license, <http://ntp.org/license>. + +

+ +
+ + +

+Next: , +Up: ntp-keygen Invocation + +
+ +

ntp-keygen help/usage (--help)

+ +

+This is the automatically generated usage text for ntp-keygen. + +

The text printed is the same whether selected with the help option +(--help) or the more-help option (--more-help). more-help will print +the usage text by passing it through a pager program. +more-help is disabled on platforms without a working +fork(2) function. The PAGER environment variable is +used to select the program, defaulting to more. Both will exit +with a status code of 0. + + 

     ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.7p333
+     USAGE:  ntp-keygen [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
+       Flg Arg Option-Name    Description
+        -b Num imbits         identity modulus bits
+                                     - It must be in the range:
+                                       256 to 2048
+        -c Str certificate    certificate scheme
+        -C Str cipher         privatekey cipher
+        -d no  debug-level    Increase debug verbosity level
+                                     - may appear multiple times
+        -D Num set-debug-level Set the debug verbosity level
+                                     - may appear multiple times
+        -e no  id-key         Write IFF or GQ identity keys
+        -G no  gq-params      Generate GQ parameters and keys
+        -H no  host-key       generate RSA host key
+        -I no  iffkey         generate IFF parameters
+        -i Str ident          set Autokey group name
+        -l Num lifetime       set certificate lifetime
+        -M no  md5key         generate MD5 keys
+        -m Num modulus        modulus
+                                     - It must be in the range:
+                                       256 to 2048
+        -P no  pvt-cert       generate PC private certificate
+        -p Str pvt-passwd     output private password
+        -q Str get-pvt-passwd input private password
+        -S Str sign-key       generate sign key (RSA or DSA)
+        -s Str subject-name   set host and optionally group name
+        -T no  trusted-cert   trusted certificate (TC scheme)
+        -V Num mv-params      generate <num> MV parameters
+        -v Num mv-keys        update <num> MV keys
+           opt version        Output version information and exit
+        -? no  help           Display extended usage information and exit
+        -! no  more-help      Extended usage information passed thru pager
+        -> opt save-opts      Save the option state to a config file
+        -< Str load-opts      Load options from a config file
+                                     - disabled as --no-load-opts
+                                     - may appear multiple times
+     
+     Options are specified by doubled hyphens and their name or by a single
+     hyphen and the flag character.
+     
+     
+     
+     The following option preset mechanisms are supported:
+      - reading file $HOME/.ntprc
+      - reading file ./.ntprc
+      - examining environment variables named NTP_KEYGEN_*
+     
+     please send bug reports to:  http://bugs.ntp.org, bugs@ntp.org
+
+
+ + +

+Next: , +Previous: ntp-keygen usage, +Up: ntp-keygen Invocation + +
+ +

imbits option (-b)

+ +

+This is the “identity modulus bits” option. +This option takes an argument number imbits. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

The number of bits in the identity modulus. The default is 256. +

+ + +

+Next: , +Previous: ntp-keygen imbits, +Up: ntp-keygen Invocation + +
+ +

certificate option (-c)

+ +

+This is the “certificate scheme” option. +This option takes an argument string scheme. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

scheme is one of +RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, +DSA-SHA, or DSA-SHA1. + +

Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA-MD5. +

+ + +

+Next: , +Previous: ntp-keygen certificate, +Up: ntp-keygen Invocation + +
+ +

cipher option (-C)

+ +

+This is the “privatekey cipher” option. +This option takes an argument string cipher. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Select the cipher which is used to encrypt the files containing +private keys. The default is three-key triple DES in CBC mode, +equivalent to "-C des-ede3-cbc". The openssl tool lists ciphers +available in "openssl -h" output. +

+ + +

+Next: , +Previous: ntp-keygen cipher, +Up: ntp-keygen Invocation + +
+ +

id-key option (-e)

+ +

+This is the “write iff or gq identity keys” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +

+ + +

+Next: , +Previous: ntp-keygen id-key, +Up: ntp-keygen Invocation + +
+ +

gq-params option (-G)

+ +

+This is the “generate gq parameters and keys” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +

+ + +

+Next: , +Previous: ntp-keygen gq-params, +Up: ntp-keygen Invocation + +
+ +

host-key option (-H)

+ +

+This is the “generate rsa host key” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate new host keys, obsoleting any that may exist. +

+ + +

+Next: , +Previous: ntp-keygen host-key, +Up: ntp-keygen Invocation + +
+ +

iffkey option (-I)

+ +

+This is the “generate iff parameters” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +

+ + +

+Next: , +Previous: ntp-keygen iffkey, +Up: ntp-keygen Invocation + +
+ +

ident option (-i)

+ +

+This is the “set autokey group name” option. +This option takes an argument string group. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

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 -i/–ident or +using -s/–subject-name following an '´character, is also a +part of the self-signed host certificate's subject and issuer +names in the form host +

or 'server ident' configuration in ntpd's configuration file. +

+ + +

+Next: , +Previous: ntp-keygen ident, +Up: ntp-keygen Invocation + +
+ +

lifetime option (-l)

+ +

+This is the “set certificate lifetime” option. +This option takes an argument number lifetime. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Set the certificate expiration to lifetime days from now. +

+ + +

+Next: , +Previous: ntp-keygen lifetime, +Up: ntp-keygen Invocation + +
+ +

md5key option (-M)

+ +

+This is the “generate md5 keys” option. +Generate MD5 keys, obsoleting any that may exist. +

+ + +

+Next: , +Previous: ntp-keygen md5key, +Up: ntp-keygen Invocation + +
+ +

modulus option (-m)

+ +

+This is the “modulus” option. +This option takes an argument number modulus. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

The number of bits in the prime modulus. The default is 512. +

+ + +

+Next: , +Previous: ntp-keygen modulus, +Up: ntp-keygen Invocation + +
+ +

pvt-cert option (-P)

+ +

+This is the “generate pc private certificate” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate a private certificate. By default, the program generates +public certificates. +

+ + +

+Next: , +Previous: ntp-keygen pvt-cert, +Up: ntp-keygen Invocation + +
+ +

pvt-passwd option (-p)

+ +

+This is the “output private password” option. +This option takes an argument string passwd. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Encrypt generated files containing private data with the specified +password and the cipher selected with -C/–cipher. +

+ + +

+Next: , +Previous: ntp-keygen pvt-passwd, +Up: ntp-keygen Invocation + +
+ +

get-pvt-passwd option (-q)

+ +

+This is the “input private password” option. +This option takes an argument string passwd. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Set the password for reading files to the specified password. +

+ + +

+Next: , +Previous: ntp-keygen get-pvt-passwd, +Up: ntp-keygen Invocation + +
+ +

sign-key option (-S)

+ +

+This is the “generate sign key (rsa or dsa)” option. +This option takes an argument string sign. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

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. +

+ + +

+Next: , +Previous: ntp-keygen sign-key, +Up: ntp-keygen Invocation + +
+ +

subject-name option (-s)

+ +

+This is the “set host and optionally group name” option. +This option takes an argument string host@group. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Set the Autokey host name, and optionally, group name specified +following an '´character. The host name is used in the file +name of generated host and signing certificates, without the +group name. The host name, and if provided, group name are used +in host +

fields. Specifying '-s is allowed, and results in +leaving the host name unchanged while appending +

subject and issuer fields, as with -i group. 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. +

+ + +

+Next: , +Previous: ntp-keygen subject-name, +Up: ntp-keygen Invocation + +
+ +

trusted-cert option (-T)

+ +

+This is the “trusted certificate (tc scheme)” option. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +

+ + +

+Next: , +Previous: ntp-keygen trusted-cert, +Up: ntp-keygen Invocation + +
+ +

mv-params option (-V)

+ +

+This is the “generate <num> mv parameters” option. +This option takes an argument number num. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +

+ + +

+Next: , +Previous: ntp-keygen mv-params, +Up: ntp-keygen Invocation + +
+ +

mv-keys option (-v)

+ +

+This is the “update <num> mv keys” option. +This option takes an argument number num. + +

This option has some usage constraints. It: +

    +
  • must be compiled in by defining AUTOKEY during the compilation. +
+ +

This option has no ‘doc’ documentation. + +

+ + +

+Next: , +Previous: ntp-keygen mv-keys, +Up: ntp-keygen Invocation + +
+ +

presetting/configuring ntp-keygen

+ +

Any option that is not marked as not presettable may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named NTP-KEYGEN and NTP-KEYGEN_<OPTION_NAME>. <OPTION_NAME> must be one of +the options listed above in upper case and segmented with underscores. +The NTP-KEYGEN variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + +

libopts will search in 2 places for configuration files: +

    +
  • $HOME +
  • $PWD +
+ The environment variables HOME, and PWD +are expanded and replaced when ntp-keygen runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named .ntprc is searched for +within that directory and processed. + +

Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +

Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: + 

         [NTP-KEYGEN]
+
+

or by + 

         <?program ntp-keygen>
+
+

Do not mix these styles within one configuration file. + +

Compound values and carefully constructed string values may also be +specified using XML syntax: + 

         <option-name>
+            <sub-opt>...&lt;...&gt;...</sub-opt>
+         </option-name>
+
+

yielding an option-name.sub-opt string value of + 

         "...<...>..."
+
+

AutoOpts does not track suboptions. You simply note that it is a +hierarchicly valued option. AutoOpts does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +

The command line options relating to configuration and/or usage help are: + +

version (-)
+ +

Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +

+
‘version’
Only print the version. This is the default. +
‘copyright’
Name the copyright usage licensing terms. +
‘verbose’
Print the full copyright usage licensing terms. +
+ +
+ + +

+Next: , +Previous: ntp-keygen config, +Up: ntp-keygen Invocation + +
+ +

ntp-keygen exit status

+ +

One of the following exit values will be returned: +

+
‘0 (EXIT_SUCCESS)’
Successful program execution. +
‘1 (EXIT_FAILURE)’
The operation failed or the command syntax was not valid. +
‘66 (EX_NOINPUT)’
A specified configuration file could not be loaded. +
‘70 (EX_SOFTWARE)’
libopts had an internal operational error. Please report +it to autogen-users@lists.sourceforge.net. Thank you. +
+
+ + +

+Next: , +Previous: ntp-keygen exit status, +Up: ntp-keygen Invocation + +
+ +

ntp-keygen Usage

+ +

The +-p -Ar -password option specifies the write password and +-q -Ar -password option the read password for previously encrypted files. +The +ntp-keygen +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. +

+ + +

+Next: , +Previous: ntp-keygen Usage, +Up: ntp-keygen Invocation + +
+ +

ntp-keygen Notes

+ +

This document corresponds to version of NTP. +Portions of this document came from FreeBSD. +

+ + +

+Previous: ntp-keygen Notes, +Up: ntp-keygen Invocation + +
+ +

ntp-keygen Bugs

+ +

It can take quite a while to generate some cryptographic values, +from one to several minutes with modern architectures +such as UltraSPARC and up to tens of minutes to an hour +with older architectures such as SPARC IPC. + +

Please report bugs to http://bugs.ntp.org . + +

+ +

+Next: , +Previous: Running the Program, +Up: Top + +
+ + +

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 .rnd, which must be available when +starting the ntp-keygen program or ntpd daemon. + +

The OpenSSL library looks for the file using the path specified by the +RANDFILE environment variable in the user home directory, whether root +or some other user. If the RANDFILE environment variable is not +present, the library looks for the .rnd file in the user home +directory. Since both the ntp-keygen program and ntpd daemon must run +as root, the logical place to put this file is in /.rnd or /root/.rnd. +If the file is not available or cannot be written, the program exits +with a message to the system log. + +

+ +

+Previous: Random Seed File, +Up: Top + +
+ + +

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 +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 ntpkey_key_host.fstamp. The second line +contains the datestamp in conventional Unix date format. Lines +beginning with # 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 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. + + 

         # 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~pV_5  # MD5 key
+          3 MD5 :lnoVsE%Yz*avh%EtNC  # MD5 key
+          4 MD5 |fdZrf0sF~^V  # MD5 key
+          5 MD5 IyAG>O"y"LmCRS!*bHC  # MD5 key
+          6 MD5 ">e\A  # 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
+
+

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 65534, 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 ntpq and 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 ntp-keygen program generates a MD5 symmetric keys file +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 +ntp.keys, so 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 ntpq and +ntpdc utilities. + + + diff --git a/util/ntp-keygen.texi b/util/ntp-keygen.texi new file mode 100644 index 0000000000..7f79e2c6ff --- /dev/null +++ b/util/ntp-keygen.texi @@ -0,0 +1,274 @@ +\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 -p option specifies the password for local encrypted files and the +-q option the password for encrypted files sent to remote sites. If no +password is specified, the host name returned by the Unix gethostname() +function, normally the DNS name of the host, is used. + +The pw option of the 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 ntp.keys, is +usually installed in /etc. Other files and links are usually installed +in /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 /etc. + +This program directs commentary and error messages to the standard +error stream stderr and remote files to the standard output stream +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 ntpkey and include the file type, generating host and filestamp, +as described in the 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 /usr/local/etc. When run for the +first time, or if all files with names beginning ntpkey have been +removed, use the 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 ntp-keygen with the -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 -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 -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 .rnd, which must be available when +starting the ntp-keygen program or ntpd daemon. + +The OpenSSL library looks for the file using the path specified by the +RANDFILE environment variable in the user home directory, whether root +or some other user. If the RANDFILE environment variable is not +present, the library looks for the .rnd file in the user home +directory. Since both the ntp-keygen program and ntpd daemon must run +as root, the logical place to put this file is in /.rnd or /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 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 +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 ntpkey_key_host.fstamp. The second line +contains the datestamp in conventional Unix date format. Lines +beginning with # 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 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 65534, 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 ntpq and 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.