1 @node ntp-keygen Invocation
2 @section Invoking ntp-keygen
4 @cindex Create a NTP host key
7 # EDIT THIS FILE WITH CAUTION (invoke-ntp-keygen.texi)
9 # It has been AutoGen-ed June 2, 2016 at 07:39:40 AM by AutoGen 5.18.5
10 # From the definitions ntp-keygen-opts.def
11 # and the template file agtexi-cmd.tpl
16 This program generates cryptographic data files used by the NTPv4
17 authentication and identification schemes.
18 It generates MD5 key files used in symmetric key cryptography.
19 In addition, if the OpenSSL software library has been installed,
20 it generates keys, certificate and identity files used in public key
22 These files are used for cookie encryption,
23 digital signature and challenge/response identification algorithms
24 compatible with the Internet standard security infrastructure.
26 All files are in PEM-encoded printable ASCII format,
27 so they can be embedded as MIME attachments in mail to other sites
28 and certificate authorities.
29 By default, files are not encrypted.
31 When used to generate message digest keys, the program produces a file
32 containing ten pseudo-random printable ASCII strings suitable for the
33 MD5 message digest algorithm included in the distribution.
34 If the OpenSSL library is installed, it produces an additional ten
35 hex-encoded random bit strings suitable for the SHA1 and other message
37 The message digest keys file must be distributed and stored
38 using secure means beyond the scope of NTP itself.
39 Besides the keys used for ordinary NTP associations, additional keys
40 can be defined as passwords for the
41 @code{ntpq(1ntpqmdoc)}
43 @code{ntpdc(1ntpdcmdoc)}
46 The remaining generated files are compatible with other OpenSSL
47 applications and other Public Key Infrastructure (PKI) resources.
48 Certificates generated by this program are compatible with extant
49 industry practice, although some users might find the interpretation of
50 X509v3 extension fields somewhat liberal.
51 However, the identity keys are probably not compatible with anything
54 Some files used by this program are encrypted using a private password.
57 option specifies the password for local encrypted files and the
59 option the password for encrypted files sent to remote sites.
60 If no password is specified, the host name returned by the Unix
62 function, normally the DNS name of the host is used.
68 configuration command specifies the read
69 password for previously encrypted local files.
70 This must match the local password used by this program.
71 If not specified, the host name is used.
72 Thus, if files are generated by this program without password,
73 they can be read back by
75 without password but only on the same host.
77 Normally, encrypted files for each host are generated by that host and
78 used only by that host, although exceptions exist as noted later on
80 The symmetric keys file, normally called
82 is usually installed in
84 Other files and links are usually installed in
85 @file{/usr/local/etc},
86 which is normally in a shared filesystem in
87 NFS-mounted networks and cannot be changed by shared clients.
88 The location of the keys directory can be changed by the
90 configuration command in such cases.
94 This program directs commentary and error messages to the standard
97 and remote files to the standard output stream
99 where they can be piped to other applications or redirected to files.
100 The names used for generated files and links all begin with the
103 and include the file type, generating host and filestamp,
105 @quotedblleft{}Cryptographic Data Files@quotedblright{}
107 @subsubsection Running the Program
108 To test and gain experience with Autokey concepts, log in as root and
109 change to the keys directory, usually
110 @file{/usr/local/etc}
111 When run for the first time, or if all files with names beginning with
113 have been removed, use the
115 command without arguments to generate a
116 default RSA host key and matching RSA-MD5 certificate with expiration
118 If run again without options, the program uses the
119 existing keys and parameters and generates only a new certificate with
120 new expiration date one year hence.
122 Run the command on as many hosts as necessary.
123 Designate one of them as the trusted host (TH) using
127 option and configure it to synchronize from reliable Internet servers.
128 Then configure the other hosts to synchronize to the TH directly or
130 A certificate trail is created when Autokey asks the immediately
131 ascendant host towards the TH to sign its certificate, which is then
132 provided to the immediately descendant host on request.
133 All group hosts should have acyclic certificate trails ending on the TH.
135 The host key is used to encrypt the cookie when required and so must be
137 By default, the host key is also the sign key used to encrypt
139 A different sign key can be assigned using the
141 option and this can be either RSA or DSA type.
142 By default, the signature
143 message digest type is MD5, but any combination of sign key type and
144 message digest type supported by the OpenSSL library can be specified
148 The rules say cryptographic media should be generated with proventic
149 filestamps, which means the host should already be synchronized before
151 This of course creates a chicken-and-egg problem
152 when the host is started for the first time.
153 Accordingly, the host time
154 should be set by some other means, such as eyeball-and-wristwatch, at
155 least so that the certificate lifetime is within the current year.
156 After that and when the host is synchronized to a proventic source, the
157 certificate should be re-generated.
159 Additional information on trusted groups and identity schemes is on the
160 @quotedblleft{}Autokey Public-Key Authentication@quotedblright{}
166 @code{ntpd(1ntpdmdoc)}
167 configuration command
168 @code{crypto} @code{pw} @kbd{password}
169 specifies the read password for previously encrypted files.
170 The daemon expires on the spot if the password is missing
172 For convenience, if a file has been previously encrypted,
173 the default read password is the name of the host running
175 If the previous write password is specified as the host name,
176 these files can be read by that host with no explicit password.
179 File names begin with the prefix
181 and end with the postfix
182 @kbd{_hostname.filestamp},
185 is the owner name, usually the string returned
186 by the Unix gethostname() routine, and
188 is the NTP seconds when the file was generated, in decimal digits.
189 This both guarantees uniqueness and simplifies maintenance
190 procedures, since all files can be quickly removed
192 @code{rm} @code{ntpkey*}
193 command or all files generated
194 at a specific time can be removed by a
198 To further reduce the risk of misconfiguration,
199 the first two lines of a file contain the file name
200 and generation date and time as comments.
202 All files are installed by default in the keys directory
203 @file{/usr/local/etc},
204 which is normally in a shared filesystem
205 in NFS-mounted networks.
206 The actual location of the keys directory
207 and each file can be overridden by configuration commands,
208 but this is not recommended.
209 Normally, the files for each host are generated by that host
210 and used only by that host, although exceptions exist
211 as noted later on this page.
213 Normally, files containing private values,
214 including the host key, sign key and identification parameters,
215 are permitted root read/write-only;
216 while others containing public values are permitted world readable.
217 Alternatively, files containing private values can be encrypted
218 and these files permitted world readable,
219 which simplifies maintenance in shared file systems.
220 Since uniqueness is insured by the hostname and
221 file name extensions, the files for a NFS server and
222 dependent clients can all be installed in the same shared directory.
224 The recommended practice is to keep the file name extensions
225 when installing a file and to install a soft link
226 from the generic names specified elsewhere on this page
227 to the generated files.
228 This allows new file generations to be activated simply
229 by changing the link.
230 If a link is present, ntpd follows it to the file name
231 to extract the filestamp.
232 If a link is not present,
233 @code{ntpd(1ntpdmdoc)}
234 extracts the filestamp from the file itself.
235 This allows clients to verify that the file and generation times
239 program uses the same timestamp extension for all files generated
240 at one time, so each generation is distinct and can be readily
241 recognized in monitoring data.
242 @subsubsection Running the program
243 The safest way to run the
245 program is logged in directly as root.
246 The recommended procedure is change to the keys directory,
248 @file{/usr/local/etc},
249 then run the program.
250 When run for the first time,
253 files have been removed,
254 the program generates a RSA host key file and matching RSA-MD5 certificate file,
255 which is all that is necessary in many cases.
256 The program also generates soft links from the generic names
257 to the respective files.
258 If run again, the program uses the same host key file,
259 but generates a new certificate file and link.
261 The host key is used to encrypt the cookie when required and so must be RSA type.
262 By default, the host key is also the sign key used to encrypt signatures.
263 When necessary, a different sign key can be specified and this can be
264 either RSA or DSA type.
265 By default, the message digest type is MD5, but any combination
266 of sign key type and message digest type supported by the OpenSSL library
267 can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
268 and RIPE160 message digest algorithms.
269 However, the scheme specified in the certificate must be compatible
271 Certificates using any digest algorithm are compatible with RSA sign keys;
272 however, only SHA and SHA1 certificates are compatible with DSA sign keys.
274 Private/public key files and certificates are compatible with
275 other OpenSSL applications and very likely other libraries as well.
276 Certificates or certificate requests derived from them should be compatible
277 with extant industry practice, although some users might find
278 the interpretation of X509v3 extension fields somewhat liberal.
279 However, the identification parameter files, although encoded
280 as the other files, are probably not compatible with anything other than Autokey.
282 Running the program as other than root and using the Unix
285 to assume root may not work properly, since by default the OpenSSL library
286 looks for the random seed file
288 in the user home directory.
289 However, there should be only one
292 in the root directory, so it is convenient to define the
294 environment variable used by the OpenSSL library as the path to
297 Installing the keys as root might not work in NFS-mounted
298 shared file systems, as NFS clients may not be able to write
299 to the shared keys directory, even as root.
300 In this case, NFS clients can specify the files in another
306 There is no need for one client to read the keys and certificates
307 of other clients or servers, as these data are obtained automatically
308 by the Autokey protocol.
310 Ordinarily, cryptographic files are generated by the host that uses them,
311 but it is possible for a trusted agent (TA) to generate these files
312 for other hosts; however, in such cases files should always be encrypted.
313 The subject name and trusted name default to the hostname
314 of the host generating the files, but can be changed by command line options.
315 It is convenient to designate the owner name and trusted name
316 as the subject and issuer fields, respectively, of the certificate.
317 The owner name is also used for the host and sign key files,
318 while the trusted name is used for the identity files.
321 All files are installed by default in the keys directory
322 @file{/usr/local/etc},
323 which is normally in a shared filesystem
324 in NFS-mounted networks.
325 The actual location of the keys directory
326 and each file can be overridden by configuration commands,
327 but this is not recommended.
328 Normally, the files for each host are generated by that host
329 and used only by that host, although exceptions exist
330 as noted later on this page.
332 Normally, files containing private values,
333 including the host key, sign key and identification parameters,
334 are permitted root read/write-only;
335 while others containing public values are permitted world readable.
336 Alternatively, files containing private values can be encrypted
337 and these files permitted world readable,
338 which simplifies maintenance in shared file systems.
339 Since uniqueness is insured by the hostname and
340 file name extensions, the files for a NFS server and
341 dependent clients can all be installed in the same shared directory.
343 The recommended practice is to keep the file name extensions
344 when installing a file and to install a soft link
345 from the generic names specified elsewhere on this page
346 to the generated files.
347 This allows new file generations to be activated simply
348 by changing the link.
349 If a link is present, ntpd follows it to the file name
350 to extract the filestamp.
351 If a link is not present,
352 @code{ntpd(1ntpdmdoc)}
353 extracts the filestamp from the file itself.
354 This allows clients to verify that the file and generation times
358 program uses the same timestamp extension for all files generated
359 at one time, so each generation is distinct and can be readily
360 recognized in monitoring data.
361 @subsubsection Running the program
362 The safest way to run the
364 program is logged in directly as root.
365 The recommended procedure is change to the keys directory,
367 @file{/usr/local/etc},
368 then run the program.
369 When run for the first time,
372 files have been removed,
373 the program generates a RSA host key file and matching RSA-MD5 certificate file,
374 which is all that is necessary in many cases.
375 The program also generates soft links from the generic names
376 to the respective files.
377 If run again, the program uses the same host key file,
378 but generates a new certificate file and link.
380 The host key is used to encrypt the cookie when required and so must be RSA type.
381 By default, the host key is also the sign key used to encrypt signatures.
382 When necessary, a different sign key can be specified and this can be
383 either RSA or DSA type.
384 By default, the message digest type is MD5, but any combination
385 of sign key type and message digest type supported by the OpenSSL library
386 can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
387 and RIPE160 message digest algorithms.
388 However, the scheme specified in the certificate must be compatible
390 Certificates using any digest algorithm are compatible with RSA sign keys;
391 however, only SHA and SHA1 certificates are compatible with DSA sign keys.
393 Private/public key files and certificates are compatible with
394 other OpenSSL applications and very likely other libraries as well.
395 Certificates or certificate requests derived from them should be compatible
396 with extant industry practice, although some users might find
397 the interpretation of X509v3 extension fields somewhat liberal.
398 However, the identification parameter files, although encoded
399 as the other files, are probably not compatible with anything other than Autokey.
401 Running the program as other than root and using the Unix
404 to assume root may not work properly, since by default the OpenSSL library
405 looks for the random seed file
407 in the user home directory.
408 However, there should be only one
411 in the root directory, so it is convenient to define the
413 environment variable used by the OpenSSL library as the path to
416 Installing the keys as root might not work in NFS-mounted
417 shared file systems, as NFS clients may not be able to write
418 to the shared keys directory, even as root.
419 In this case, NFS clients can specify the files in another
425 There is no need for one client to read the keys and certificates
426 of other clients or servers, as these data are obtained automatically
427 by the Autokey protocol.
429 Ordinarily, cryptographic files are generated by the host that uses them,
430 but it is possible for a trusted agent (TA) to generate these files
431 for other hosts; however, in such cases files should always be encrypted.
432 The subject name and trusted name default to the hostname
433 of the host generating the files, but can be changed by command line options.
434 It is convenient to designate the owner name and trusted name
435 as the subject and issuer fields, respectively, of the certificate.
436 The owner name is also used for the host and sign key files,
437 while the trusted name is used for the identity files.
441 s Trusted Hosts and Groups
442 Each cryptographic configuration involves selection of a signature scheme
443 and identification scheme, called a cryptotype,
445 @ref{Authentication Options}
448 The default cryptotype uses RSA encryption, MD5 message digest
449 and TC identification.
450 First, configure a NTP subnet including one or more low-stratum
451 trusted hosts from which all other hosts derive synchronization
452 directly or indirectly.
453 Trusted hosts have trusted certificates;
454 all other hosts have nontrusted certificates.
455 These hosts will automatically and dynamically build authoritative
456 certificate trails to one or more trusted hosts.
457 A trusted group is the set of all hosts that have, directly or indirectly,
458 a certificate trail ending at a trusted host.
459 The trail is defined by static configuration file entries
460 or dynamic means described on the
461 @ref{Automatic NTP Configuration Options}
465 On each trusted host as root, change to the keys directory.
466 To insure a fresh fileset, remove all
472 to generate keys and a trusted certificate.
473 On all other hosts do the same, but leave off the
475 flag to generate keys and nontrusted certificates.
476 When complete, start the NTP daemons beginning at the lowest stratum
477 and working up the tree.
478 It may take some time for Autokey to instantiate the certificate trails
479 throughout the subnet, but setting up the environment is completely automatic.
481 If it is necessary to use a different sign key or different digest/signature
482 scheme than the default, run
492 The most often need to do this is when a DSA-signed certificate is used.
493 If it is necessary to use a different certificate scheme than the default,
497 @code{-c} @kbd{scheme}
503 is run again without these options, it generates a new certificate
504 using the same scheme and sign key.
506 After setting up the environment it is advisable to update certificates
507 from time to time, if only to extend the validity interval.
510 with the same flags as before to generate new certificates
512 However, if the host or sign key is changed,
513 @code{ntpd(1ntpdmdoc)}
516 @code{ntpd(1ntpdmdoc)}
517 is restarted, it loads any new files and restarts the protocol.
518 Other dependent hosts will continue as usual until signatures are refreshed,
519 at which time the protocol is restarted.
520 @subsubsection Identity Schemes
521 As mentioned on the Autonomous Authentication page,
522 the default TC identity scheme is vulnerable to a middleman attack.
523 However, there are more secure identity schemes available,
524 including PC, IFF, GQ and MV described on the
525 "Identification Schemes"
528 @code{http://www.eecis.udel.edu/%7emills/keygen.html}).
529 These schemes are based on a TA, one or more trusted hosts
530 and some number of nontrusted hosts.
531 Trusted hosts prove identity using values provided by the TA,
532 while the remaining hosts prove identity using values provided
533 by a trusted host and certificate trails that end on that host.
534 The name of a trusted host is also the name of its sugroup
535 and also the subject and issuer name on its trusted certificate.
536 The TA is not necessarily a trusted host in this sense, but often is.
538 In some schemes there are separate keys for servers and clients.
539 A server can also be a client of another server,
540 but a client can never be a server for another client.
541 In general, trusted hosts and nontrusted hosts that operate
542 as both server and client have parameter files that contain
543 both server and client keys.
545 only as clients have key files that contain only client keys.
547 The PC scheme supports only one trusted host in the group.
548 On trusted host alice run
551 @code{-p} @kbd{password}
552 to generate the host key file
553 @file{ntpkey_RSAkey_}@kbd{alice.filestamp}
554 and trusted private certificate file
555 @file{ntpkey_RSA-MD5_cert_}@kbd{alice.filestamp}.
556 Copy both files to all group hosts;
557 they replace the files which would be generated in other schemes.
558 On each host bob install a soft link from the generic name
559 @file{ntpkey_host_}@kbd{bob}
560 to the host key file and soft link
561 @file{ntpkey_cert_}@kbd{bob}
562 to the private certificate file.
563 Note the generic links are on bob, but point to files generated
564 by trusted host alice.
565 In this scheme it is not possible to refresh
566 either the keys or certificates without copying them
567 to all other hosts in the group.
569 For the IFF scheme proceed as in the TC scheme to generate keys
570 and certificates for all group hosts, then for every trusted host in the group,
571 generate the IFF parameter file.
572 On trusted host alice run
576 @code{-p} @kbd{password}
577 to produce her parameter file
578 @file{ntpkey_IFFpar_}@kbd{alice.filestamp},
579 which includes both server and client keys.
580 Copy this file to all group hosts that operate as both servers
581 and clients and install a soft link from the generic
582 @file{ntpkey_iff_}@kbd{alice}
584 If there are no hosts restricted to operate only as clients,
585 there is nothing further to do.
586 As the IFF scheme is independent
587 of keys and certificates, these files can be refreshed as needed.
589 If a rogue client has the parameter file, it could masquerade
590 as a legitimate server and present a middleman threat.
591 To eliminate this threat, the client keys can be extracted
592 from the parameter file and distributed to all restricted clients.
593 After generating the parameter file, on alice run
596 and pipe the output to a file or mail program.
597 Copy or mail this file to all restricted clients.
598 On these clients install a soft link from the generic
599 @file{ntpkey_iff_}@kbd{alice}
601 To further protect the integrity of the keys,
602 each file can be encrypted with a secret password.
604 For the GQ scheme proceed as in the TC scheme to generate keys
605 and certificates for all group hosts, then for every trusted host
606 in the group, generate the IFF parameter file.
607 On trusted host alice run
611 @code{-p} @kbd{password}
612 to produce her parameter file
613 @file{ntpkey_GQpar_}@kbd{alice.filestamp},
614 which includes both server and client keys.
615 Copy this file to all group hosts and install a soft link
617 @file{ntpkey_gq_}@kbd{alice}
619 In addition, on each host bob install a soft link
621 @file{ntpkey_gq_}@kbd{bob}
623 As the GQ scheme updates the GQ parameters file and certificate
624 at the same time, keys and certificates can be regenerated as needed.
626 For the MV scheme, proceed as in the TC scheme to generate keys
627 and certificates for all group hosts.
628 For illustration assume trish is the TA, alice one of several trusted hosts
629 and bob one of her clients.
633 @code{-p} @kbd{password},
636 is the number of revokable keys (typically 5) to produce
638 @file{ntpkeys_MVpar_}@kbd{trish.filestamp}
640 @file{ntpkeys_MVkeyd_}@kbd{trish.filestamp}
643 is the key number (0 <
647 Copy the parameter file to alice and install a soft link
649 @file{ntpkey_mv_}@kbd{alice}
651 Copy one of the client key files to alice for later distribution
653 It doesn't matter which client key file goes to alice,
654 since they all work the same way.
655 Alice copies the client key file to all of her cliens.
656 On client bob install a soft link from generic
657 @file{ntpkey_mvkey_}@kbd{bob}
658 to the client key file.
659 As the MV scheme is independent of keys and certificates,
660 these files can be refreshed as needed.
661 @subsubsection Command Line Options
663 @item @code{-c} @kbd{scheme}
664 Select certificate message digest/signature encryption scheme.
667 can be one of the following:
668 . Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA ,
671 Note that RSA schemes must be used with a RSA sign key and DSA
672 schemes must be used with a DSA sign key.
673 The default without this option is
677 This option displays the cryptographic data produced in eye-friendly billboards.
679 Write the IFF client keys to the standard output.
680 This is intended for automatic key distribution by mail.
682 Generate parameters and keys for the GQ identification scheme,
683 obsoleting any that may exist.
685 Generate keys for the GQ identification scheme
686 using the existing GQ parameters.
687 If the GQ parameters do not yet exist, create them first.
689 Generate new host keys, obsoleting any that may exist.
691 Generate parameters for the IFF identification scheme,
692 obsoleting any that may exist.
693 @item @code{-i} @kbd{name}
694 Set the suject name to
696 This is used as the subject field in certificates
697 and in the file name for host and sign keys.
699 Generate MD5 keys, obsoleting any that may exist.
701 Generate a private certificate.
702 By default, the program generates public certificates.
703 @item @code{-p} @kbd{password}
704 Encrypt generated files containing private data with
706 and the DES-CBC algorithm.
708 Set the password for reading files to password.
709 @item @code{-S} @code{[@code{RSA} | @code{DSA}]}
710 Generate a new sign key of the designated type,
711 obsoleting any that may exist.
712 By default, the program uses the host key as the sign key.
713 @item @code{-s} @kbd{name}
714 Set the issuer name to
716 This is used for the issuer field in certificates
717 and in the file name for identity files.
719 Generate a trusted certificate.
720 By default, the program generates a non-trusted certificate.
721 @item @code{-V} @kbd{nkeys}
722 Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme.
724 @subsubsection Random Seed File
725 All cryptographically sound key generation schemes must have means
726 to randomize the entropy seed used to initialize
727 the internal pseudo-random number generator used
728 by the library routines.
729 The OpenSSL library uses a designated random seed file for this purpose.
730 The file must be available when starting the NTP daemon and
733 If a site supports OpenSSL or its companion OpenSSH,
734 it is very likely that means to do this are already available.
736 It is important to understand that entropy must be evolved
737 for each generation, for otherwise the random number sequence
738 would be predictable.
739 Various means dependent on external events, such as keystroke intervals,
740 can be used to do this and some systems have built-in entropy sources.
741 Suitable means are described in the OpenSSL software documentation,
742 but are outside the scope of this page.
744 The entropy seed used by the OpenSSL library is contained in a file,
747 which must be available when starting the NTP daemon
751 The NTP daemon will first look for the file
752 using the path specified by the
756 configuration command.
757 If not specified in this way, or when starting the
760 the OpenSSL library will look for the file using the path specified
763 environment variable in the user home directory,
764 whether root or some other user.
767 environment variable is not present,
768 the library will look for the
770 file in the user home directory.
771 If the file is not available or cannot be written,
772 the daemon exits with a message to the system log and the program
773 exits with a suitable error message.
774 @subsubsection Cryptographic Data Files
775 All other file formats begin with two lines.
776 The first contains the file name, including the generated host name
778 The second contains the datestamp in conventional Unix date format.
779 Lines beginning with # are considered comments and ignored by the
782 @code{ntpd(1ntpdmdoc)}
784 Cryptographic values are encoded first using ASN.1 rules,
785 then encrypted if necessary, and finally written PEM-encoded
786 printable ASCII format preceded and followed by MIME content identifier lines.
788 The format of the symmetric keys file is somewhat different
789 than the other files in the interest of backward compatibility.
790 Since DES-CBC is deprecated in NTPv4, the only key format of interest
791 is MD5 alphanumeric strings.
792 Following hte heard the keys are
793 entered one per line in the format
795 @kbd{keyno} @kbd{type} @kbd{key}
799 is a positive integer in the range 1-65,535,
801 is the string MD5 defining the key format and
804 which is a printable ASCII string 16 characters or less in length.
805 Each character is chosen from the 93 printable characters
806 in the range 0x21 through 0x7f excluding space and the
807 @quoteleft{}#@quoteright{}
810 Note that the keys used by the
811 @code{ntpq(1ntpqmdoc)}
813 @code{ntpdc(1ntpdcmdoc)}
815 are checked against passwords requested by the programs
816 and entered by hand, so it is generally appropriate to specify these keys
817 in human readable ASCII format.
821 program generates a MD5 symmetric keys file
822 @file{ntpkey_MD5key_}@kbd{hostname.filestamp}.
823 Since the file contains private shared keys,
824 it should be visible only to root and distributed by secure means
825 to other subnet hosts.
826 The NTP daemon loads the file
830 installs a soft link from this name to the generated file.
831 Subsequently, similar soft links must be installed by manual
832 or automated means on the other subnet hosts.
833 While this file is not used with the Autokey Version 2 protocol,
834 it is needed to authenticate some remote configuration commands
836 @code{ntpq(1ntpqmdoc)}
838 @code{ntpdc(1ntpdcmdoc)}
841 This section was generated by @strong{AutoGen},
842 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp-keygen} program.
843 This software is released under the NTP license, <http://ntp.org/license>.
846 * ntp-keygen usage:: ntp-keygen help/usage (@option{--help})
847 * ntp-keygen imbits:: imbits option (-b)
848 * ntp-keygen certificate:: certificate option (-c)
849 * ntp-keygen cipher:: cipher option (-C)
850 * ntp-keygen id-key:: id-key option (-e)
851 * ntp-keygen gq-params:: gq-params option (-G)
852 * ntp-keygen host-key:: host-key option (-H)
853 * ntp-keygen iffkey:: iffkey option (-I)
854 * ntp-keygen ident:: ident option (-i)
855 * ntp-keygen lifetime:: lifetime option (-l)
856 * ntp-keygen md5key:: md5key option (-M)
857 * ntp-keygen modulus:: modulus option (-m)
858 * ntp-keygen pvt-cert:: pvt-cert option (-P)
859 * ntp-keygen password:: password option (-p)
860 * ntp-keygen export-passwd:: export-passwd option (-q)
861 * ntp-keygen sign-key:: sign-key option (-S)
862 * ntp-keygen subject-name:: subject-name option (-s)
863 * ntp-keygen trusted-cert:: trusted-cert option (-T)
864 * ntp-keygen mv-params:: mv-params option (-V)
865 * ntp-keygen mv-keys:: mv-keys option (-v)
866 * ntp-keygen config:: presetting/configuring ntp-keygen
867 * ntp-keygen exit status:: exit status
868 * ntp-keygen Usage:: Usage
869 * ntp-keygen Notes:: Notes
870 * ntp-keygen Bugs:: Bugs
873 @node ntp-keygen usage
874 @subsection ntp-keygen help/usage (@option{--help})
875 @cindex ntp-keygen help
877 This is the automatically generated usage text for ntp-keygen.
879 The text printed is the same whether selected with the @code{help} option
880 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
881 the usage text by passing it through a pager program.
882 @code{more-help} is disabled on platforms without a working
883 @code{fork(2)} function. The @code{PAGER} environment variable is
884 used to select the program, defaulting to @file{more}. Both will exit
885 with a status code of 0.
889 ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.8p8
890 Usage: ntp-keygen [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
891 Flg Arg Option-Name Description
892 -b Num imbits identity modulus bits
893 - it must be in the range:
895 -c Str certificate certificate scheme
896 -C Str cipher privatekey cipher
897 -d no debug-level Increase debug verbosity level
898 - may appear multiple times
899 -D Num set-debug-level Set the debug verbosity level
900 - may appear multiple times
901 -e no id-key Write IFF or GQ identity keys
902 -G no gq-params Generate GQ parameters and keys
903 -H no host-key generate RSA host key
904 -I no iffkey generate IFF parameters
905 -i Str ident set Autokey group name
906 -l Num lifetime set certificate lifetime
907 -M no md5key generate MD5 keys
908 -m Num modulus modulus
909 - it must be in the range:
911 -P no pvt-cert generate PC private certificate
912 -p Str password local private password
913 -q Str export-passwd export IFF or GQ group keys with password
914 -S Str sign-key generate sign key (RSA or DSA)
915 -s Str subject-name set host and optionally group name
916 -T no trusted-cert trusted certificate (TC scheme)
917 -V Num mv-params generate <num> MV parameters
918 -v Num mv-keys update <num> MV keys
919 opt version output version information and exit
920 -? no help display extended usage information and exit
921 -! no more-help extended usage information passed thru pager
922 -> opt save-opts save the option state to a config file
923 -< Str load-opts load options from a config file
924 - disabled as '--no-load-opts'
925 - may appear multiple times
927 Options are specified by doubled hyphens and their name or by a single
928 hyphen and the flag character.
931 The following option preset mechanisms are supported:
932 - reading file $HOME/.ntprc
933 - reading file ./.ntprc
934 - examining environment variables named NTP_KEYGEN_*
936 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
940 @node ntp-keygen imbits
941 @subsection imbits option (-b)
942 @cindex ntp-keygen-imbits
944 This is the ``identity modulus bits'' option.
945 This option takes a number argument @file{imbits}.
948 This option has some usage constraints. It:
951 must be compiled in by defining @code{AUTOKEY} during the compilation.
954 The number of bits in the identity modulus. The default is 256.
955 @node ntp-keygen certificate
956 @subsection certificate option (-c)
957 @cindex ntp-keygen-certificate
959 This is the ``certificate scheme'' option.
960 This option takes a string argument @file{scheme}.
963 This option has some usage constraints. It:
966 must be compiled in by defining @code{AUTOKEY} during the compilation.
970 RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160,
971 DSA-SHA, or DSA-SHA1.
973 Select the certificate message digest/signature encryption scheme.
974 Note that RSA schemes must be used with a RSA sign key and DSA
975 schemes must be used with a DSA sign key. The default without
976 this option is RSA-MD5.
977 @node ntp-keygen cipher
978 @subsection cipher option (-C)
979 @cindex ntp-keygen-cipher
981 This is the ``privatekey cipher'' option.
982 This option takes a string argument @file{cipher}.
985 This option has some usage constraints. It:
988 must be compiled in by defining @code{AUTOKEY} during the compilation.
991 Select the cipher which is used to encrypt the files containing
992 private keys. The default is three-key triple DES in CBC mode,
993 equivalent to "@code{-C des-ede3-cbc". The openssl tool lists ciphers
994 available in "@code{openssl -h}" output.
995 @node ntp-keygen id-key
996 @subsection id-key option (-e)
997 @cindex ntp-keygen-id-key
999 This is the ``write iff or gq identity keys'' option.
1002 This option has some usage constraints. It:
1005 must be compiled in by defining @code{AUTOKEY} during the compilation.
1008 Write the IFF or GQ client keys to the standard output. This is
1009 intended for automatic key distribution by mail.
1010 @node ntp-keygen gq-params
1011 @subsection gq-params option (-G)
1012 @cindex ntp-keygen-gq-params
1014 This is the ``generate gq parameters and keys'' option.
1017 This option has some usage constraints. It:
1020 must be compiled in by defining @code{AUTOKEY} during the compilation.
1023 Generate parameters and keys for the GQ identification scheme,
1024 obsoleting any that may exist.
1025 @node ntp-keygen host-key
1026 @subsection host-key option (-H)
1027 @cindex ntp-keygen-host-key
1029 This is the ``generate rsa host key'' option.
1032 This option has some usage constraints. It:
1035 must be compiled in by defining @code{AUTOKEY} during the compilation.
1038 Generate new host keys, obsoleting any that may exist.
1039 @node ntp-keygen iffkey
1040 @subsection iffkey option (-I)
1041 @cindex ntp-keygen-iffkey
1043 This is the ``generate iff parameters'' option.
1046 This option has some usage constraints. It:
1049 must be compiled in by defining @code{AUTOKEY} during the compilation.
1052 Generate parameters for the IFF identification scheme, obsoleting
1054 @node ntp-keygen ident
1055 @subsection ident option (-i)
1056 @cindex ntp-keygen-ident
1058 This is the ``set autokey group name'' option.
1059 This option takes a string argument @file{group}.
1062 This option has some usage constraints. It:
1065 must be compiled in by defining @code{AUTOKEY} during the compilation.
1068 Set the optional Autokey group name to name. This is used in
1069 the file name of IFF, GQ, and MV client parameters files. In
1070 that role, the default is the host name if this option is not
1071 provided. The group name, if specified using @code{-i/--ident} or
1072 using @code{-s/--subject-name} following an '@code{@}' character,
1073 is also a part of the self-signed host certificate's subject and
1074 issuer names in the form @code{host@group} and should match the
1075 '@code{crypto ident}' or '@code{server ident}' configuration in
1076 @code{ntpd}'s configuration file.
1077 @node ntp-keygen lifetime
1078 @subsection lifetime option (-l)
1079 @cindex ntp-keygen-lifetime
1081 This is the ``set certificate lifetime'' option.
1082 This option takes a number argument @file{lifetime}.
1085 This option has some usage constraints. It:
1088 must be compiled in by defining @code{AUTOKEY} during the compilation.
1091 Set the certificate expiration to lifetime days from now.
1092 @node ntp-keygen md5key
1093 @subsection md5key option (-M)
1094 @cindex ntp-keygen-md5key
1096 This is the ``generate md5 keys'' option.
1097 Generate MD5 keys, obsoleting any that may exist.
1098 @node ntp-keygen modulus
1099 @subsection modulus option (-m)
1100 @cindex ntp-keygen-modulus
1102 This is the ``modulus'' option.
1103 This option takes a number argument @file{modulus}.
1106 This option has some usage constraints. It:
1109 must be compiled in by defining @code{AUTOKEY} during the compilation.
1112 The number of bits in the prime modulus. The default is 512.
1113 @node ntp-keygen pvt-cert
1114 @subsection pvt-cert option (-P)
1115 @cindex ntp-keygen-pvt-cert
1117 This is the ``generate pc private certificate'' option.
1120 This option has some usage constraints. It:
1123 must be compiled in by defining @code{AUTOKEY} during the compilation.
1126 Generate a private certificate. By default, the program generates
1127 public certificates.
1128 @node ntp-keygen password
1129 @subsection password option (-p)
1130 @cindex ntp-keygen-password
1132 This is the ``local private password'' option.
1133 This option takes a string argument @file{passwd}.
1136 This option has some usage constraints. It:
1139 must be compiled in by defining @code{AUTOKEY} during the compilation.
1142 Local files containing private data are encrypted with the
1143 DES-CBC algorithm and the specified password. The same password
1144 must be specified to the local ntpd via the "crypto pw password"
1145 configuration command. The default password is the local
1147 @node ntp-keygen export-passwd
1148 @subsection export-passwd option (-q)
1149 @cindex ntp-keygen-export-passwd
1151 This is the ``export iff or gq group keys with password'' option.
1152 This option takes a string argument @file{passwd}.
1155 This option has some usage constraints. It:
1158 must be compiled in by defining @code{AUTOKEY} during the compilation.
1161 Export IFF or GQ identity group keys to the standard output,
1162 encrypted with the DES-CBC algorithm and the specified password.
1163 The same password must be specified to the remote ntpd via the
1164 "crypto pw password" configuration command. See also the option
1165 --id-key (-e) for unencrypted exports.
1166 @node ntp-keygen sign-key
1167 @subsection sign-key option (-S)
1168 @cindex ntp-keygen-sign-key
1170 This is the ``generate sign key (rsa or dsa)'' option.
1171 This option takes a string argument @file{sign}.
1174 This option has some usage constraints. It:
1177 must be compiled in by defining @code{AUTOKEY} during the compilation.
1180 Generate a new sign key of the designated type, obsoleting any
1181 that may exist. By default, the program uses the host key as the
1183 @node ntp-keygen subject-name
1184 @subsection subject-name option (-s)
1185 @cindex ntp-keygen-subject-name
1187 This is the ``set host and optionally group name'' option.
1188 This option takes a string argument @file{host@@group}.
1191 This option has some usage constraints. It:
1194 must be compiled in by defining @code{AUTOKEY} during the compilation.
1197 Set the Autokey host name, and optionally, group name specified
1198 following an '@code{@}' character. The host name is used in the file
1199 name of generated host and signing certificates, without the
1200 group name. The host name, and if provided, group name are used
1201 in @code{host@group} form for the host certificate's subject and issuer
1202 fields. Specifying '@code{-s @group}' is allowed, and results in
1203 leaving the host name unchanged while appending @code{@group} to the
1204 subject and issuer fields, as with @code{-i group}. The group name, or
1205 if not provided, the host name are also used in the file names
1206 of IFF, GQ, and MV client parameter files.
1207 @node ntp-keygen trusted-cert
1208 @subsection trusted-cert option (-T)
1209 @cindex ntp-keygen-trusted-cert
1211 This is the ``trusted certificate (tc scheme)'' option.
1214 This option has some usage constraints. It:
1217 must be compiled in by defining @code{AUTOKEY} during the compilation.
1220 Generate a trusted certificate. By default, the program generates
1221 a non-trusted certificate.
1222 @node ntp-keygen mv-params
1223 @subsection mv-params option (-V)
1224 @cindex ntp-keygen-mv-params
1226 This is the ``generate <num> mv parameters'' option.
1227 This option takes a number argument @file{num}.
1230 This option has some usage constraints. It:
1233 must be compiled in by defining @code{AUTOKEY} during the compilation.
1236 Generate parameters and keys for the Mu-Varadharajan (MV)
1237 identification scheme.
1238 @node ntp-keygen mv-keys
1239 @subsection mv-keys option (-v)
1240 @cindex ntp-keygen-mv-keys
1242 This is the ``update <num> mv keys'' option.
1243 This option takes a number argument @file{num}.
1246 This option has some usage constraints. It:
1249 must be compiled in by defining @code{AUTOKEY} during the compilation.
1252 This option has no @samp{doc} documentation.
1255 @node ntp-keygen config
1256 @subsection presetting/configuring ntp-keygen
1258 Any option that is not marked as @i{not presettable} may be preset by
1259 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTP-KEYGEN} and @code{NTP-KEYGEN_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
1260 the options listed above in upper case and segmented with underscores.
1261 The @code{NTP-KEYGEN} variable will be tokenized and parsed like
1262 the command line. The remaining variables are tested for existence and their
1263 values are treated like option arguments.
1267 @code{libopts} will search in 2 places for configuration files:
1274 The environment variables @code{HOME}, and @code{PWD}
1275 are expanded and replaced when @file{ntp-keygen} runs.
1276 For any of these that are plain files, they are simply processed.
1277 For any that are directories, then a file named @file{.ntprc} is searched for
1278 within that directory and processed.
1280 Configuration files may be in a wide variety of formats.
1281 The basic format is an option name followed by a value (argument) on the
1282 same line. Values may be separated from the option name with a colon,
1283 equal sign or simply white space. Values may be continued across multiple
1284 lines by escaping the newline with a backslash.
1286 Multiple programs may also share the same initialization file.
1287 Common options are collected at the top, followed by program specific
1288 segments. The segments are separated by lines like:
1295 <?program ntp-keygen>
1298 Do not mix these styles within one configuration file.
1300 Compound values and carefully constructed string values may also be
1301 specified using XML syntax:
1304 <sub-opt>...<...>...</sub-opt>
1308 yielding an @code{option-name.sub-opt} string value of
1312 @code{AutoOpts} does not track suboptions. You simply note that it is a
1313 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
1314 the associated name/value pair list (see: optionFindValue).
1316 The command line options relating to configuration and/or usage help are:
1318 @subsubheading version (-)
1320 Print the program version to standard out, optionally with licensing
1321 information, then exit 0. The optional argument specifies how much licensing
1322 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
1323 Only the first letter of the argument is examined:
1327 Only print the version. This is the default.
1329 Name the copyright usage licensing terms.
1331 Print the full copyright usage licensing terms.
1334 @node ntp-keygen exit status
1335 @subsection ntp-keygen exit status
1337 One of the following exit values will be returned:
1339 @item 0 (EXIT_SUCCESS)
1340 Successful program execution.
1341 @item 1 (EXIT_FAILURE)
1342 The operation failed or the command syntax was not valid.
1343 @item 66 (EX_NOINPUT)
1344 A specified configuration file could not be loaded.
1345 @item 70 (EX_SOFTWARE)
1346 libopts had an internal operational error. Please report
1347 it to autogen-users@@lists.sourceforge.net. Thank you.
1349 @node ntp-keygen Usage
1350 @subsection ntp-keygen Usage
1351 @node ntp-keygen Notes
1352 @subsection ntp-keygen Notes
1353 @node ntp-keygen Bugs
1354 @subsection ntp-keygen Bugs