diff options
Diffstat (limited to 'util/ntp-keygen.1ntp-keygenmdoc')
| -rw-r--r-- | util/ntp-keygen.1ntp-keygenmdoc | 1071 |
1 files changed, 1071 insertions, 0 deletions
diff --git a/util/ntp-keygen.1ntp-keygenmdoc b/util/ntp-keygen.1ntp-keygenmdoc new file mode 100644 index 000000000000..a3bb102526bd --- /dev/null +++ b/util/ntp-keygen.1ntp-keygenmdoc @@ -0,0 +1,1071 @@ +.Dd December 19 2014 +.Dt NTP_KEYGEN 1ntp-keygenmdoc User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) +.\" +.\" It has been AutoGen-ed December 19, 2014 at 07:50:58 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-keygen +.Nd Create a NTP host key +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Op Ar value +.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +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. +.Pp +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 +.Xr ntpq 1ntpqmdoc +and +.Xr ntpdc 1ntpdcmdoc +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 1ntpdmdoc +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. +.Pp +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. +.Pp +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. +.Pp +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. +.Pp +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, +.Xr ntpd 1ntpdmdoc +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +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 +.Nm +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. +.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. +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. +.Pp +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. +.Pp +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 . +.Pp +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. +.Pp +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. +.Pp +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. +.Pp +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. +.Pp +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, +.Xr ntpd 1ntpdmdoc +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +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 +.Nm +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. +.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. +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. +.Pp +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. +.Pp +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 . +.Pp +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. +.Pp +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 +.Xr 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 +.Xr ntp.conf 5 . +.Pp +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm ntpkey +files. +Then run +.Nm +.Fl T +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +.Fl 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. +.Pp +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +.Nm +with the +.Fl 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 +.Nm +with the +.Fl c Ar scheme +option and selected +.Ar scheme +as needed. +f +.Nm +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.Pp +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +.Nm +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +.Xr ntpd 1ntpdmdoc +should be restarted. +When +.Xr 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. +.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. +.Pp +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. +.Pp +The PC scheme supports only one trusted host in the group. +On trusted host alice run +.Nm +.Fl P +.Fl 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. +.Pp +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 +.Nm +.Fl T +.Fl I +.Fl 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. +.Pp +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 +.Nm +.Fl 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. +.Pp +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 +.Nm +.Fl T +.Fl G +.Fl 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. +.Pp +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 +.Nm +.Fl V Ar n +.Fl 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 +.Bl -tag -width indent +.It Fl c Ar scheme +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 . +.It Fl d +Enable debugging. +This option displays the cryptographic data produced in eye\-friendly billboards. +.It Fl e +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.It Fl G +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It Fl g +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.It Fl H +Generate new host keys, obsoleting any that may exist. +.It Fl I +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.It Fl i Ar name +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. +.It Fl M +Generate MD5 keys, obsoleting any that may exist. +.It Fl P +Generate a private certificate. +By default, the program generates public certificates. +.It Fl p Ar password +Encrypt generated files containing private data with +.Ar password +and the DES\-CBC algorithm. +.It Fl q +Set the password for reading files to password. +.It Fl S Oo Cm RSA | DSA Oc +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. +.It Fl s Ar name +Set the issuer name to +.Ar name . +This is used for the issuer field in certificates +and in the file name for identity files. +.It Fl T +Generate a trusted certificate. +By default, the program generates a non\-trusted certificate. +.It Fl V Ar nkeys +Generate parameters and keys for the Mu\-Varadharajan (MV) identification scheme. +.El +.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 +.Nm +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.Pp +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. +.Pp +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 +.Nm +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 +.Nm +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 +.Nm +program and +.Xr 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. +.Pp +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. +.Pp +Note that the keys used by the +.Xr ntpq 1ntpqmdoc +and +.Xr 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. +.Pp +The +.Nm +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 +.Nm +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 +.Xr ntpq 1ntpqmdoc +and +.Xr ntpdc 1ntpdcmdoc +utilities. +.Sh "OPTIONS" +.Bl -tag +.It Fl b Ar imbits , Fl \-imbits Ns = Ns Ar imbits +identity modulus bits. +This option takes an integer number as its argument. +The value of +.Ar imbits +is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the identity modulus. The default is 256. +.It Fl c Ar scheme , Fl \-certificate Ns = Ns Ar scheme +certificate scheme. +.sp +scheme is one of +RSA\-MD2, RSA\-MD5, RSA\-SHA, RSA\-SHA1, RSA\-MDC2, RSA\-RIPEMD160, +DSA\-SHA, or DSA\-SHA1. +.sp +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. +.It Fl C Ar cipher , Fl \-cipher Ns = Ns Ar cipher +privatekey cipher. +.sp +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 "\fBopenssl \-h\fP" output. +.It Fl d , Fl \-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.It Fl e , Fl \-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.It Fl G , Fl \-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It Fl H , Fl \-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.It Fl I , Fl \-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.It Fl i Ar group , Fl \-ident Ns = Ns Ar group +set Autokey group name. +.sp +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 \fB\-i/\-\-ident\fP or +using \fB\-s/\-\-subject\-name\fP following an '\fB@\fP' character, +is also a part of the self\-signed host certificate's subject and +issuer names in the form \fBhost@group\fP and should match the +\'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in +\fBntpd\fP's configuration file. +.It Fl l Ar lifetime , Fl \-lifetime Ns = Ns Ar lifetime +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.It Fl M , Fl \-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.It Fl m Ar modulus , Fl \-modulus Ns = Ns Ar modulus +modulus. +This option takes an integer number as its argument. +The value of +.Ar modulus +is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.It Fl P , Fl \-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.It Fl p Ar passwd , Fl \-password Ns = Ns Ar passwd +local private password. +.sp +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. +.It Fl q Ar passwd , Fl \-export\-passwd Ns = Ns Ar passwd +export IFF or GQ group keys with password. +.sp +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. +.It Fl S Ar sign , Fl \-sign\-key Ns = Ns Ar sign +generate sign key (RSA or DSA). +.sp +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. +.It Fl s Ar host@group , Fl \-subject\-name Ns = Ns Ar host@group +set host and optionally group name. +.sp +Set the Autokey host name, and optionally, group name specified +following an '\fB@\fP' 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 \fBhost@group\fP form for the host certificate's subject and issuer +fields. Specifying '\fB\-s @group\fP' is allowed, and results in +leaving the host name unchanged while appending \fB@group\fP to the +subject and issuer fields, as with \fB\-i group\fP. 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. +.It Fl T , Fl \-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non\-trusted certificate. +.It Fl V Ar num , Fl \-mv\-params Ns = Ns Ar num +generate <num> MV parameters. +This option takes an integer number as its argument. +.sp +Generate parameters and keys for the Mu\-Varadharajan (MV) +identification scheme. +.It Fl v Ar num , Fl \-mv\-keys Ns = Ns Ar num +update <num> MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.It Fl \&? , Fl \-help +Display usage information and exit. +.It Fl \&! , Fl \-more\-help +Pass the extended usage information through a pager. +.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc +Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +The command will exit after updating the config file. +.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts +Load options from \fIcfgfile\fP. +The \fIno\-load\-opts\fP form will disable the loading +of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, +out of order. +.It Fl \-version Op Brq Ar v|c|n +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTP_KEYGEN_<option\-name>\fP or \fBNTP_KEYGEN\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +The +.Fl p Ar password +option specifies the write password and +.Fl q Ar password +option the read password for previously encrypted files. +The +.Nm +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. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 " (EXIT_SUCCESS)" +Successful program execution. +.It 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.It 66 " (EX_NOINPUT)" +A specified configuration file could not be loaded. +.It 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen\-users@lists.sourceforge.net. Thank you. +.El +.Sh "AUTHORS" +The University of Delaware +.Sh "COPYRIGHT" +Copyright (C) 1970\-2014 The University of Delaware all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh 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. +.Pp +Please report bugs to http://bugs.ntp.org . +.Pp +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh NOTES +Portions of this document came from FreeBSD. +.Pp +This manual page was \fIAutoGen\fP\-erated from the \fBntp\-keygen\fP +option definitions. |