diff options
Diffstat (limited to 'util/ntp-keygen.man.in')
| -rw-r--r-- | util/ntp-keygen.man.in | 1221 |
1 files changed, 1221 insertions, 0 deletions
diff --git a/util/ntp-keygen.man.in b/util/ntp-keygen.man.in new file mode 100644 index 0000000..69fcfaa --- /dev/null +++ b/util/ntp-keygen.man.in @@ -0,0 +1,1221 @@ +.de1 NOP +. it 1 an-trap +. if \\n[.$] \,\\$*\/ +.. +.ie t \ +.ds B-Font [CB] +.ds I-Font [CI] +.ds R-Font [CR] +.el \ +.ds B-Font B +.ds I-Font I +.ds R-Font R +.TH ntp-keygen @NTP_KEYGEN_MS@ "02 Dec 2014" "ntp (4.2.7p482)" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-znaynR/ag-LnaqmR) +.\" +.\" It has been AutoGen-ed December 2, 2014 at 08:58:44 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agman-cmd.tpl +.SH NAME +\f\*[B-Font]ntp-keygen\fP +\- Create a NTP host key +.SH SYNOPSIS +\f\*[B-Font]ntp-keygen\fP +.\" Mixture of short (flag) options and long options +[\f\*[B-Font]\-flags\f[]] +[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] +[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] +.sp \n(Ppu +.ne 2 + +All arguments must be options. +.sp \n(Ppu +.ne 2 + +.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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +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 +\fCntpq\fR(@NTPQ_MS@)\f[] +and +\fCntpdc\fR(@NTPDC_MS@)\f[] +utility programs. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +Some files used by this program are encrypted using a private password. +The +\f\*[B-Font]\-p\f[] +option specifies the password for local encrypted files and the +\f\*[B-Font]\-q\f[] +option the password for encrypted files sent to remote sites. +If no password is specified, the host name returned by the Unix +\fBgethostname\fR()\f[] +function, normally the DNS name of the host is used. +.sp \n(Ppu +.ne 2 + +The +\f\*[I-Font]pw\f[] +option of the +\f\*[I-Font]crypto\f[] +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 +\f\*[I-Font]ntpd\f[] +without password but only on the same host. +.sp \n(Ppu +.ne 2 + +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 +\f\*[I-Font]ntp.keys\f[], +is usually installed in +\fI/etc\f[]. +Other files and links are usually installed in +\fI/usr/local/etc\f[], +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 +\f\*[I-Font]keysdir\f[] +configuration command in such cases. +Normally, this is in +\fI/etc\f[]. +.sp \n(Ppu +.ne 2 + +This program directs commentary and error messages to the standard +error stream +\f\*[I-Font]stderr\f[] +and remote files to the standard output stream +\f\*[I-Font]stdout\f[] +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 +\f\*[I-Font]ntpkey\f[] +and include the file type, generating host and filestamp, +as described in the +\*[Lq]Cryptographic Data Files\*[Rq] +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 +\fI/usr/local/etc\f[] +When run for the first time, or if all files with names beginning with +\f\*[I-Font]ntpkey\f[] +have been removed, use the +\f\*[B-Font]ntp-keygen\fP +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. +.sp \n(Ppu +.ne 2 + +Run the command on as many hosts as necessary. +Designate one of them as the trusted host (TH) using +\f\*[B-Font]ntp-keygen\fP +with the +\f\*[B-Font]\-T\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +\f\*[B-Font]\-S\f[] +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 +\f\*[B-Font]\-c\f[] +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. +.sp \n(Ppu +.ne 2 + +Additional information on trusted groups and identity schemes is on the +\*[Lq]Autokey Public-Key Authentication\*[Rq] +page. +.sp \n(Ppu +.ne 2 + +The +\fCntpd\fR(@NTPD_MS@)\f[] +configuration command +\f\*[B-Font]crypto\f[] \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[] +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. +.sp \n(Ppu +.ne 2 + +File names begin with the prefix +\f\*[B-Font]ntpkey_\f[] +and end with the postfix +\f\*[I-Font]_hostname.filestamp\f[], +where +\f\*[I-Font]hostname\f[] +is the owner name, usually the string returned +by the Unix gethostname() routine, and +\f\*[I-Font]filestamp\f[] +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 +\f\*[B-Font]rm\f[] \f\*[B-Font]ntpkey\&*\f[] +command or all files generated +at a specific time can be removed by a +\f\*[B-Font]rm\f[] +\f\*[I-Font]\&*filestamp\f[] +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. +.sp \n(Ppu +.ne 2 + +All files are installed by default in the keys directory +\fI/usr/local/etc\f[], +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +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, +\fCntpd\fR(@NTPD_MS@)\f[] +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +\f\*[B-Font]ntp-keygen\fP +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 +\f\*[B-Font]ntp-keygen\fP +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +\fI/usr/local/etc\f[], +then run the program. +When run for the first time, +or if all +\f\*[B-Font]ntpkey\f[] +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +Running the program as other than root and using the Unix +\f\*[B-Font]su\f[] +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +\f\*[B-Font].rnd\f[] +in the user home directory. +However, there should be only one +\f\*[B-Font].rnd\f[], +most conveniently +in the root directory, so it is convenient to define the +\f\*[B-Font]$RANDFILE\f[] +environment variable used by the OpenSSL library as the path to +\f\*[B-Font]/.rnd\f[]. +.sp \n(Ppu +.ne 2 + +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 +\fI/etc\f[] +using the +\f\*[B-Font]keysdir\f[] +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +All files are installed by default in the keys directory +\fI/usr/local/etc\f[], +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +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, +\fCntpd\fR(@NTPD_MS@)\f[] +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +\f\*[B-Font]ntp-keygen\fP +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 +\f\*[B-Font]ntp-keygen\fP +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +\fI/usr/local/etc\f[], +then run the program. +When run for the first time, +or if all +\f\*[B-Font]ntpkey\f[] +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +Running the program as other than root and using the Unix +\f\*[B-Font]su\f[] +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +\f\*[B-Font].rnd\f[] +in the user home directory. +However, there should be only one +\f\*[B-Font].rnd\f[], +most conveniently +in the root directory, so it is convenient to define the +\f\*[B-Font]$RANDFILE\f[] +environment variable used by the OpenSSL library as the path to +\f\*[B-Font]/.rnd\f[]. +.sp \n(Ppu +.ne 2 + +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 +\fI/etc\f[] +using the +\f\*[B-Font]keysdir\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +\fIAuthentication\f[] \fIOptions\f[] +section of +\fCntp.conf\fR(5)\f[]. +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 +\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[] +section of +\fCntp.conf\fR(5)\f[]. +.sp \n(Ppu +.ne 2 + +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +\f\*[B-Font]ntpkey\f[] +files. +Then run +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-T\f[] +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +\f\*[B-Font]\-T\f[] +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. +.sp \n(Ppu +.ne 2 + +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +\f\*[B-Font]ntp-keygen\fP +with the +\f\*[B-Font]\-S\f[] \f\*[I-Font]type\f[] +option, where +\f\*[I-Font]type\f[] +is either +\f\*[B-Font]RSA\f[] +or +\f\*[B-Font]DSA\f[]. +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 +\f\*[B-Font]ntp-keygen\fP +with the +\f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[] +option and selected +\f\*[I-Font]scheme\f[] +as needed. +f +\f\*[B-Font]ntp-keygen\fP +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.sp \n(Ppu +.ne 2 + +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +\f\*[B-Font]ntp-keygen\fP +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +\fCntpd\fR(@NTPD_MS@)\f[] +should be restarted. +When +\fCntpd\fR(@NTPD_MS@)\f[] +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 +"Identification Schemes" +page +(maybe available at +\f[C]http://www.eecis.udel.edu/%7emills/keygen.html\f[]). +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. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +The PC scheme supports only one trusted host in the group. +On trusted host alice run +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-P\f[] +\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] +to generate the host key file +\fIntpkey_RSAkey_\f[]\f\*[I-Font]alice.filestamp\f[] +and trusted private certificate file +\fIntpkey_RSA-MD5_cert_\f[]\f\*[I-Font]alice.filestamp\f[]. +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 +\fIntpkey_host_\f[]\f\*[I-Font]bob\f[] +to the host key file and soft link +\fIntpkey_cert_\f[]\f\*[I-Font]bob\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-T\f[] +\f\*[B-Font]\-I\f[] +\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] +to produce her parameter file +\fIntpkey_IFFpar_\f[]\f\*[I-Font]alice.filestamp\f[], +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 +\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-e\f[] +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 +\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[] +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +.sp \n(Ppu +.ne 2 + +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 +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-T\f[] +\f\*[B-Font]\-G\f[] +\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] +to produce her parameter file +\fIntpkey_GQpar_\f[]\f\*[I-Font]alice.filestamp\f[], +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +\fIntpkey_gq_\f[]\f\*[I-Font]alice\f[] +to this file. +In addition, on each host bob install a soft link +from generic +\fIntpkey_gq_\f[]\f\*[I-Font]bob\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +\f\*[B-Font]ntp-keygen\fP +\f\*[B-Font]\-V\f[] \f\*[I-Font]n\f[] +\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[], +where +\f\*[I-Font]n\f[] +is the number of revokable keys (typically 5) to produce +the parameter file +\fIntpkeys_MVpar_\f[]\f\*[I-Font]trish.filestamp\f[] +and client key files +\fIntpkeys_MVkeyd_\f[]\f\*[I-Font]trish.filestamp\f[] +where +\f\*[I-Font]d\f[] +is the key number (0 \&< +\f\*[I-Font]d\f[] +\&< +\f\*[I-Font]n\f[]). +Copy the parameter file to alice and install a soft link +from the generic +\fIntpkey_mv_\f[]\f\*[I-Font]alice\f[] +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 +\fIntpkey_mvkey_\f[]\f\*[I-Font]bob\f[] +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 +.TP 7 +.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[] +Select certificate message digest/signature encryption scheme. +The +\f\*[I-Font]scheme\f[] +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +\f\*[B-Font]DSA-SHA1\f[]. +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 +\f\*[B-Font]RSA-MD5\f[]. +.TP 7 +.NOP \f\*[B-Font]\-d\f[] +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +.TP 7 +.NOP \f\*[B-Font]\-e\f[] +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.TP 7 +.NOP \f\*[B-Font]\-G\f[] +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP 7 +.NOP \f\*[B-Font]\-g\f[] +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.TP 7 +.NOP \f\*[B-Font]\-H\f[] +Generate new host keys, obsoleting any that may exist. +.TP 7 +.NOP \f\*[B-Font]\-I\f[] +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.TP 7 +.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]name\f[] +Set the suject name to +\f\*[I-Font]name\f[]. +This is used as the subject field in certificates +and in the file name for host and sign keys. +.TP 7 +.NOP \f\*[B-Font]\-M\f[] +Generate MD5 keys, obsoleting any that may exist. +.TP 7 +.NOP \f\*[B-Font]\-P\f[] +Generate a private certificate. +By default, the program generates public certificates. +.TP 7 +.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] +Encrypt generated files containing private data with +\f\*[I-Font]password\f[] +and the DES-CBC algorithm. +.TP 7 +.NOP \f\*[B-Font]\-q\f[] +Set the password for reading files to password. +.TP 7 +.NOP \f\*[B-Font]\-S\f[] [\f\*[B-Font]RSA\f[] | \f\*[B-Font]DSA\f[]] +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. +.TP 7 +.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]name\f[] +Set the issuer name to +\f\*[I-Font]name\f[]. +This is used for the issuer field in certificates +and in the file name for identity files. +.TP 7 +.NOP \f\*[B-Font]\-T\f[] +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +.TP 7 +.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]nkeys\f[] +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +.PP +.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 +\f\*[B-Font]ntp-keygen\fP +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.sp \n(Ppu +.ne 2 + +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. +.sp \n(Ppu +.ne 2 + +The entropy seed used by the OpenSSL library is contained in a file, +usually called +\f\*[B-Font].rnd\f[], +which must be available when starting the NTP daemon +or the +\f\*[B-Font]ntp-keygen\fP +program. +The NTP daemon will first look for the file +using the path specified by the +\f\*[B-Font]randfile\f[] +subcommand of the +\f\*[B-Font]crypto\f[] +configuration command. +If not specified in this way, or when starting the +\f\*[B-Font]ntp-keygen\fP +program, +the OpenSSL library will look 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 will look for the +\f\*[B-Font].rnd\f[] +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 +\f\*[B-Font]ntp-keygen\fP +program and +\fCntpd\fR(@NTPD_MS@)\f[] +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. +.sp \n(Ppu +.ne 2 + +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 +.in +4 +\f\*[I-Font]keyno\f[] \f\*[I-Font]type\f[] \f\*[I-Font]key\f[] +.in -4 +where +\f\*[I-Font]keyno\f[] +is a positive integer in the range 1-65,535, +\f\*[I-Font]type\f[] +is the string MD5 defining the key format and +\f\*[I-Font]key\f[] +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 +\[oq]#\[cq] +character. +.sp \n(Ppu +.ne 2 + +Note that the keys used by the +\fCntpq\fR(@NTPQ_MS@)\f[] +and +\fCntpdc\fR(@NTPDC_MS@)\f[] +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. +.sp \n(Ppu +.ne 2 + +The +\f\*[B-Font]ntp-keygen\fP +program generates a MD5 symmetric keys file +\fIntpkey_MD5key_\f[]\f\*[I-Font]hostname.filestamp\f[]. +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 +\fIntp.keys\f[], +so +\f\*[B-Font]ntp-keygen\fP +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 +\fCntpq\fR(@NTPQ_MS@)\f[] +and +\fCntpdc\fR(@NTPDC_MS@)\f[] +utilities. +.SH "OPTIONS" +.TP +.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]imbits\f[], \f\*[B-Font]\-\-imbits\f[]=\f\*[I-Font]imbits\f[] +identity modulus bits. +This option takes an integer number as its argument. +The value of +\f\*[I-Font]imbits\f[] +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. +.TP +.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[], \f\*[B-Font]\-\-certificate\f[]=\f\*[I-Font]scheme\f[] +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. +.TP +.NOP \f\*[B-Font]\-C\f[] \f\*[I-Font]cipher\f[], \f\*[B-Font]\-\-cipher\f[]=\f\*[I-Font]cipher\f[] +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. +.TP +.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.TP +.NOP \f\*[B-Font]\-e\f[], \f\*[B-Font]\-\-id\-key\f[] +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. +.TP +.NOP \f\*[B-Font]\-G\f[], \f\*[B-Font]\-\-gq\-params\f[] +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP +.NOP \f\*[B-Font]\-H\f[], \f\*[B-Font]\-\-host\-key\f[] +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.TP +.NOP \f\*[B-Font]\-I\f[], \f\*[B-Font]\-\-iffkey\f[] +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.TP +.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]group\f[], \f\*[B-Font]\-\-ident\f[]=\f\*[I-Font]group\f[] +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. +.TP +.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]lifetime\f[], \f\*[B-Font]\-\-lifetime\f[]=\f\*[I-Font]lifetime\f[] +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.TP +.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-md5key\f[] +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.TP +.NOP \f\*[B-Font]\-m\f[] \f\*[I-Font]modulus\f[], \f\*[B-Font]\-\-modulus\f[]=\f\*[I-Font]modulus\f[] +modulus. +This option takes an integer number as its argument. +The value of +\f\*[I-Font]modulus\f[] +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. +.TP +.NOP \f\*[B-Font]\-P\f[], \f\*[B-Font]\-\-pvt\-cert\f[] +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.TP +.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-password\f[]=\f\*[I-Font]passwd\f[] +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. +.TP +.NOP \f\*[B-Font]\-q\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-export\-passwd\f[]=\f\*[I-Font]passwd\f[] +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. +.TP +.NOP \f\*[B-Font]\-S\f[] \f\*[I-Font]sign\f[], \f\*[B-Font]\-\-sign\-key\f[]=\f\*[I-Font]sign\f[] +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. +.TP +.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]host@group\f[], \f\*[B-Font]\-\-subject\-name\f[]=\f\*[I-Font]host@group\f[] +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. +.TP +.NOP \f\*[B-Font]\-T\f[], \f\*[B-Font]\-\-trusted\-cert\f[] +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +.TP +.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-params\f[]=\f\*[I-Font]num\f[] +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. +.TP +.NOP \f\*[B-Font]\-v\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-keys\f[]=\f\*[I-Font]num\f[] +update <num> MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.TP +.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] +Display usage information and exit. +.TP +.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] +Pass the extended usage information through a pager. +.TP +.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] +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. +.TP +.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[] +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. +.TP +.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] +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. +.PP +.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 +\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] +option specifies the write password and +\f\*[B-Font]\-q\f[] \f\*[I-Font]password\f[] +option the read password for previously encrypted files. +The +\f\*[B-Font]ntp-keygen\fP +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: +.TP +.NOP 0 " (EXIT_SUCCESS)" +Successful program execution. +.TP +.NOP 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.TP +.NOP 66 " (EX_NOINPUT)" +A specified configuration file could not be loaded. +.TP +.NOP 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen-users@lists.sourceforge.net. Thank you. +.PP +.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. +.sp \n(Ppu +.ne 2 + +Please report bugs to http://bugs.ntp.org . +.sp \n(Ppu +.ne 2 + +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH NOTES +Portions of this document came from FreeBSD. +.sp \n(Ppu +.ne 2 + +This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP +option definitions. |