'\" te

.\" CDDL HEADER START

.\"

.\" The contents of this file are subject to the terms of the

.\" Common Development and Distribution License (the "License").

.\" You may not use this file except in compliance with the License.

.\"

.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

.\" or http://www.opensolaris.org/os/licensing.

.\" See the License for the specific language governing permissions

.\" and limitations under the License.

.\"

.\" When distributing Covered Code, include this CDDL HEADER in each

.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.

.\" If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying

.\" information: Portions Copyright [yyyy] [name of copyright owner]

.\"

.\" CDDL HEADER END

.\"

.\" Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.

.\"

.TH "ntp-keygen" "1M" "" "" "System Administration Commands"

.SH NAME

ntp-keygen \- Generate Public and Private Keys for NTP

.SH SYNOPSIS

.LP

.n

\fB/usr/sbin/ntp-keygen\fR [\fB-deGgHIMPTv?!\fR] [\fB-i\fR \fIissuername\fR] [\fB-q\fR \fIpasswd1\fR]

[\fB-p\fR \fIpasswd2\fR] [\fB-s\fR \fIsubjectname\fR] [\fB-V\fR \fInkeys\fR] [\fB-v\fR \fImvkeys\fR]

[\fB-c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA=SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]]\fR

[\fB-S [ RSA | DSA]\fR]

.fi

.SH "OPTIONS"

.TP

.BR "-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 |"

.BR " RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]",

.BR "--certificate [...]"

.sp

Select certificate and 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 \fBRSA-MD5\fR.

.TP

.BR "-d, --debug-level"

Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.

.TP

.BR "-D \fIdebug-level\fP, --debug-level=\fIdebug-level\fP"

Enable debugging and set the debug level to \fIdebug-level\fP. 

.TP

.BR "-e, --id-key"

Generate unencrypted IFF or GQ parameters file from existing key file \fBIFFkey\fR or \fBGQkey\fR  file, respectively. The file contents are sent to the standard output.

.TP

.BR "-G, --gq-params"

Generate GQ key file \fBGQkey\fR and link \fBgqkey\fR for the Guillou-Quisquater (GQ) identity scheme.

.TP

.BR "-g, --gq-keys"

Update the GQ keys.

.TP

.BR "-H, --host-key"

Generate a new public/private host keys \fBRSAkey\fR, and link \fBhost\fR.  

.TP

.BR "-I, --iffkey"

Generate a new encrypted IFF key file \fBIFFkey\fR and link \fBiffkey\fR for the Schnorr (IFF) identity scheme.

.TP

.BR "-i \fIissuername\fP, --issuer-name=\fIissuername\fP"

Set the issuername name to \fIissuername\fR for generated identity files. This is useful only if the TA is not a group member and is generally considered not a good practice.

.TP

.BR "-M, --md5key"

Generate a new MD5 key file.

.TP

.BR "-m \fImodulus\fP, --modulus=\fImodulus\fP"

Set the modulus to \fImodulus\fR.

.TP

.BR "-P, --pvt-cert"

Generate a new private certificate used by the PC identity scheme. By default, the program generates public certificates. Note: the PC identity scheme is not recommended for new installations.

.TP

.BR "-p \fIpasswd2\fP, --pvt-passwd=\fIpasswd2\fP"

Set the password for writing encrypted files to \fIpasswd2\fR. By default, the write password is the read password.

.TP

.BR "-q \fIpasswd1\fP, --get-pvt-passwd=\fIpasswd1\fP"

Set the password for reading encrypted files to \fIpasswd1\fR. By default,  the read password is the host name.

.TP

.BR "-S [ RSA | DSA ], --sign-key=[ RSA | DSA] "

Generate a new sign key of the designated type. By default, the sign key is the host key.

.TP

.BR "-s \fIname\fP, --subject-name=\fIname\fP"

Set the host name to \fIname\fR. This is used in the host and sign key file names, as well as the subject and issuer names in the certificate. It must match the host name specified in the \fBCRYPTO\fR configuration command. 

.TP

.BR "-T, --trusted-cert"

Generate a trusted certificate. By default, the program generates nontrusted certificates.

.TP

.BR "-V \fInkeys\fP, --mv-params=\fInkeys\fP"

Generate server parameters \fBMV\fR and \fInkeys\fR client keys for the Mu-Varadharajan (MV)  identity scheme. Note: support for this option should be considered a work in progress.

.TP

.BR \-v ", " \-\-version

Output version of program and exit.

.TP

.BR "--mv-keys=\fImvkeys\fP"

.TP

.BR "-?, --help"

Print program help information.

.TP

