System Administration Commands ntp-keygen(1M)
NAME
ntp-keygen - Generate Public and Private Keys for NTP
SYNOPSIS
/usr/sbin/ntp-keygen [-deGgHIMPTv?!] [-i issuername] [-q
passwd1] [-p passwd2] [-s subjectname] [-V nkeys] [-v
mvkeys] [-c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA=SHA1 | RSA-
MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1]] [-S [ RSA |
DSA]] OPTIONS-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 |
RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ], --
certificate [...]Select certificate and message digest/signature encryp-
tion scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSAsign key. The default without this option is RSA-MD5.
-d, --debug-level
Enable debugging. This option displays the crypto-
graphic data produced for eye-friendly billboards.
-D debug-level, --debug-level=debug-level
Enable debugging and set the debug level to debug-
level.-e, --id-key
Generate unencrypted IFF or GQ parameters file from existing key file IFFkey or GQkey file, respectively. The file contents are sent to the standard output.-G, --gq-params
Generate GQ key file GQkey and link gqkey for theGuillou-Quisquater (GQ) identity scheme.
-g, --gq-keys
Update the GQ keys.-H, --host-key
Generate a new public/private host keys RSAkey, and link host.-I, --iffkey
Generate a new encrypted IFF key file IFFkey and link iffkey for the Schnorr (IFF) identity scheme.-i issuername, --issuer-name=issuername
Set the issuername name to issuername for generated identity files. This is useful only if the TA is not a group member and is generally considered not a good SunOS 5.10 Last change: 1System Administration Commands ntp-keygen(1M)
practice.-M, --md5key
Generate a new MD5 key file.-m modulus, --modulus=modulus
Set the modulus to modulus.-P, --pvt-cert
Generate a new private certificate used by the PC iden-
tity scheme. By default, the program generates public certificates. Note: the PC identity scheme is not recommended for new installations.-p passwd2, --pvt-passwd=passwd2
Set the password for writing encrypted files to passwd2. By default, the write password is the read password.-q passwd1, --get-pvt-passwd=passwd1
Set the password for reading encrypted files to passwd1. By default, the read password is the host name.-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.-s name, --subject-name=name
Set the host name to name. 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 CRYPTO configuration command.-T, --trusted-cert
Generate a trusted certificate. By default, the program generates nontrusted certificates.-V nkeys, --mv-params=nkeys
Generate server parameters MV and nkeys client keys forthe Mu-Varadharajan (MV) identity scheme. Note: sup-
port for this option should be considered a work in progress.-v, --version
Output version of program and exit.--mv-keys=mvkeys
-?, --help
Print program help information. SunOS 5.10 Last change: 2System Administration Commands ntp-keygen(1M)
-!, --more-help
Extended usages information passed through a pager.-> rcfile, --save-opts=rcfile
Save the option state to rcfile.-< rcfile, --load-opts=rcfile, --no-load-opts
Load options from rcfile. The no-load-opts form will
disable the loading of earlier RC/INI files. --no-
load-opts is handled early, out of order.
OPTION PRESETSMost options may be preset by loading values from configura-
tion file(s) and values from environment variables named:NTP_KEYGEN_
The environmental presets take precedence (are processedor NTP_KEYGEN 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.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 theAutokey 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.Generated files are compatible with other OpenSSL applica-
tions 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, theidentity keys files are probably not compatible with any-
thing other than Autokey. Most files written by this program are encrypted using aprivate password. The -p passwd2 option specifies the write
password and the -q passwd2 option the read password for
previously encrypted files. If no read password is speci-
fied, the host name returned by the Unix gethostname() func-
tion is used. If no write password is specified, the read password is used as the write password. The ntpd configuration command crypto pw passwd specifies the read password for previously encrypted files. This must match the write password used by this program. For SunOS 5.10 Last change: 3System Administration Commands ntp-keygen(1M)
convenience, if the ntpd password is not specified, the host name returned by the Unix gethostname() function is used.Thus, if files are generated by this program without pass-
word, they can be read back by ntpd without password, but only on the same host. All files and links are installed by default in the keysdirectory /etc/inet, which is normally in a shared filesys-
tem in NFS-mounted networks. The location of the keys direc-
tory can be changed by the keysdir 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. This program directs commentary and error messages to the standard error stream stderr and some files to the standardoutput stream stdout where they can be piped to other apli-
cations or redirected to a file. The names used for gen-
erated files and links all begin with the string ntpkey and include the file type, generating host and filestamp, as described in the "Cryptographic Data Files" section below Running the Program The safest way to run this program is log in as root and change to the keys directory, /etc/inet. When run for the first time, or if all files with names beginning ntpkey havebeen removed, use the ntp-keygen command 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. Run the command on as many hosts as necessary. Designate oneof them as the trusted host (TH) using the -T option on the
command line and configure it to synchronize via reliablepaths. THs have trusted, self-signed certificates; all other
hosts have nontrusted, self-signed certificates. Then con-
figure 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 tosign its certificate, which is then provided to the immedi-
ately descendant host on request. All group hosts should have acyclic certificate trails ending on the TH. By default the name used in the subject and issuer fields in the certificate is the host name. A different name can beassigned using the -s host option on the command line, but
the name must match the host name specified by the crypto configuration command. SunOS 5.10 Last change: 4System Administration Commands ntp-keygen(1M)
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 keyfile name can be assigned using the -S option and this can
be either RSA or DSA type. By default, the message digesttype is MD5, but any combination of sign key type and mes-
sage digest type supported by the OpenSSL library can be specified. Trusted Hosts and Secure Groups As described on the "Authentication Options" page at file:///usr/share/doc/ntp/authopt.html, an NTP secure groupconsists 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 crypto configuratrion command. Host and group names are used only for authentication purposes and have nothing to do with DNS names. It is convenient to nominate a single TH acting as a trusted authority (TA) to generate a set of files and links that arethen copied intact to all other THs in the group, most con-
veniently 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. To generate and install cryptographic media files, The TA uses thentp-keygen -q passwd1 -s host -T
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 crypto 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 differenthost name and without the -T option. On these hosts if the
-s host option is missing, the host name is the default
described above. Identity Schemes As described on the "Authentication Options" page, there arefive 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 SunOS 5.10 Last change: 5System Administration Commands ntp-keygen(1M)
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. 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 withthis password and returns it as an attachment. The attach-
ment 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.. The TA can generate GQ keys, certificate and identity files for all TH's using the commandntp-keygen -q passwd1 -s host -T -G -e >parameters_file
where the the redirected parameters_file can be piped to a
mail application or stored locally and renamed as above for later distribution. The procedure for IFF files is similarwith -G replaced by -I.
The TA can generate an encrypted GQ keys file copy using the commandntp-keygen -q passwd1 -p passwd2 -s host >keys_file
where passwd1 is the read password for the TA, passwd2 isthe read password for the requesting host and keys_file is
sent or stored as above. The program uses the keys and parameters of whatever scheme generated the keys file. Cryptographic Data FilesFile and link names are in the form ntpkey_key_name.fstamp,
where key is the key or parameter type, name is the host or group name and fstamp is the filestamp (NTP seconds) whenthe file was created). By convention, key fields in gen-
erated 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.The key type is a string defining the cryptographic func-
tion. Key types include public/private keys host and sign, certificate cert and several challenge/response key types. By convention, files used for challenges have a par subtype, as in the IFF challenge IFFpar, while files for responses have a key subtype, as in the GQ response GQkey. SunOS 5.10 Last change: 6System Administration Commands ntp-keygen(1M)
All files begin with two nonencrypted lines. The first linecontains the file name in the format ntpkey_key_host.fstamp.
The second line contains the datestamp in conventional Unixdate format. Lines beginning with # are ignored.
The remainder of the file contains cryptographic data encoded first using ASN.1 rules, then encrypted using theDES-CBC algorithm and given password and finally written in
PEM-encoded printable ASCII text preceded and followed by
MIME content identifier lines. The format of the symmetric keys file is somewhat differentthan the other files in the interest of backward compatibil-
ity. Since DES-CBC is deprecated in NTPv4, the only key for-
mat of interest is MD5 alphanumeric strings. Following the header the keys are entered one per line in the format keyno type keywhere keyno is a positive integer in the range 1-65,535,
type is the string MD5 defining the key format and key isthe key itself, which is a printable ASCII string 16 charac-
ters or less in length. Each character is chosen from the 93printable characters in the range 0x21 through 0x7f exclud-
ing space and the '#' character.
Note that the keys used by the ntpq and ntpdc programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in human readable ASCII format.The ntp-keygen program generates a MD5 symmetric keys file
ntpkey_MD5key_hostname.filestamp. Since the file contains
private shared keys, it should be visible only to root and distributed by secure means to other subnet hosts. The NTPdaemon loads the file ntp.keys, so ntp-keygen installs a
soft link from this name to the generated file. Subse-
quently, similar soft links must be installed by manual or automated means on the other subnet hosts. While this file is not used with the Autokey Version 2 protocol, it is needed to authenticate some remote configuration commands used by the ntpq and ntpdc utilities. NOTESSource for ntp-keygen is available on
http://src.opensolaris.org.The documentation available at /usr/share/doc/ntp is pro-
vided as is from the NTP distribution and may contain infor-
mation that is not applicable to the software as provided in this partIcular distribution. SunOS 5.10 Last change: 7System Administration Commands ntp-keygen(1M)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| Attribute | Attribute Value || ____________________________|_____________________________|_
| Availability | service/network/ntp ||_____________________________|_____________________________|
| Interface Stability | Uncommitted ||_____________________________|_____________________________|
SEE ALSO
ntpd(1M), ntprc(4), attributes(5) SunOS 5.10 Last change: 8