diff options
Diffstat (limited to 'util/invoke-ntp-keygen.texi')
| -rw-r--r-- | util/invoke-ntp-keygen.texi | 1354 |
1 files changed, 1354 insertions, 0 deletions
diff --git a/util/invoke-ntp-keygen.texi b/util/invoke-ntp-keygen.texi new file mode 100644 index 000000000000..56ab5a8d2504 --- /dev/null +++ b/util/invoke-ntp-keygen.texi @@ -0,0 +1,1354 @@ +@node ntp-keygen Invocation +@section Invoking ntp-keygen +@pindex ntp-keygen +@cindex Create a NTP host key +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntp-keygen.texi) +# +# It has been AutoGen-ed December 19, 2014 at 07:50:55 AM by AutoGen 5.18.5pre4 +# From the definitions ntp-keygen-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + +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. + +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 +@code{ntpq(1ntpqmdoc)} +and +@code{ntpdc(1ntpdcmdoc)} +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 +@kbd{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 +@kbd{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 +@kbd{ntp.keys}, +is usually installed in +@file{/etc}. +Other files and links are usually installed in +@file{/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 +@kbd{keysdir} +configuration command in such cases. +Normally, this is in +@file{/etc}. + +This program directs commentary and error messages to the standard +error stream +@kbd{stderr} +and remote files to the standard output stream +@kbd{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 +@kbd{ntpkey} +and include the file type, generating host and filestamp, +as described in the +@quotedblleft{}Cryptographic Data Files@quotedblright{} +section below. +@subsubsection Running the Program +To test and gain experience with Autokey concepts, log in as root and +change to the keys directory, usually +@file{/usr/local/etc} +When run for the first time, or if all files with names beginning with +@kbd{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 +@quotedblleft{}Autokey Public-Key Authentication@quotedblright{} +page. + + + +The +@code{ntpd(1ntpdmdoc)} +configuration command +@code{crypto} @code{pw} @kbd{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 +@code{ntpkey_} +and end with the postfix +@kbd{_hostname.filestamp}, +where +@kbd{hostname} +is the owner name, usually the string returned +by the Unix gethostname() routine, and +@kbd{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 +@code{rm} @code{ntpkey*} +command or all files generated +at a specific time can be removed by a +@code{rm} +@kbd{*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 +@file{/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, +@code{ntpd(1ntpdmdoc)} +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +@code{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. +@subsubsection Running the program +The safest way to run the +@code{ntp-keygen} +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +@file{/usr/local/etc}, +then run the program. +When run for the first time, +or if all +@code{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 +@code{su} +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +@code{.rnd} +in the user home directory. +However, there should be only one +@code{.rnd}, +most conveniently +in the root directory, so it is convenient to define the +@code{$RANDFILE} +environment variable used by the OpenSSL library as the path to +@code{/.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 +@file{/etc} +using the +@code{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 +@file{/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, +@code{ntpd(1ntpdmdoc)} +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +@code{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. +@subsubsection Running the program +The safest way to run the +@code{ntp-keygen} +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +@file{/usr/local/etc}, +then run the program. +When run for the first time, +or if all +@code{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 +@code{su} +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +@code{.rnd} +in the user home directory. +However, there should be only one +@code{.rnd}, +most conveniently +in the root directory, so it is convenient to define the +@code{$RANDFILE} +environment variable used by the OpenSSL library as the path to +@code{/.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 +@file{/etc} +using the +@code{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 +@ref{Authentication Options} +section of +@code{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 +@ref{Automatic NTP Configuration Options} +section of +@code{ntp.conf(5)}. + +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +@code{ntpkey} +files. +Then run +@code{ntp-keygen} +@code{-T} +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +@code{-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 +@code{ntp-keygen} +with the +@code{-S} @kbd{type} +option, where +@kbd{type} +is either +@code{RSA} +or +@code{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 +@code{ntp-keygen} +with the +@code{-c} @kbd{scheme} +option and selected +@kbd{scheme} +as needed. +f +@code{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 +@code{ntp-keygen} +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +@code{ntpd(1ntpdmdoc)} +should be restarted. +When +@code{ntpd(1ntpdmdoc)} +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. +@subsubsection 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 +"Identification Schemes" +page +(maybe available at +@code{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 +@code{ntp-keygen} +@code{-P} +@code{-p} @kbd{password} +to generate the host key file +@file{ntpkey_RSAkey_}@kbd{alice.filestamp} +and trusted private certificate file +@file{ntpkey_RSA-MD5_cert_}@kbd{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 +@file{ntpkey_host_}@kbd{bob} +to the host key file and soft link +@file{ntpkey_cert_}@kbd{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 +@code{ntp-keygen} +@code{-T} +@code{-I} +@code{-p} @kbd{password} +to produce her parameter file +@file{ntpkey_IFFpar_}@kbd{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 +@file{ntpkey_iff_}@kbd{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 +@code{ntp-keygen} +@code{-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 +@file{ntpkey_iff_}@kbd{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 +@code{ntp-keygen} +@code{-T} +@code{-G} +@code{-p} @kbd{password} +to produce her parameter file +@file{ntpkey_GQpar_}@kbd{alice.filestamp}, +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +@file{ntpkey_gq_}@kbd{alice} +to this file. +In addition, on each host bob install a soft link +from generic +@file{ntpkey_gq_}@kbd{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 +@code{ntp-keygen} +@code{-V} @kbd{n} +@code{-p} @kbd{password}, +where +@kbd{n} +is the number of revokable keys (typically 5) to produce +the parameter file +@file{ntpkeys_MVpar_}@kbd{trish.filestamp} +and client key files +@file{ntpkeys_MVkeyd_}@kbd{trish.filestamp} +where +@kbd{d} +is the key number (0 < +@kbd{d} +< +@kbd{n}). +Copy the parameter file to alice and install a soft link +from the generic +@file{ntpkey_mv_}@kbd{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 +@file{ntpkey_mvkey_}@kbd{bob} +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +@subsubsection Command Line Options +@table @asis +@item @code{-c} @kbd{scheme} +Select certificate message digest/signature encryption scheme. +The +@kbd{scheme} +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +@code{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 +@code{RSA-MD5}. +@item @code{-d} +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +@item @code{-e} +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +@item @code{-G} +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +@item @code{-g} +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +@item @code{-H} +Generate new host keys, obsoleting any that may exist. +@item @code{-I} +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +@item @code{-i} @kbd{name} +Set the suject name to +@kbd{name}. +This is used as the subject field in certificates +and in the file name for host and sign keys. +@item @code{-M} +Generate MD5 keys, obsoleting any that may exist. +@item @code{-P} +Generate a private certificate. +By default, the program generates public certificates. +@item @code{-p} @kbd{password} +Encrypt generated files containing private data with +@kbd{password} +and the DES-CBC algorithm. +@item @code{-q} +Set the password for reading files to password. +@item @code{-S} @code{[@code{RSA} | @code{DSA}]} +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. +@item @code{-s} @kbd{name} +Set the issuer name to +@kbd{name}. +This is used for the issuer field in certificates +and in the file name for identity files. +@item @code{-T} +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +@item @code{-V} @kbd{nkeys} +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +@end table +@subsubsection 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 +@code{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 +@code{.rnd}, +which must be available when starting the NTP daemon +or the +@code{ntp-keygen} +program. +The NTP daemon will first look for the file +using the path specified by the +@code{randfile} +subcommand of the +@code{crypto} +configuration command. +If not specified in this way, or when starting the +@code{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 +@code{.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. +@subsubsection 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 +@code{ntp-keygen} +program and +@code{ntpd(1ntpdmdoc)} +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 +@example +@kbd{keyno} @kbd{type} @kbd{key} +@end example +where +@kbd{keyno} +is a positive integer in the range 1-65,535, +@kbd{type} +is the string MD5 defining the key format and +@kbd{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 +@quoteleft{}#@quoteright{} +character. + +Note that the keys used by the +@code{ntpq(1ntpqmdoc)} +and +@code{ntpdc(1ntpdcmdoc)} +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 +@file{ntpkey_MD5key_}@kbd{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 +@file{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(1ntpqmdoc)} +and +@code{ntpdc(1ntpdcmdoc)} +utilities. + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp-keygen} program. +This software is released under the NTP license, <http://ntp.org/license>. + +@menu +* ntp-keygen usage:: ntp-keygen help/usage (@option{--help}) +* ntp-keygen imbits:: imbits option (-b) +* ntp-keygen certificate:: certificate option (-c) +* ntp-keygen cipher:: cipher option (-C) +* ntp-keygen id-key:: id-key option (-e) +* ntp-keygen gq-params:: gq-params option (-G) +* ntp-keygen host-key:: host-key option (-H) +* ntp-keygen iffkey:: iffkey option (-I) +* ntp-keygen ident:: ident option (-i) +* ntp-keygen lifetime:: lifetime option (-l) +* ntp-keygen md5key:: md5key option (-M) +* ntp-keygen modulus:: modulus option (-m) +* ntp-keygen pvt-cert:: pvt-cert option (-P) +* ntp-keygen password:: password option (-p) +* ntp-keygen export-passwd:: export-passwd option (-q) +* ntp-keygen sign-key:: sign-key option (-S) +* ntp-keygen subject-name:: subject-name option (-s) +* ntp-keygen trusted-cert:: trusted-cert option (-T) +* ntp-keygen mv-params:: mv-params option (-V) +* ntp-keygen mv-keys:: mv-keys option (-v) +* ntp-keygen config:: presetting/configuring ntp-keygen +* ntp-keygen exit status:: exit status +* ntp-keygen Usage:: Usage +* ntp-keygen Notes:: Notes +* ntp-keygen Bugs:: Bugs +@end menu + +@node ntp-keygen usage +@subsection ntp-keygen help/usage (@option{--help}) +@cindex ntp-keygen help + +This is the automatically generated usage text for ntp-keygen. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.8 +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 password local private password + -q Str export-passwd export IFF or GQ group keys with 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> +@end example +@exampleindent 4 + +@node ntp-keygen imbits +@subsection imbits option (-b) +@cindex ntp-keygen-imbits + +This is the ``identity modulus bits'' option. +This option takes a number argument @file{imbits}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +The number of bits in the identity modulus. The default is 256. +@node ntp-keygen certificate +@subsection certificate option (-c) +@cindex ntp-keygen-certificate + +This is the ``certificate scheme'' option. +This option takes a string argument @file{scheme}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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. +@node ntp-keygen cipher +@subsection cipher option (-C) +@cindex ntp-keygen-cipher + +This is the ``privatekey cipher'' option. +This option takes a string argument @file{cipher}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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 "@code{-C des-ede3-cbc". The openssl tool lists ciphers +available in "@code{openssl -h}" output. +@node ntp-keygen id-key +@subsection id-key option (-e) +@cindex ntp-keygen-id-key + +This is the ``write iff or gq identity keys'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +@node ntp-keygen gq-params +@subsection gq-params option (-G) +@cindex ntp-keygen-gq-params + +This is the ``generate gq parameters and keys'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +@node ntp-keygen host-key +@subsection host-key option (-H) +@cindex ntp-keygen-host-key + +This is the ``generate rsa host key'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate new host keys, obsoleting any that may exist. +@node ntp-keygen iffkey +@subsection iffkey option (-I) +@cindex ntp-keygen-iffkey + +This is the ``generate iff parameters'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +@node ntp-keygen ident +@subsection ident option (-i) +@cindex ntp-keygen-ident + +This is the ``set autokey group name'' option. +This option takes a string argument @file{group}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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 @code{-i/--ident} or +using @code{-s/--subject-name} following an '@code{@}' character, +is also a part of the self-signed host certificate's subject and +issuer names in the form @code{host@group} and should match the +'@code{crypto ident}' or '@code{server ident}' configuration in +@code{ntpd}'s configuration file. +@node ntp-keygen lifetime +@subsection lifetime option (-l) +@cindex ntp-keygen-lifetime + +This is the ``set certificate lifetime'' option. +This option takes a number argument @file{lifetime}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the certificate expiration to lifetime days from now. +@node ntp-keygen md5key +@subsection md5key option (-M) +@cindex ntp-keygen-md5key + +This is the ``generate md5 keys'' option. +Generate MD5 keys, obsoleting any that may exist. +@node ntp-keygen modulus +@subsection modulus option (-m) +@cindex ntp-keygen-modulus + +This is the ``modulus'' option. +This option takes a number argument @file{modulus}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +The number of bits in the prime modulus. The default is 512. +@node ntp-keygen pvt-cert +@subsection pvt-cert option (-P) +@cindex ntp-keygen-pvt-cert + +This is the ``generate pc private certificate'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate a private certificate. By default, the program generates +public certificates. +@node ntp-keygen password +@subsection password option (-p) +@cindex ntp-keygen-password + +This is the ``local private password'' option. +This option takes a string argument @file{passwd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Local files containing private data are encrypted with the +DES-CBC algorithm and the specified password. The same password +must be specified to the local ntpd via the "crypto pw password" +configuration command. The default password is the local +hostname. +@node ntp-keygen export-passwd +@subsection export-passwd option (-q) +@cindex ntp-keygen-export-passwd + +This is the ``export iff or gq group keys with password'' option. +This option takes a string argument @file{passwd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Export IFF or GQ identity group keys to the standard output, +encrypted with the DES-CBC algorithm and the specified password. +The same password must be specified to the remote ntpd via the +"crypto pw password" configuration command. See also the option +--id-key (-e) for unencrypted exports. +@node ntp-keygen sign-key +@subsection sign-key option (-S) +@cindex ntp-keygen-sign-key + +This is the ``generate sign key (rsa or dsa)'' option. +This option takes a string argument @file{sign}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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. +@node ntp-keygen subject-name +@subsection subject-name option (-s) +@cindex ntp-keygen-subject-name + +This is the ``set host and optionally group name'' option. +This option takes a string argument @file{host@@group}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the Autokey host name, and optionally, group name specified +following an '@code{@}' 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 @code{host@group} form for the host certificate's subject and issuer +fields. Specifying '@code{-s @group}' is allowed, and results in +leaving the host name unchanged while appending @code{@group} to the +subject and issuer fields, as with @code{-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. +@node ntp-keygen trusted-cert +@subsection trusted-cert option (-T) +@cindex ntp-keygen-trusted-cert + +This is the ``trusted certificate (tc scheme)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +@node ntp-keygen mv-params +@subsection mv-params option (-V) +@cindex ntp-keygen-mv-params + +This is the ``generate <num> mv parameters'' option. +This option takes a number argument @file{num}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +@node ntp-keygen mv-keys +@subsection mv-keys option (-v) +@cindex ntp-keygen-mv-keys + +This is the ``update <num> mv keys'' option. +This option takes a number argument @file{num}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +This option has no @samp{doc} documentation. + + +@node ntp-keygen config +@subsection presetting/configuring ntp-keygen + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTP-KEYGEN} and @code{NTP-KEYGEN_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of +the options listed above in upper case and segmented with underscores. +The @code{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. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntp-keygen} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.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: +@example +[NTP-KEYGEN] +@end example +@noindent +or by +@example +<?program ntp-keygen> +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example +<option-name> + <sub-opt>...<...>...</sub-opt> +</option-name> +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{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: + +@subsubheading 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: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntp-keygen exit status +@subsection ntp-keygen exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node ntp-keygen Usage +@subsection ntp-keygen Usage +@node ntp-keygen Notes +@subsection ntp-keygen Notes +@node ntp-keygen Bugs +@subsection ntp-keygen Bugs |