.BR "-!, --more-help"

Extended usages information passed through a pager.

.TP

.BR \-> " \fIrcfile\fP," " \-\-save-opts" "=\fIrcfile\fP"

Save the option state to \fIrcfile\fP. 

.TP

.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts"

Load options from \fIrcfile\fP.

The \fIno-load-opts\fP form will disable the loading

of earlier RC/INI files.  \fI--no-load-opts\fP is handled early,

out of order.

.SS OPTION PRESETS

Most options may be preset by loading values from configuration file(s) and values from

environment variables named:

.nf

  \fBNTP_KEYGEN_<option-name>\fP or \fBNTP_KEYGEN\fP

.fi

.aj

The environmental presets take precedence (are processed later than)

the configuration files. The option-name should be in all capital letters.

For example, to set the --command option, you would set the NTP_KEYGEN_COMMAND environment

variable.

The users home directory and the current directory are searched for a file named .ntprc.

.SH "DESCRIPTION"

This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It generates MD5 keys used in symmetric key cryptography and generates encryption keys, certificates and identity keys used in the Autokey public key cryptography. 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.

.LP

Generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates or certificate requests generated by this or other programs should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity keys files are probably not compatible with anything other than Autokey.

.LP

Most files written by this program are encrypted using a private password. The \fB-p\fR \fIpasswd2\fR option specifies the write password and the \fB-q\fR \fIpasswd2\fR option the read password for previously encrypted files. If no read password is specified, the host name returned by the Unix \fBgethostname()\fR function is used. If no write password is specified, the read password is used as the write password.

.LP

The \fBntpd\fR configuration command \fBcrypto pw\fR \fIpasswd\fR specifies the read password for previously encrypted files. This must match the write password used by this program. For convenience, if the \fBntpd\fR password is not specified, the host name returned by the Unix \fBgethostname()\fR function is used. Thus, if files are generated by this program without password, they can be read back by \fBntpd\fR without password, but only on the same host.

.LP

All files and links are installed by default in the keys directory \fB/etc/inet\fR, which is normally in a shared filesystem in NFS-mounted networks. The location of the keys directory can be changed by the \fBkeysdir\fR configuration command. 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.

.LP

This program directs commentary and error messages to the standard error stream \fBstderr\fR and some files to the standard output stream \fBstdout\fR where they can be piped to other aplications or redirected to a file. The names used for generated files and links all begin with the string \fBntpkey\fR and include the file type, generating host and filestamp, as described in the "Cryptographic Data Files" section below

.SS "Running the Program"

The safest way to run this program is log in as root and change to the keys directory, \fB/etc/inet.\fR When run for the first time, or if all files with names beginning \fBntpkey\fR have been removed, use the \fBntp-keygen \fRcommand without arguments to generate a default RSA host key file and matching RSA-MD5 certificate file. The file names and password default to the host name as described above. If run again with the same command line, the program uses the same host key file, but generates a new certificate file.

.LP

Run the command on as many hosts as necessary. Designate one of them as the trusted host (TH) using the \fB-T\fR option on the command line and configure it to synchronize via reliable paths. THs have trusted, self-signed certificates; all other hosts have nontrusted, self-signed certificates. Then configure the nontrusted hosts to synchronize to the TH directly or indirectly. A certificate trail is created by asking the immediately ascendant host towards the root 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.

.LP

By default the name used in the subject and issuer fields in the certificate is the host name. A different name can be assigned using the \fB-s\fR \fIhost\fR option on the command line, but the name must match the host name specified by the \fBcrypto\fR configuration command.

.LP

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 file name can be assigned using the \fB-S\fR option 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.

.SS "Trusted Hosts and Secure Groups"

As described on the "Authentication Options" page at file:///usr/share/doc/ntp/authopt.html, an NTP secure group consists of one or more low-stratum THs as the root from which all other group hosts derive synchronization directly or indirectly. For authentication purposes all THs in a group must have the same host and group name; all other hosts have the same group name, but different host names. The host name and group name must match the names specified by the \fBcrypto\fR configuratrion command. Host and group names are used only for authentication purposes and have nothing to do with DNS names.

.LP

It is convenient to nominate a single TH acting as a trusted authority (TA) to generate a set of files and links that are then copied intact to all other THs in the group, most conveniently as a tar archive. This means that it doesn't matter which certificate trail ends at which TH, since the cryptographic media are the same.

.LP

To generate and install cryptographic media files, The TA uses the

.IP

.BR "ntp-keygen -q \fIpasswd1\fP -s \fIhost\fP -T"

.LP

