1.Dd October 13, 2003 2.Dt NTP_KEYGEN 8 3.Os 4.Sh NAME 5.Nm ntp-keygen 6.Nd generate public and private keys 7.Sh SYNOPSIS 8.Nm 9.Op Fl deGgHIMnPT 10.Op Fl c Ar RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 11.Op Fl i Ar name 12.Op Fl p Ar password 13.Op Fl S {RSA | DSA} 14.Op Fl s Ar name 15.Op Fl v Ar keys 16.Sh DESCRIPTION 17This program generates cryptographic data files used by the NTPv4 18authentication and identification schemes. It generates MD5 key files used 19in symmetric key cryptography. In addition, if the OpenSSL software 20library has been installed, it generates keys, certificate and identity 21files used in public key cryptography. These files are used for cookie 22encryption, digital signature and challenge/response identification 23algorithms compatible with the Internet standard security infrastructure. 24.Pp 25All files are in PEM-encoded printable ASCII format, so they can be 26embedded as MIME attachments in mail to other sites and certificate 27authorities. By default, files are not encrypted. The -p password option 28specifies the write password and -q password option the read password for 29previously encrypted files. The ntp-keygen program prompts for the 30password if it reads an encrypted file and the password is missing or 31incorrect. If an encrypted file is read successfully and no write password 32is specified, the read password is used as the write password by default. 33.Pp 34The ntpd configuration command crypto pw password specifies the read 35password for previously encrypted files. The daemon expires on the spot if 36the password is missing or incorrect. For convenience, if a file has been 37previously encrypted, the default read password is the name of the host 38running the program. If the previous write password is specified as the 39host name, these files can be read by that host with no explicit password. 40.Pp 41File names begin with the prefix ntpkey_ and end with the postfix 42_hostname.filestamp, where hostname is the owner name, usually the string 43returned by the Unix gethostname() routine, and filestamp is the NTP 44seconds when the file was generated, in decimal digits. This both 45guarantees uniqueness and simplifies maintenance procedures, since all 46files can be quickly removed by a rm ntpkey* command or all files 47generated at a specific time can be removed by a rm *filestamp command. To 48further reduce the risk of misconfiguration, the first two lines of a file 49contain the file name and generation date and time as comments. 50.Pp 51All files are installed by default in the keys directory /usr/local/etc, 52which is normally in a shared filesystem in NFS-mounted networks. The 53actual location of the keys directory and each file can be overridden by 54configuration commands, but this is not recommended. Normally, the files 55for each host are generated by that host and used only by that host, 56although exceptions exist as noted later on this page. 57.Pp 58Normally, files containing private values, including the host key, sign 59key and identification parameters, are permitted root read/write-only; 60while others containing public values are permitted world readable. 61Alternatively, files containing private values can be encrypted and these 62files permitted world readable, which simplifies maintenance in shared 63file systems. Since uniqueness is insured by the hostname and file name 64extensions, the files for a NFS server and dependent clients can all be 65installed in the same shared directory. 66.Pp 67The recommended practice is to keep the file name extensions when 68installing a file and to install a soft link from the generic names 69specified elsewhere on this page to the generated files. This allows new 70file generations to be activated simply by changing the link. If a link is 71present, ntpd follows it to the file name to extract the filestamp. If a 72link is not present, ntpd extracts the filestamp from the file itself. 73This allows clients to verify that the file and generation times are 74always current. The ntp-keygen program uses the same timestamp extension 75for all files generated at one time, so each generation is distinct and 76can be readily recognized in monitoring data. 77.Ss "Running the program" 78The safest way to run the ntp-keygen program is logged in directly as 79root. The recommended procedure is change to the keys directory, usually 80/ust/local/etc, then run the program. When run for the first time, or if 81all ntpkey files have been removed, the program generates a RSA host key 82file and matching RSA-MD5 certificate file, which is all that is necessary 83in many cases. The program also generates soft links from the generic 84names to the respective files. If run again, the program uses the same 85host key file, but generates a new certificate file and link. 86.Pp 87The host key is used to encrypt the cookie when required and so must be 88RSA type. By default, the host key is also the sign key used to encrypt 89signatures. When necessary, a different sign key can be specified and this 90can be either RSA or DSA type. By default, the message digest type is MD5, 91but any combination of sign key type and message digest type supported by 92the OpenSSL library can be specified, including those using the MD2, MD5, 93SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme 94specified in the certificate must be compatible with the sign key. 95Certificates using any digest algorithm are compatible with RSA sign keys; 96however, only SHA and SHA1 certificates are compatible with DSA sign keys. 97.Pp 98Private/public key files and certificates are compatible with other 99OpenSSL applications and very likely other libraries as well. Certificates 100or certificate requests derived from them should be compatible with extant 101industry practice, although some users might find the interpretation of 102X509v3 extension fields somewhat liberal. However, the identification 103parameter files, although encoded as the other files, are probably not 104compatible with anything other than Autokey. 105.Pp 106Running the program as other than root and using the Unix su command to 107assume root may not work properly, since by default the OpenSSL library 108looks for the random seed file .rnd in the user home directory. However, 109there should be only one .rnd, most conveniently in the root directory, so 110it is convenient to define the $RANDFILE environment variable used by the 111OpenSSL library as the path to /.rnd. 112.Pp 113Installing the keys as root might not work in NFS-mounted shared file 114systems, as NFS clients may not be able to write to the shared keys 115directory, even as root. In this case, NFS clients can specify the files 116in another directory such as /etc using the keysdir command. There is no 117need for one client to read the keys and certificates of other clients or 118servers, as these data are obtained automatically by the Autokey protocol. 119.Pp 120Ordinarily, cryptographic files are generated by the host that uses them, 121but it is possible for a trusted agent (TA) to generate these files for 122other hosts; however, in such cases files should always be encrypted. The 123subject name and trusted name default to the hostname of the host 124generating the files, but can be changed by command line options. It is 125convenient to designate the owner name and trusted name as the subject and 126issuer fields, respectively, of the certificate. The owner name is also 127used for the host and sign key files, while the trusted name is used for 128the identity files. 129.Ss "Trusted Hosts and Groups" 130Each cryptographic configuration involves selection of a signature scheme 131and identification scheme, called a cryptotype, as explained in the 132Authentication Options page. The default cryptotype uses RSA 133encryption, MD5 message digest and TC identification. First, configure a 134NTP subnet including one or more low-stratum trusted hosts from which all 135other hosts derive synchronization directly or indirectly. Trusted hosts 136have trusted certificates; all other hosts have nontrusted certificates. 137These hosts will automatically and dynamically build authoritative 138certificate trails to one or more trusted hosts. A trusted group is the 139set of all hosts that have, directly or indirectly, a certificate trail 140ending at a trusted host. The trail is defined by static configuration 141file entries or dynamic means described on the Automatic NTP 142Configuration Options page. 143.Pp 144On each trusted host as root, change to the keys directory. To insure a 145fresh fileset, remove all ntpkey files. Then run ntp-keygen -T to generate 146keys and a trusted certificate. On all other hosts do the same, but leave 147off the -T flag to generate keys and nontrusted certificates. When 148complete, start the NTP daemons beginning at the lowest stratum and 149working up the tree. It may take some time for Autokey to instantiate the 150certificate trails throughout the subnet, but setting up the environment 151is completely automatic. 152.Pp 153If it is necessary to use a different sign key or different 154digest/signature scheme than the default, run ntp-keygen with the -S type 155option, where type is either RSA or DSA. The most often need to do this is 156when a DSA-signed certificate is used. If it is necessary to use a 157different certificate scheme than the default, run ntp-keygen with the -c 158scheme option and selected scheme as needed. If ntp-keygen is run again 159without these options, it generates a new certificate using the same 160scheme and sign key. 161.Pp 162After setting up the environment it is advisable to update certificates 163from time to time, if only to extend the validity interval. Simply run 164ntp-keygen with the same flags as before to generate new certificates 165using existing keys. However, if the host or sign key is changed, ntpd 166should be restarted. When ntpd is restarted, it loads any new files and 167restarts the protocol. Other dependent hosts will continue as usual until 168signatures are refreshed, at which time the protocol is restarted. 169.Ss "Identity Schemes" 170As mentioned on the Autonomous Authentication page, the default TC 171identity scheme is vulnerable to a middleman attack. However, there are 172more secure identity schemes available, including PC, IFF, GQ and MV 173described on the Identification Schemes page. These schemes are based 174on a TA, one or more trusted hosts and some number of nontrusted hosts. 175Trusted hosts prove identity using values provided by the TA, while the 176remaining hosts prove identity using values provided by a trusted host and 177certificate trails that end on that host. The name of a trusted host is 178also the name of its sugroup and also the subject and issuer name on its 179trusted certificate. The TA is not necessarily a trusted host in this 180sense, but often is. 181.Pp 182In some schemes there are separate keys for servers and clients. A server 183can also be a client of another server, but a client can never be a server 184for another client. In general, trusted hosts and nontrusted hosts that 185operate as both server and client have parameter files that contain both 186server and client keys. Hosts that operate only as clients have key files 187that contain only client keys. 188.Pp 189The PC scheme supports only one trusted host in the group. On trusted host 190alice run ntp-keygen -P -p password to generate the host key file 191ntpkey_RSAkey_alice.filestamp and trusted private certificate file 192ntpkey_RSA-MD5_cert_alice.filestamp. Copy both files to all group hosts; 193they replace the files which would be generated in other schemes. On each 194host bob install a soft link from the generic name ntpkey_host_bob to the 195host key file and soft link ntpkey_cert_bob to the private certificate 196file. Note the generic links are on bob, but point to files generated by 197trusted host alice. In this scheme it is not possible to refresh either 198the keys or certificates without copying them to all other hosts in the 199group. 200.Pp 201For the IFF scheme proceed as in the TC scheme to generate keys and 202certificates for all group hosts, then for every trusted host in the 203group, generate the IFF parameter file. On trusted host alice run 204ntp-keygen -T -I -p password to produce her parameter file 205ntpkey_IFFpar_alice.filestamp, which includes both server and client keys. 206Copy this file to all group hosts that operate as both servers and clients 207and install a soft link from the generic ntpkey_iff_alice to this file. If 208there are no hosts restricted to operate only as clients, there is nothing 209further to do. As the IFF scheme is independent of keys and certificates, 210these files can be refreshed as needed. 211.Pp 212If a rogue client has the parameter file, it could masquerade as a 213legitimate server and present a middleman threat. To eliminate this 214threat, the client keys can be extracted from the parameter file and 215distributed to all restricted clients. After generating the parameter 216file, on alice run ntp-keygen -e and pipe the output to a file or mail 217program. Copy or mail this file to all restricted clients. On these 218clients install a soft link from the generic ntpkey_iff_alice to this 219file. To further protect the integrity of the keys, each file can be 220encrypted with a secret password. 221.Pp 222For the GQ scheme proceed as in the TC scheme to generate keys and 223certificates for all group hosts, then for every trusted host in the 224group, generate the IFF parameter file. On trusted host alice run 225ntp-keygen -T -G -p password to produce her parameter file 226ntpkey_GQpar_alice.filestamp, which includes both server and client keys. 227Copy this file to all group hosts and install a soft link from the generic 228ntpkey_gq_alice to this file. In addition, on each host bob install a soft 229link from generic ntpkey_gq_bob to this file. As the GQ scheme updates the 230GQ parameters file and certificate at the same time, keys and certificates 231can be regenerated as needed. 232.Pp 233For the MV scheme, proceed as in the TC scheme to generate keys and 234certificates for all group hosts. For illustration assume trish is the TA, 235alice one of several trusted hosts and bob one of her clients. On TA trish 236run ntp-keygen -V n -p password, where n is the number of revokable keys 237(typically 5) to produce the parameter file ntpkeys_MVpar_trish.filestamp 238and client key files ntpkeys_MVkeyd_trish.filestamp where d is the key 239number (0 < d < n). Copy the parameter file to alice and install a soft 240link from the generic ntpkey_mv_alice to this file. Copy one of the client 241key files to alice for later distribution to her clients. It doesn't 242matter which client key file goes to alice, since they all work the same 243way. Alice copies the client key file to all of her cliens. On client bob 244install a soft link from generic ntpkey_mvkey_bob to the client key file. 245As the MV scheme is independent of keys and certificates, these files can 246be refreshed as needed. 247.Sh OPTIONS 248.Bl -tag -width Ds 249.It Fl c Ar RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 250Select certificate message digest/signature encryption scheme. 251Note that RSA schemes must be used with a RSA sign key and DSA 252schemes must be used with a DSA sign key. The default without this 253option is RSA-MD5. 254.It Fl d 255Enable debugging. This option displays the cryptographic data 256produced in eye-friendly billboards. 257.It Fl e 258Write the IFF client keys to the standard output. This is intended 259for automatic key distribution by mail. 260.It Fl G 261Generate parameters and keys for the GQ identification scheme, 262obsoleting any that may exist. 263.It Fl g 264Generate keys for the GQ identification scheme using the existing 265GQ parameters. If the GQ parameters do not yet exist, create them 266first. 267.It Fl H 268Generate new host keys, obsoleting any that may exist. 269.It Fl I 270Generate parameters for the IFF identification scheme, obsoleting 271any that may exist. 272.It Fl i Ar name 273Set the suject name to name. This is used as the subject field in 274certificates and in the file name for host and sign keys. 275.It Fl M 276Generate MD5 keys, obsoleting any that may exist. 277.It Fl P 278Generate a private certificate. By default, the program generates 279public certificates. 280.It Fl p Ar password 281Encrypt generated files containing private data with password and 282the DES-CBC algorithm. 283.It Fl q 284Set the password for reading files to password. 285.It Fl S Ar RSA | DSA 286Generate a new sign key of the designated type, obsoleting any 287that may exist. By default, the program uses the host key as the 288sign key. 289.It Fl s Ar name 290Set the issuer name to name. This is used for the issuer field in 291certificates and in the file name for identity files. 292.It Fl T 293Generate a trusted certificate. By default, the program generates 294a non-trusted certificate. 295.It Fl v Ar nkeys 296Generate parameters and keys for the Mu-Varadharajan (MV) 297identification scheme. 298.El 299.Ss "Random Seed File" 300All cryptographically sound key generation schemes must have means to 301randomize the entropy seed used to initialize the internal pseudo-random 302number generator used by the library routines. The OpenSSL library uses a 303designated random seed file for this purpose. The file must be available 304when starting the NTP daemon and ntp-keygen program. If a site supports 305OpenSSL or its companion OpenSSH, it is very likely that means to do this 306are already available. 307.Pp 308It is important to understand that entropy must be evolved for each 309generation, for otherwise the random number sequence would be predictable. 310Various means dependent on external events, such as keystroke intervals, 311can be used to do this and some systems have built-in entropy sources. 312Suitable means are described in the OpenSSL software documentation, but 313are outside the scope of this page. 314.Pp 315The entropy seed used by the OpenSSL library is contained in a file, 316usually called .rnd, which must be available when starting the NTP daemon 317or the ntp-keygen program. The NTP daemon will first look for the file 318using the path specified by the randfile subcommand of the crypto 319configuration command. If not specified in this way, or when starting the 320ntp-keygen program, the OpenSSL library will look for the file using the 321path specified by the RANDFILE environment variable in the user home 322directory, whether root or some other user. If the RANDFILE environment 323variable is not present, the library will look for the .rnd file in the 324user home directory. If the file is not available or cannot be written, 325the daemon exits with a message to the system log and the program exits 326with a suitable error message. 327.Ss "Cryptographic Data Files" 328All other file formats begin with two lines. The first contains the file 329name, including the generated host name and filestamp. The second contains 330the datestamp in conventional Unix date format. Lines beginning with # are 331considered comments and ignored by the ntp-keygen program and ntpd daemon. 332Cryptographic values are encoded first using ASN.1 rules, then encrypted 333if necessary, and finally written PEM-encoded printable ASCII format 334preceded and followed by MIME content identifier lines. 335.Pp 336The format of the symmetric keys file is somewhat different than the other 337files in the interest of backward compatibility. Since DES-CBC is 338deprecated in NTPv4, the only key format of interest is MD5 alphanumeric 339strings. Following the herd the keys are entered one per line in the 340format 341.Dl keyno type key 342where keyno is a positive integer in the range 1-65,535, type is the 343string MD5 defining the key format and key is the key itself, which is a 344printable ASCII string 16 characters or less in length. Each character is 345chosen from the 93 printable characters in the range 0x21 through 0x7f 346excluding space and the '#' character. 347.Pp 348Note that the keys used by the ntpq and ntpdc programs are checked against 349passwords requested by the programs and entered by hand, so it is 350generally appropriate to specify these keys in human readable ASCII 351format. 352.Pp 353The ntp-keygen program generates a MD5 symmetric keys file 354ntpkey_MD5key_hostname.filestamp. Since the file contains private shared 355keys, it should be visible only to root and distributed by secure means to 356other subnet hosts. The NTP daemon loads the file ntp.keys, so ntp-keygen 357installs a soft link from this name to the generated file. Subsequently, 358similar soft links must be installed by manual or automated means on the 359other subnet hosts. While this file is not used with the Autokey Version 2 360protocol, it is needed to authenticate some remote configuration commands 361used by the ntpq and ntpdc utilities. 362.Sh SEE ALSO 363.Xr ntpdc 8 , 364.Xr ntpq 8 365.Sh BUGS 366It can take quite a while to generate the RSA public/private key 367pair and Diffie-Hellman parameters, from a few seconds on a modern 368workstation to several minutes on older machines. 369