9 .Nd key generation program for ntpd
13 .Op Fl c Oo Cm RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 Oc
16 .Op Fl S Oo Cm RSA | DSA Oc
21 This program generates cryptographic data files used by the NTPv4
22 authentication and identification schemes.
23 It generates MD5 key files used in symmetric key cryptography.
24 In addition, if the OpenSSL software library has been installed,
25 it generates keys, certificate and identity files used in public key
26 cryptography. These files are used for cookie encryption,
27 digital signature and challenge/response identification algorithms
28 compatible with the Internet standard security infrastructure.
30 All files are in PEM-encoded printable ASCII format,
31 so they can be embedded as MIME attachments in mail to other sites
32 and certificate authorities.
33 By default, files are not encrypted. The
35 option specifies the write password and
37 option the read password for previously encrypted files.
40 program prompts for the password if it reads an encrypted file
41 and the password is missing or incorrect.
42 If an encrypted file is read successfully and
43 no write password is specified, the read password is used
44 as the write password by default.
49 .Ic crypto pw Ar password
50 specifies the read password for previously encrypted files.
51 The daemon expires on the spot if the password is missing
53 For convenience, if a file has been previously encrypted,
54 the default read password is the name of the host running
56 If the previous write password is specified as the host name,
57 these files can be read by that host with no explicit password.
59 File names begin with the prefix
61 and end with the postfix
62 .Ar _hostname.filestamp ,
65 is the owner name, usually the string returned
66 by the Unix gethostname() routine, and
68 is the NTP seconds when the file was generated, in decimal digits.
69 This both guarantees uniqueness and simplifies maintenance
70 procedures, since all files can be quickly removed
73 command or all files generated
74 at a specific time can be removed by a
78 To further reduce the risk of misconfiguration,
79 the first two lines of a file contain the file name
80 and generation date and time as comments.
82 All files are installed by default in the keys directory
84 which is normally in a shared filesystem
85 in NFS-mounted networks. The actual location of the keys directory
86 and each file can be overridden by configuration commands,
87 but this is not recommended.
88 Normally, the files for each host are generated by that host
89 and used only by that host, although exceptions exist
90 as noted later on this page.
92 Normally, files containing private values,
93 including the host key, sign key and identification parameters,
94 are permitted root read/write-only;
95 while others containing public values are permitted world readable.
96 Alternatively, files containing private values can be encrypted
97 and these files permitted world readable,
98 which simplifies maintenance in shared file systems.
99 Since uniqueness is insured by the hostname and
100 file name extensions, the files for a NFS server and
101 dependent clients can all be installed in the same shared directory.
103 The recommended practice is to keep the file name extensions
104 when installing a file and to install a soft link
105 from the generic names specified elsewhere on this page
106 to the generated files.
107 This allows new file generations to be activated simply
108 by changing the link.
109 If a link is present, ntpd follows it to the file name
110 to extract the filestamp.
111 If a link is not present,
113 extracts the filestamp from the file itself.
114 This allows clients to verify that the file and generation times
115 are always current. The
117 program uses the same timestamp extension for all files generated
118 at one time, so each generation is distinct and can be readily
119 recognized in monitoring data.
120 .Ss Running the program
121 The safest way to run the
123 program is logged in directly as root.
124 The recommended procedure is change to the keys directory,
127 then run the program. When run for the first time,
130 files have been removed,
131 the program generates a RSA host key file and matching RSA-MD5 certificate file,
132 which is all that is necessary in many cases.
133 The program also generates soft links from the generic names
134 to the respective files.
135 If run again, the program uses the same host key file,
136 but generates a new certificate file and link.
138 The host key is used to encrypt the cookie when required and so must be RSA type.
139 By default, the host key is also the sign key used to encrypt signatures.
140 When necessary, a different sign key can be specified and this can be
141 either RSA or DSA type.
142 By default, the message digest type is MD5, but any combination
143 of sign key type and message digest type supported by the OpenSSL library
144 can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
145 and RIPE160 message digest algorithms.
146 However, the scheme specified in the certificate must be compatible
148 Certificates using any digest algorithm are compatible with RSA sign keys;
149 however, only SHA and SHA1 certificates are compatible with DSA sign keys.
151 Private/public key files and certificates are compatible with
152 other OpenSSL applications and very likely other libraries as well.
153 Certificates or certificate requests derived from them should be compatible
154 with extant industry practice, although some users might find
155 the interpretation of X509v3 extension fields somewhat liberal.
156 However, the identification parameter files, although encoded
157 as the other files, are probably not compatible with anything other than Autokey.
159 Running the program as other than root and using the Unix
162 to assume root may not work properly, since by default the OpenSSL library
163 looks for the random seed file
165 in the user home directory.
166 However, there should be only one
169 in the root directory, so it is convenient to define the
171 environment variable used by the OpenSSL library as the path to
174 Installing the keys as root might not work in NFS-mounted
175 shared file systems, as NFS clients may not be able to write
176 to the shared keys directory, even as root.
177 In this case, NFS clients can specify the files in another
183 There is no need for one client to read the keys and certificates
184 of other clients or servers, as these data are obtained automatically
185 by the Autokey protocol.
187 Ordinarily, cryptographic files are generated by the host that uses them,
188 but it is possible for a trusted agent (TA) to generate these files
189 for other hosts; however, in such cases files should always be encrypted.
190 The subject name and trusted name default to the hostname
191 of the host generating the files, but can be changed by command line options.
192 It is convenient to designate the owner name and trusted name
193 as the subject and issuer fields, respectively, of the certificate.
194 The owner name is also used for the host and sign key files,
195 while the trusted name is used for the identity files.
197 .Ss Trusted Hosts and Groups
198 Each cryptographic configuration involves selection of a signature scheme
199 and identification scheme, called a cryptotype,
201 .Sx Authentication Options
204 The default cryptotype uses RSA encryption, MD5 message digest
205 and TC identification.
206 First, configure a NTP subnet including one or more low-stratum
207 trusted hosts from which all other hosts derive synchronization
208 directly or indirectly. Trusted hosts have trusted certificates;
209 all other hosts have nontrusted certificates.
210 These hosts will automatically and dynamically build authoritative
211 certificate trails to one or more trusted hosts.
212 A trusted group is the set of all hosts that have, directly or indirectly,
213 a certificate trail ending at a trusted host.
214 The trail is defined by static configuration file entries
215 or dynamic means described on the
216 .Sx Automatic NTP Configuration Options
220 On each trusted host as root, change to the keys directory.
221 To insure a fresh fileset, remove all
227 to generate keys and a trusted certificate.
228 On all other hosts do the same, but leave off the
230 flag to generate keys and nontrusted certificates.
231 When complete, start the NTP daemons beginning at the lowest stratum
232 and working up the tree.
233 It may take some time for Autokey to instantiate the certificate trails
234 throughout the subnet, but setting up the environment is completely automatic.
236 If it is necessary to use a different sign key or different digest/signature
237 scheme than the default, run
247 The most often need to do this is when a DSA-signed certificate is used.
248 If it is necessary to use a different certificate scheme than the default,
258 is run again without these options, it generates a new certificate
259 using the same scheme and sign key.
261 After setting up the environment it is advisable to update certificates
262 from time to time, if only to extend the validity interval.
265 with the same flags as before to generate new certificates
267 However, if the host or sign key is changed,
272 is restarted, it loads any new files and restarts the protocol.
273 Other dependent hosts will continue as usual until signatures are refreshed,
274 at which time the protocol is restarted.
276 As mentioned on the Autonomous Authentication page,
277 the default TC identity scheme is vulnerable to a middleman attack.
278 However, there are more secure identity schemes available,
279 including PC, IFF, GQ and MV described on the
280 .Qq Identification Schemes
283 .Li http://www.eecis.udel.edu/%7emills/keygen.html ) .
284 These schemes are based on a TA, one or more trusted hosts
285 and some number of nontrusted hosts.
286 Trusted hosts prove identity using values provided by the TA,
287 while the remaining hosts prove identity using values provided
288 by a trusted host and certificate trails that end on that host.
289 The name of a trusted host is also the name of its sugroup
290 and also the subject and issuer name on its trusted certificate.
291 The TA is not necessarily a trusted host in this sense, but often is.
293 In some schemes there are separate keys for servers and clients.
294 A server can also be a client of another server,
295 but a client can never be a server for another client.
296 In general, trusted hosts and nontrusted hosts that operate
297 as both server and client have parameter files that contain
298 both server and client keys. Hosts that operate
299 only as clients have key files that contain only client keys.
301 The PC scheme supports only one trusted host in the group.
302 On trusted host alice run
306 to generate the host key file
307 .Pa ntpkey_RSAkey_ Ns Ar alice.filestamp
308 and trusted private certificate file
309 .Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp .
310 Copy both files to all group hosts;
311 they replace the files which would be generated in other schemes.
312 On each host bob install a soft link from the generic name
313 .Pa ntpkey_host_ Ns Ar bob
314 to the host key file and soft link
315 .Pa ntpkey_cert_ Ns Ar bob
316 to the private certificate file.
317 Note the generic links are on bob, but point to files generated
318 by trusted host alice. In this scheme it is not possible to refresh
319 either the keys or certificates without copying them
320 to all other hosts in the group.
322 For the IFF scheme proceed as in the TC scheme to generate keys
323 and certificates for all group hosts, then for every trusted host in the group,
324 generate the IFF parameter file.
325 On trusted host alice run
330 to produce her parameter file
331 .Pa ntpkey_IFFpar_ Ns Ar alice.filestamp ,
332 which includes both server and client keys.
333 Copy this file to all group hosts that operate as both servers
334 and clients and install a soft link from the generic
335 .Pa ntpkey_iff_ Ns Ar alice
337 If there are no hosts restricted to operate only as clients,
338 there is nothing further to do. As the IFF scheme is independent
339 of keys and certificates, these files can be refreshed as needed.
341 If a rogue client has the parameter file, it could masquerade
342 as a legitimate server and present a middleman threat.
343 To eliminate this threat, the client keys can be extracted
344 from the parameter file and distributed to all restricted clients.
345 After generating the parameter file, on alice run
348 and pipe the output to a file or mail program.
349 Copy or mail this file to all restricted clients.
350 On these clients install a soft link from the generic
351 .Pa ntpkey_iff_ Ns Ar alice
352 to this file. To further protect the integrity of the keys,
353 each file can be encrypted with a secret password.
355 For the GQ scheme proceed as in the TC scheme to generate keys
356 and certificates for all group hosts, then for every trusted host
357 in the group, generate the IFF parameter file.
358 On trusted host alice run
363 to produce her parameter file
364 .Pa ntpkey_GQpar_ Ns Ar alice.filestamp ,
365 which includes both server and client keys.
366 Copy this file to all group hosts and install a soft link
368 .Pa ntpkey_gq_ Ns Ar alice
370 In addition, on each host bob install a soft link
372 .Pa ntpkey_gq_ Ns Ar bob
374 As the GQ scheme updates the GQ parameters file and certificate
375 at the same time, keys and certificates can be regenerated as needed.
377 For the MV scheme, proceed as in the TC scheme to generate keys
378 and certificates for all group hosts.
379 For illustration assume trish is the TA, alice one of several trusted hosts
380 and bob one of her clients. On TA trish run
386 is the number of revokable keys (typically 5) to produce
388 .Pa ntpkeys_MVpar_ Ns Ar trish.filestamp
390 .Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp
393 is the key number (0 \&<
397 Copy the parameter file to alice and install a soft link
399 .Pa ntpkey_mv_ Ns Ar alice
401 Copy one of the client key files to alice for later distribution
403 It doesn't matter which client key file goes to alice,
404 since they all work the same way.
405 Alice copies the client key file to all of her cliens.
406 On client bob install a soft link from generic
407 .Pa ntpkey_mvkey_ Ns Ar bob
408 to the client key file.
409 As the MV scheme is independent of keys and certificates,
410 these files can be refreshed as needed.
411 .Ss Command Line Options
412 .Bl -tag -width indent
413 .It Fl c Oo Cm RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 Oc
414 Select certificate message digest/signature encryption scheme.
415 Note that RSA schemes must be used with a RSA sign key and DSA
416 schemes must be used with a DSA sign key.
417 The default without this option is
421 This option displays the cryptographic data produced in eye-friendly billboards.
423 Write the IFF client keys to the standard output.
424 This is intended for automatic key distribution by mail.
426 Generate parameters and keys for the GQ identification scheme,
427 obsoleting any that may exist.
429 Generate keys for the GQ identification scheme
430 using the existing GQ parameters.
431 If the GQ parameters do not yet exist, create them first.
433 Generate new host keys, obsoleting any that may exist.
435 Generate parameters for the IFF identification scheme,
436 obsoleting any that may exist.
438 Set the suject name to
440 This is used as the subject field in certificates
441 and in the file name for host and sign keys.
443 Generate MD5 keys, obsoleting any that may exist.
445 Generate a private certificate.
446 By default, the program generates public certificates.
448 Encrypt generated files containing private data with
450 and the DES-CBC algorithm.
452 Set the password for reading files to password.
453 .It Fl S Oo Cm RSA | DSA Oc
454 Generate a new sign key of the designated type,
455 obsoleting any that may exist.
456 By default, the program uses the host key as the sign key.
458 Set the issuer name to
460 This is used for the issuer field in certificates
461 and in the file name for identity files.
463 Generate a trusted certificate.
464 By default, the program generates a non-trusted certificate.
466 Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme.
469 All cryptographically sound key generation schemes must have means
470 to randomize the entropy seed used to initialize
471 the internal pseudo-random number generator used
472 by the library routines.
473 The OpenSSL library uses a designated random seed file for this purpose.
474 The file must be available when starting the NTP daemon and
476 program. If a site supports OpenSSL or its companion OpenSSH,
477 it is very likely that means to do this are already available.
479 It is important to understand that entropy must be evolved
480 for each generation, for otherwise the random number sequence
481 would be predictable.
482 Various means dependent on external events, such as keystroke intervals,
483 can be used to do this and some systems have built-in entropy sources.
484 Suitable means are described in the OpenSSL software documentation,
485 but are outside the scope of this page.
487 The entropy seed used by the OpenSSL library is contained in a file,
490 which must be available when starting the NTP daemon
493 program. The NTP daemon will first look for the file
494 using the path specified by the
498 configuration command.
499 If not specified in this way, or when starting the
502 the OpenSSL library will look for the file using the path specified
505 environment variable in the user home directory,
506 whether root or some other user.
509 environment variable is not present,
510 the library will look for the
512 file in the user home directory.
513 If the file is not available or cannot be written,
514 the daemon exits with a message to the system log and the program
515 exits with a suitable error message.
516 .Ss Cryptographic Data Files
517 All other file formats begin with two lines.
518 The first contains the file name, including the generated host name
520 The second contains the datestamp in conventional Unix date format.
521 Lines beginning with # are considered comments and ignored by the
526 Cryptographic values are encoded first using ASN.1 rules,
527 then encrypted if necessary, and finally written PEM-encoded
528 printable ASCII format preceded and followed by MIME content identifier lines.
530 The format of the symmetric keys file is somewhat different
531 than the other files in the interest of backward compatibility.
532 Since DES-CBC is deprecated in NTPv4, the only key format of interest
533 is MD5 alphanumeric strings. Following hte heard the keys are
534 entered one per line in the format
535 .D1 Ar keyno type key
538 is a positive integer in the range 1-65,535,
540 is the string MD5 defining the key format and
543 which is a printable ASCII string 16 characters or less in length.
544 Each character is chosen from the 93 printable characters
545 in the range 0x21 through 0x7f excluding space and the
549 Note that the keys used by the
554 are checked against passwords requested by the programs
555 and entered by hand, so it is generally appropriate to specify these keys
556 in human readable ASCII format.
560 program generates a MD5 symmetric keys file
561 .Pa ntpkey_MD5key_ Ns Ar hostname.filestamp .
562 Since the file contains private shared keys,
563 it should be visible only to root and distributed by secure means
564 to other subnet hosts.
565 The NTP daemon loads the file
569 installs a soft link from this name to the generated file.
570 Subsequently, similar soft links must be installed by manual
571 or automated means on the other subnet hosts.
572 While this file is not used with the Autokey Version 2 protocol,
573 it is needed to authenticate some remote configuration commands
580 It can take quite a while to generate some cryptographic values,
581 from one to several minutes with modern architectures
582 such as UltraSPARC and up to tens of minutes to an hour
583 with older architectures such as SPARC IPC.