command to specify the password, host/group name and trusted certificate. For THs the host and group names are the same and must match the host and group names specified on the \fBcrypto\fR configuration command. If run again with the same command line, the program uses the same host key file, but generates a new trusted certificate file. Group hosts other than the THs use the same command line, but with a different host name and without the \fB\fI-\fRT\fR option. On these hosts if the \fB-s\fR \fIhost\fR option is missing, the host name is the default described above.

.SS "Identity Schemes"

As described on the "Authentication Options" page, there are five identity schemes, three of which - IFF, GQ and MV - require files specific to each scheme and group. There are two files for each scheme, an encrypted keys file and a nonencrypted parameters file. THs need only the keys file; all the others need the parameters file. Other hosts expecting to support a client population also need the keys file; hosts acting only as clients need only the parameters file. Both files are generated by the TA on behalf of all servers and clients in the group.

.LP

The parameters files are public; they can be stored in a public place and sent in the clear. The keys files are encrypted with the host read password. To retrieve the keys file, a host sends a mail request to the TA including its private read password. The TA encrypts the keys file with this password and returns it as an attachment. The attachment is then copied intact to the keys directory with name given in the first line of the file, but all in lower case and with the filestamp deleted..

.LP

The TA can generate GQ keys, certificate and identity files for all TH's using the command

.IP 

.BR "ntp-keygen -q \fIpasswd1\fP -s \fIhost\fP -T -G -e >\fIparameters_file\fP"

.LP

where the the redirected \fIparameters_file\fR can be piped to a mail application or stored locally and renamed as above for later distribution. The procedure for IFF files is similar with \fB-G\fR replaced by \fB-I\fR.

.LP

The TA can generate an encrypted GQ keys file copy using the command

.IP

.BR "ntp-keygen -q \fIpasswd1\fP -p \fIpasswd2\fP -s \fIhost\fP >\fIkeys_file\fP"

.LP

where \fIpasswd1\fR is the read password for the TA, \fIpasswd2\fR is the read password for the requesting host and \fIkeys_file\fR is sent or stored as above. The program uses the keys and parameters of whatever scheme generated the keys file.

.SS "Cryptographic Data Files"

File and link names are in the form \fBntpkey_\fIkey\fR_\fIname\fR.\fIfstamp\fR\fR, where \fB\fIkey\fR\fR is the key or parameter type, \fB\fIname\fR\fR is the host or group name and \fB\fIfstamp\fR\fR is the filestamp (NTP seconds) when the file was created). By convention, key fields in generated file names include both upper and lower case alphanumeric characters, while key fields in generated link names include only lower case characters. The filestamp is not used in generated link names.

.LP

The key type is a string defining the cryptographic function. Key types include public/private keys \fBhost \fRand \fBsign\fR, certificate \fBcert\fR and several challenge/response key types. By convention, files used for challenges have a \fBpar\fR subtype, as in the IFF challenge \fBIFFpar\fR, while files for responses have a \fBkey\fR subtype, as in the GQ response \fBGQkey\fR.

.LP

All files begin with two nonencrypted lines. The first line contains the file name in the format \fBntpkey_\fIkey\fR_\fIhost\fR.\fIfstamp\fR\fR. The second line contains the datestamp in conventional Unix \fBdate\fR format. Lines beginning with \fB#\fR are ignored.

.LP

The remainder of the file contains cryptographic data encoded first using ASN.1 rules, then encrypted using the DES-CBC algorithm and given password and finally written in PEM-encoded printable ASCII text preceded and followed by MIME content identifier lines.

.LP

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 the header the keys are entered one per line in the format

.IP

\fIkeyno type key\fR

.LP

where \fIkeyno\fR is a positive integer in the range 1-65,535, \fItype\fR is the string \fBMD5\fR defining the key format and

\fIkey\fR 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 '#' character.

.LP

Note that the keys used by the \fBntpq\fR and \fBntpdc\fR 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.

.LP

The \fBntp-keygen\fR program generates a MD5 symmetric keys file \fBntpkey_MD5key_\fIhostname.filestamp\fR\fR. 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 \fBntp.keys\fR, so \fBntp-keygen\fR 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 \fBntpq\fR and \fBntpdc\fR utilities.

.SH NOTES

Source for \fBntp-keygen\fR is available on http://src.opensolaris.org.

.LP

The documentation available at /usr/share/doc/ntp is provided as is from the

\fBNTP\fR distribution and may contain information that is not applicable to

the software as provided in this partIcular distribution.

.SH SEE ALSO

.LP

\fBntpd\fR(1M), \fBntprc\fR(4), \fBattributes\fR(5)