1 /* -*- Mode: Text -*- */
3 autogen definitions options;
7 #include autogen-version.def
9 prog-name = "ntp-keygen";
10 prog-title = "Create a NTP host key";
13 include = '#include <stdlib.h>';
21 arg-range = '256->2048';
23 descrip = "identity modulus bits";
25 The number of bits in the identity modulus. The default is 256.
35 descrip = "certificate scheme";
38 RSA-MD2, RSA-MD5, RSA-MDC2, RSA-SHA, RSA-SHA1, RSA-RIPEMD160,
41 Select the certificate signature encryption/message digest scheme.
42 Note that RSA schemes must be used with a RSA sign key and DSA
43 schemes must be used with a DSA sign key. The default without
44 this option is RSA-MD5.
54 descrip = "privatekey cipher";
56 Select the cipher which is used to encrypt the files containing
57 private keys. The default is three-key triple DES in CBC mode,
58 equivalent to "@code{-C des-ede3-cbc}". The openssl tool lists ciphers
59 available in "@code{openssl -h}" output.
63 #include debug-opt.def
69 descrip = "Write IFF or GQ identity keys";
71 Write the public parameters from the IFF or GQ client keys to
73 This is intended for automatic key distribution by email.
81 descrip = "Generate GQ parameters and keys";
83 Generate parameters and keys for the GQ identification scheme,
84 obsoleting any that may exist.
92 descrip = "generate RSA host key";
94 Generate new host keys, obsoleting any that may exist.
102 descrip = "generate IFF parameters";
104 Generate parameters for the IFF identification scheme, obsoleting
115 descrip = "set Autokey group name";
117 Set the optional Autokey group name to name. This is used in
118 the file name of IFF, GQ, and MV client parameters files. In
119 that role, the default is the host name if this option is not
120 provided. The group name, if specified using @code{-i/--ident} or
121 using @code{-s/--subject-name} following an '@code{@@}' character,
122 is also a part of the self-signed host certificate subject and
123 issuer names in the form @code{host@@group} and should match the
124 '@code{crypto ident}' or '@code{server ident}' configuration in the
125 @code{ntpd} configuration file.
135 descrip = "set certificate lifetime";
137 Set the certificate expiration to lifetime days from now.
146 arg-range = '256->2048';
148 descrip = "prime modulus";
150 The number of bits in the prime modulus. The default is 512.
157 descrip = "generate symmetric keys";
159 Generate symmetric keys, obsoleting any that may exist.
167 descrip = "generate PC private certificate";
169 Generate a private certificate. By default, the program generates
176 name = password; // was: pvt-passwd;
180 descrip = "local private password";
182 Local files containing private data are encrypted with the
183 DES-CBC algorithm and the specified password. The same password
184 must be specified to the local ntpd via the "crypto pw password"
185 configuration command. The default password is the local
192 name = export-passwd; // Was: get-pvt-passwd;
196 descrip = "export IFF or GQ group keys with password";
198 Export IFF or GQ identity group keys to the standard output,
199 encrypted with the DES-CBC algorithm and the specified password.
200 The same password must be specified to the remote ntpd via the
201 "crypto pw password" configuration command. See also the option
202 --id-key (-e) for unencrypted exports.
210 arg-name = host@group;
212 descrip = "set host and optionally group name";
214 Set the Autokey host name, and optionally, group name specified
215 following an '@code{@@}' character. The host name is used in the file
216 name of generated host and signing certificates, without the
217 group name. The host name, and if provided, group name are used
218 in @code{host@@group} form for the host certificate subject and issuer
219 fields. Specifying '@code{-s @@group}' is allowed, and results in
220 leaving the host name unchanged while appending @code{@@group} to the
221 subject and issuer fields, as with @code{-i group}. The group name, or
222 if not provided, the host name are also used in the file names
223 of IFF, GQ, and MV client parameter files.
233 descrip = "generate sign key (RSA or DSA)";
235 Generate a new sign key of the designated type, obsoleting any
236 that may exist. By default, the program uses the host key as the
245 descrip = "trusted certificate (TC scheme)";
247 Generate a trusted certificate. By default, the program generates
248 a non-trusted certificate.
258 descrip = "generate <num> MV parameters";
260 Generate parameters and keys for the Mu-Varadharajan (MV)
261 identification scheme.
271 descrip = "update <num> MV keys";
274 /* explain: Additional information whenever the usage routine is invoked */
275 explain = <<- _END_EXPLAIN
279 ds-type = 'DESCRIPTION';
281 ds-text = <<- _END_PROG_MDOC_DESCRIP
282 This program generates cryptographic data files used by the NTPv4
283 authentication and identification schemes.
284 It can generate message digest keys used in symmetric key cryptography and,
285 if the OpenSSL software library has been installed, it can generate host keys,
286 signing keys, certificates, and identity keys and parameters used in Autokey
287 public key cryptography.
288 These files are used for cookie encryption,
289 digital signature, and challenge/response identification algorithms
290 compatible with the Internet standard security infrastructure.
292 The message digest symmetric keys file is generated in a format
293 compatible with NTPv3.
294 All other files are in PEM-encoded printable ASCII format,
295 so they can be embedded as MIME attachments in email to other sites
296 and certificate authorities.
297 By default, files are not encrypted.
299 When used to generate message digest symmetric keys, the program
300 produces a file containing ten pseudo-random printable ASCII strings
301 suitable for the MD5 message digest algorithm included in the
303 If the OpenSSL library is installed, it produces an additional ten
304 hex-encoded random bit strings suitable for SHA1, AES-128-CMAC, and
305 other message digest algorithms.
306 The message digest symmetric keys file must be distributed and stored
307 using secure means beyond the scope of NTP itself.
308 Besides the keys used for ordinary NTP associations, additional keys
309 can be defined as passwords for the
315 The remaining generated files are compatible with other OpenSSL
316 applications and other Public Key Infrastructure (PKI) resources.
317 Certificates generated by this program are compatible with extant
318 industry practice, although some users might find the interpretation of
319 X509v3 extension fields somewhat liberal.
320 However, the identity keys are probably not compatible with anything
323 Some files used by this program are encrypted using a private password.
326 option specifies the read password for local encrypted files and the
328 option the write password for encrypted files sent to remote sites.
329 If no password is specified, the host name returned by the Unix
331 command, normally the DNS name of the host, is used as the the default read
332 password, for convenience.
335 program prompts for the password if it reads an encrypted file
336 and the password is missing or incorrect.
337 If an encrypted file is read successfully and
338 no write password is specified, the read password is used
339 as the write password by default.
346 configuration command specifies the read
347 password for previously encrypted local files.
348 This must match the local read password used by this program.
349 If not specified, the host name is used.
350 Thus, if files are generated by this program without an explicit password,
351 they can be read back by
353 without specifying an explicit password but only on the same host.
354 If the write password used for encryption is specified as the host name,
355 these files can be read by that host with no explicit password.
357 Normally, encrypted files for each host are generated by that host and
358 used only by that host, although exceptions exist as noted later on
360 The symmetric keys file, normally called
362 is usually installed in
364 Other files and links are usually installed in
366 which is normally in a shared filesystem in
367 NFS-mounted networks and cannot be changed by shared clients.
368 In these cases, NFS clients can specify the files in another
374 configuration file command.
376 This program directs commentary and error messages to the standard
379 and remote files to the standard output stream
381 where they can be piped to other applications or redirected to files.
382 The names used for generated files and links all begin with the
385 and include the file type, generating host and filestamp,
387 .Sx "Cryptographic Data Files"
390 .Ss Running the Program
391 The safest way to run the
393 program is logged in directly as root.
394 The recommended procedure is change to the
398 then run the program.
400 To test and gain experience with Autokey concepts, log in as root and
405 When run for the first time, or if all files with names beginning with
407 have been removed, use the
409 command without arguments to generate a default
411 host key and matching
413 certificate file with expiration date one year hence,
414 which is all that is necessary in many cases.
415 The program also generates soft links from the generic names
416 to the respective files.
417 If run again without options, the program uses the
418 existing keys and parameters and generates a new certificate file with
419 new expiration date one year hence, and soft link.
421 The host key is used to encrypt the cookie when required and so must be
424 By default, the host key is also the sign key used to encrypt signatures.
425 When necessary, a different sign key can be specified and this can be
431 By default, the message digest type is
434 of sign key type and message digest type supported by the OpenSSL library
435 can be specified, including those using the
436 .Cm AES128CMAC , MD2 , MD5 , MDC2 , SHA , SHA1
439 message digest algorithms.
440 However, the scheme specified in the certificate must be compatible
442 Certificates using any digest algorithm are compatible with
449 certificates are compatible with
453 Private/public key files and certificates are compatible with
454 other OpenSSL applications and very likely other libraries as well.
455 Certificates or certificate requests derived from them should be compatible
456 with extant industry practice, although some users might find
457 the interpretation of X509v3 extension fields somewhat liberal.
458 However, the identification parameter files, although encoded
459 as the other files, are probably not compatible with anything other than Autokey.
461 Running the program as other than root and using the Unix
464 to assume root may not work properly, since by default the OpenSSL library
465 looks for the random seed file
467 in the user home directory.
468 However, there should be only one
471 in the root directory, so it is convenient to define the
473 environment variable used by the OpenSSL library as the path to
476 Installing the keys as root might not work in NFS-mounted
477 shared file systems, as NFS clients may not be able to write
478 to the shared keys directory, even as root.
479 In this case, NFS clients can specify the files in another
485 configuration file command.
486 There is no need for one client to read the keys and certificates
487 of other clients or servers, as these data are obtained automatically
488 by the Autokey protocol.
490 Ordinarily, cryptographic files are generated by the host that uses them,
491 but it is possible for a trusted agent (TA) to generate these files
492 for other hosts; however, in such cases files should always be encrypted.
493 The subject name and trusted name default to the hostname
494 of the host generating the files, but can be changed by command line options.
495 It is convenient to designate the owner name and trusted name
496 as the subject and issuer fields, respectively, of the certificate.
497 The owner name is also used for the host and sign key files,
498 while the trusted name is used for the identity files.
500 All files are installed by default in the keys directory
502 which is normally in a shared filesystem
503 in NFS-mounted networks.
504 The actual location of the keys directory
505 and each file can be overridden by configuration commands,
506 but this is not recommended.
507 Normally, the files for each host are generated by that host
508 and used only by that host, although exceptions exist
509 as noted later on this page.
511 Normally, files containing private values,
512 including the host key, sign key and identification parameters,
513 are permitted root read/write-only;
514 while others containing public values are permitted world readable.
515 Alternatively, files containing private values can be encrypted
516 and these files permitted world readable,
517 which simplifies maintenance in shared file systems.
518 Since uniqueness is insured by the
522 file name extensions, the files for an NTP server and
523 dependent clients can all be installed in the same shared directory.
525 The recommended practice is to keep the file name extensions
526 when installing a file and to install a soft link
527 from the generic names specified elsewhere on this page
528 to the generated files.
529 This allows new file generations to be activated simply
530 by changing the link.
531 If a link is present,
533 follows it to the file name to extract the
535 If a link is not present,
539 from the file itself.
540 This allows clients to verify that the file and generation times
544 program uses the same
546 extension for all files generated
547 at one time, so each generation is distinct and can be readily
548 recognized in monitoring data.
550 Run the command on as many hosts as necessary.
551 Designate one of them as the trusted host (TH) using
555 option and configure it to synchronize from reliable Internet servers.
556 Then configure the other hosts to synchronize to the TH directly or
558 A certificate trail is created when Autokey asks the immediately
559 ascendant host towards the TH to sign its certificate, which is then
560 provided to the immediately descendant host on request.
561 All group hosts should have acyclic certificate trails ending on the TH.
563 The host key is used to encrypt the cookie when required and so must be
565 By default, the host key is also the sign key used to encrypt
567 A different sign key can be assigned using the
569 option and this can be either
574 By default, the signature
575 message digest type is
577 but any combination of sign key type and
578 message digest type supported by the OpenSSL library can be specified
583 The rules say cryptographic media should be generated with proventic
584 filestamps, which means the host should already be synchronized before
586 This of course creates a chicken-and-egg problem
587 when the host is started for the first time.
588 Accordingly, the host time
589 should be set by some other means, such as eyeball-and-wristwatch, at
590 least so that the certificate lifetime is within the current year.
591 After that and when the host is synchronized to a proventic source, the
592 certificate should be re-generated.
594 Additional information on trusted groups and identity schemes is on the
595 .Dq Autokey Public-Key Authentication
598 File names begin with the prefix
600 and end with the suffix
601 .Pa _ Ns Ar hostname . Ar filestamp ,
604 is the owner name, usually the string returned
609 is the NTP seconds when the file was generated, in decimal digits.
610 This both guarantees uniqueness and simplifies maintenance
611 procedures, since all files can be quickly removed
614 command or all files generated
615 at a specific time can be removed by a
616 .Ic rm Pa \&* Ns Ar filestamp
618 To further reduce the risk of misconfiguration,
619 the first two lines of a file contain the file name
620 and generation date and time as comments.
622 .Ss Trusted Hosts and Groups
623 Each cryptographic configuration involves selection of a signature scheme
624 and identification scheme, called a cryptotype,
626 .Sx Authentication Options
629 The default cryptotype uses
637 First, configure a NTP subnet including one or more low-stratum
638 trusted hosts from which all other hosts derive synchronization
639 directly or indirectly.
640 Trusted hosts have trusted certificates;
641 all other hosts have nontrusted certificates.
642 These hosts will automatically and dynamically build authoritative
643 certificate trails to one or more trusted hosts.
644 A trusted group is the set of all hosts that have, directly or indirectly,
645 a certificate trail ending at a trusted host.
646 The trail is defined by static configuration file entries
647 or dynamic means described on the
648 .Sx Automatic NTP Configuration Options
652 On each trusted host as root, change to the keys directory.
653 To insure a fresh fileset, remove all
659 to generate keys and a trusted certificate.
660 On all other hosts do the same, but leave off the
662 flag to generate keys and nontrusted certificates.
663 When complete, start the NTP daemons beginning at the lowest stratum
664 and working up the tree.
665 It may take some time for Autokey to instantiate the certificate trails
666 throughout the subnet, but setting up the environment is completely automatic.
668 If it is necessary to use a different sign key or different digest/signature
669 scheme than the default, run
679 The most frequent need to do this is when a
682 If it is necessary to use a different certificate scheme than the default,
692 is run again without these options, it generates a new certificate
693 using the same scheme and sign key, and soft link.
695 After setting up the environment it is advisable to update certificates
696 from time to time, if only to extend the validity interval.
699 with the same flags as before to generate new certificates
700 using existing keys, and soft links.
701 However, if the host or sign key is changed,
706 is restarted, it loads any new files and restarts the protocol.
707 Other dependent hosts will continue as usual until signatures are refreshed,
708 at which time the protocol is restarted.
711 As mentioned on the Autonomous Authentication page,
714 identity scheme is vulnerable to a middleman attack.
715 However, there are more secure identity schemes available,
720 schemes described below.
721 These schemes are based on a TA, one or more trusted hosts
722 and some number of nontrusted hosts.
723 Trusted hosts prove identity using values provided by the TA,
724 while the remaining hosts prove identity using values provided
725 by a trusted host and certificate trails that end on that host.
726 The name of a trusted host is also the name of its sugroup
727 and also the subject and issuer name on its trusted certificate.
728 The TA is not necessarily a trusted host in this sense, but often is.
730 In some schemes there are separate keys for servers and clients.
731 A server can also be a client of another server,
732 but a client can never be a server for another client.
733 In general, trusted hosts and nontrusted hosts that operate
734 as both server and client have parameter files that contain
735 both server and client keys.
737 only as clients have key files that contain only client keys.
739 The PC scheme supports only one trusted host in the group.
740 On trusted host alice run
744 to generate the host key file
745 .Pa ntpkey Ns _ Cm RSA Pa key_alice. Ar filestamp
746 and trusted private certificate file
747 .Pa ntpkey Ns _ Cm RSA-MD5 _ Pa cert_alice. Ar filestamp ,
749 Copy both files to all group hosts;
750 they replace the files which would be generated in other schemes.
753 install a soft link from the generic name
754 .Pa ntpkey_host_ Ns Ar bob
755 to the host key file and soft link
756 .Pa ntpkey_cert_ Ns Ar bob
757 to the private certificate file.
758 Note the generic links are on bob, but point to files generated
759 by trusted host alice.
760 In this scheme it is not possible to refresh
761 either the keys or certificates without copying them
762 to all other hosts in the group, and recreating the soft links.
766 scheme proceed as in the
768 scheme to generate keys
769 and certificates for all group hosts, then for every trusted host in the group,
773 On trusted host alice run
778 to produce her parameter file
779 .Pa ntpkey_IFFpar_alice. Ns Ar filestamp ,
780 which includes both server and client keys.
781 Copy this file to all group hosts that operate as both servers
782 and clients and install a soft link from the generic
785 If there are no hosts restricted to operate only as clients,
786 there is nothing further to do.
789 scheme is independent
790 of keys and certificates, these files can be refreshed as needed.
792 If a rogue client has the parameter file, it could masquerade
793 as a legitimate server and present a middleman threat.
794 To eliminate this threat, the client keys can be extracted
795 from the parameter file and distributed to all restricted clients.
796 After generating the parameter file, on alice run
799 and pipe the output to a file or email program.
800 Copy or email this file to all restricted clients.
801 On these clients install a soft link from the generic
804 To further protect the integrity of the keys,
805 each file can be encrypted with a secret password.
809 scheme proceed as in the
811 scheme to generate keys
812 and certificates for all group hosts, then for every trusted host
813 in the group, generate the
816 On trusted host alice run
821 to produce her parameter file
822 .Pa ntpkey_GQpar_alice. Ns Ar filestamp ,
823 which includes both server and client keys.
824 Copy this file to all group hosts and install a soft link
828 In addition, on each host
832 .Pa ntpkey_gq_ Ns Ar bob
838 parameters file and certificate
839 at the same time, keys and certificates can be regenerated as needed.
843 scheme, proceed as in the
845 scheme to generate keys
846 and certificates for all group hosts.
847 For illustration assume trish is the TA, alice one of several trusted hosts
848 and bob one of her clients.
855 is the number of revokable keys (typically 5) to produce
857 .Pa ntpkeys_MVpar_trish. Ns Ar filestamp
859 .Pa ntpkeys_MVkey Ns Ar d _ Pa trish. Ar filestamp
862 is the key number (0 \&<
866 Copy the parameter file to alice and install a soft link
870 Copy one of the client key files to alice for later distribution
872 It does not matter which client key file goes to alice,
873 since they all work the same way.
874 Alice copies the client key file to all of her clients.
875 On client bob install a soft link from generic
877 to the client key file.
880 scheme is independent of keys and certificates,
881 these files can be refreshed as needed.
883 .Ss Command Line Options
884 .Bl -tag -width indent
885 .It Fl b Fl -imbits Ns = Ar modulus
886 Set the number of bits in the identity modulus for generating identity keys to
889 The number of bits in the identity modulus defaults to 256, but can be set to
890 values from 256 to 2048 (32 to 256 octets).
891 Use the larger moduli with caution, as this can consume considerable computing
892 resources and increases the size of authenticated packets.
893 .It Fl c Fl -certificate Ns = Ar scheme
894 Select certificate signature encryption/message digest scheme.
897 can be one of the following:
898 .Cm RSA-MD2 , RSA-MD5 , RSA-MDC2 , RSA-SHA , RSA-SHA1 , RSA-RIPEMD160 , DSA-SHA ,
903 schemes must be used with an
907 schemes must be used with a
910 The default without this option is
912 If compatibility with FIPS 140-2 is required, either the
917 .It Fl C Fl -cipher Ns = Ar cipher
918 Select the OpenSSL cipher to encrypt the files containing private keys.
919 The default without this option is three-key triple DES in CBC mode,
923 command provided with OpenSSL displays available ciphers.
924 .It Fl d Fl -debug-level
925 Increase debugging verbosity level.
926 This option displays the cryptographic data produced in eye-friendly billboards.
927 .It Fl D Fl -set-debug-level Ns = Ar level
928 Set the debugging verbosity to
930 This option displays the cryptographic data produced in eye-friendly billboards.
936 public parameters from the
938 client keys file previously specified
939 as unencrypted data to the standard output stream
941 This is intended for automatic key distribution by email.
942 .It Fl G Fl -gq-params
943 Generate a new encrypted
945 parameters and key file for the Guillou-Quisquater (GQ) identity scheme.
946 This option is mutually exclusive with the
951 .It Fl H Fl -host-key
952 Generate a new encrypted
954 public/private host key file.
956 Generate a new encrypted
958 key file for the Schnorr (IFF) identity scheme.
959 This option is mutually exclusive with the
964 .It Fl i Fl -ident Ns = Ar group
965 Set the optional Autokey group name to
967 This is used in the identity scheme parameter file names of
971 client parameters files.
972 In that role, the default is the host name if no group is provided.
973 The group name, if specified using
979 character, is also used in certificate subject and issuer names in the form
981 and should match the group specified via
985 in the ntpd configuration file.
986 .It Fl l Fl -lifetime Ns = Ar days
987 Set the lifetime for certificate expiration to
989 The default lifetime is one year (365 days).
990 .It Fl m Fl -modulus Ns = Ar bits
991 Set the number of bits in the prime modulus for generating files to
993 The modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets).
994 Use the larger moduli with caution, as this can consume considerable computing
995 resources and increases the size of authenticated packets.
997 Generate a new symmetric keys file containing 10
999 keys, and if OpenSSL is available, 10
1004 key is a string of 20 random printable ASCII characters, while a
1006 key is a string of 40 random hex digits.
1007 The file can be edited using a text editor to change the key type or key content.
1008 This option is mutually exclusive with all other options.
1009 .It Fl p Fl -password Ns = Ar passwd
1010 Set the password for reading and writing encrypted files to
1012 These include the host, sign and identify key files.
1013 By default, the password is the string returned by the Unix
1016 .It Fl P Fl -pvt-cert
1017 Generate a new private certificate used by the
1020 By default, the program generates public certificates.
1021 Note: the PC identity scheme is not recommended for new installations.
1022 .It Fl q Fl -export-passwd Ns = Ar passwd
1023 Set the password for writing encrypted
1025 identity files redirected to
1029 In effect, these files are decrypted with the
1031 password, then encrypted with the
1034 By default, the password is the string returned by the Unix
1037 .It Fl s Fl -subject-key Ns = Ar Oo host Oc Op @@ Ar group
1038 Specify the Autokey host name, where
1040 is the optional host name and
1042 is the optional group name.
1043 The host name, and if provided, group name are used in
1045 form as certificate subject and issuer.
1048 is allowed, and results in leaving the host name unchanged, as with
1050 The group name, or if no group is provided, the host name are also used in the
1055 identity scheme client parameter files.
1058 is not specified, the default host name is the string returned by the Unix
1061 .It Fl S Fl -sign-key Ns = Op Cm RSA | DSA
1062 Generate a new encrypted public/private sign key file of the specified type.
1063 By default, the sign key is the host key and has the same type.
1064 If compatibility with FIPS 140-2 is required, the sign key type must be
1066 .It Fl T Fl -trusted-cert
1067 Generate a trusted certificate.
1068 By default, the program generates a non-trusted certificate.
1069 .It Fl V Fl -mv-params Ar nkeys
1072 encrypted server keys and parameters for the Mu-Varadharajan (MV)
1074 This option is mutually exclusive with the
1079 Note: support for this option should be considered a work in progress.
1082 .Ss Random Seed File
1083 All cryptographically sound key generation schemes must have means
1084 to randomize the entropy seed used to initialize
1085 the internal pseudo-random number generator used
1086 by the library routines.
1087 The OpenSSL library uses a designated random seed file for this purpose.
1088 The file must be available when starting the NTP daemon and
1091 If a site supports OpenSSL or its companion OpenSSH,
1092 it is very likely that means to do this are already available.
1094 It is important to understand that entropy must be evolved
1095 for each generation, for otherwise the random number sequence
1096 would be predictable.
1097 Various means dependent on external events, such as keystroke intervals,
1098 can be used to do this and some systems have built-in entropy sources.
1099 Suitable means are described in the OpenSSL software documentation,
1100 but are outside the scope of this page.
1102 The entropy seed used by the OpenSSL library is contained in a file,
1105 which must be available when starting the NTP daemon
1109 The NTP daemon will first look for the file
1110 using the path specified by the
1114 configuration command.
1115 If not specified in this way, or when starting the
1118 the OpenSSL library will look for the file using the path specified
1121 environment variable in the user home directory,
1122 whether root or some other user.
1125 environment variable is not present,
1126 the library will look for the
1128 file in the user home directory.
1133 daemon must run as root, the logical place to put this file is in
1137 If the file is not available or cannot be written,
1138 the daemon exits with a message to the system log and the program
1139 exits with a suitable error message.
1141 .Ss Cryptographic Data Files
1142 All file formats begin with two nonencrypted lines.
1143 The first line contains the file name, including the generated host name
1144 and filestamp, in the format
1145 .Pa ntpkey_ Ns Ar key _ Ar name . Ar filestamp ,
1148 is the key or parameter type,
1150 is the host or group name and
1152 is the filestamp (NTP seconds) when the file was created.
1155 names in generated file names include both upper and lower case
1158 names in generated link names include only lower case characters.
1159 The filestamp is not used in generated link names.
1160 The second line contains the datestamp in conventional Unix
1163 Lines beginning with
1165 are considered comments and ignored by the
1171 The remainder of the file contains cryptographic data, encoded first using ASN.1
1172 rules, then encrypted if necessary, and finally written in PEM-encoded
1173 printable ASCII text, preceded and followed by MIME content identifier lines.
1175 The format of the symmetric keys file, ordinarily named
1177 is somewhat different than the other files in the interest of backward compatibility.
1178 Ordinarily, the file is generated by this program, but it can be constructed
1179 and edited using an ordinary text editor.
1180 .Bd -literal -unfilled -offset center
1181 # ntpkey_MD5key_bk.ntp.org.3595864945
1182 # Thu Dec 12 19:22:25 2013
1184 1 MD5 L";Nw<\`.I<f4U0)247"i # MD5 key
1185 2 MD5 &>l0%XXK9O'51VwV<xq~ # MD5 key
1186 3 MD5 lb4zLW~d^!K:]RsD'qb6 # MD5 key
1187 4 MD5 Yue:tL[+vR)M\`n~bY,'? # MD5 key
1188 5 MD5 B;fx'Kgr/&4ZTbL6=RxA # MD5 key
1189 6 MD5 4eYwa\`o@}3i@@@@V@@..R9!l # MD5 key
1190 7 MD5 \`A.([h+;wTQ|xfi%Sn_! # MD5 key
1191 8 MD5 45:V,r4]l6y^JH6"Sh?F # MD5 key
1192 9 MD5 3-5vcn*6l29DS?Xdsg)* # MD5 key
1193 10 MD5 2late4Me # MD5 key
1194 11 SHA1 a27872d3030a9025b8446c751b4551a7629af65c # SHA1 key
1195 12 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74 # SHA1 key
1196 13 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9 # SHA1 key
1197 14 SHA a5332809c8878dd3a5b918819108a111509aeceb # SHA key
1198 15 MD2 2fe16c88c760ff2f16d4267e36c1aa6c926e6964 # MD2 key
1199 16 MD4 b2691811dc19cfc0e2f9bcacd74213f29812183d # MD4 key
1200 17 MD5 e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c # MD5 key
1201 18 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc # MDC2 key
1202 19 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2 # RIPEMD160 key
1203 20 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878 # AES128CMAC key
1205 .D1 Figure 1. Typical Symmetric Key File
1207 Figure 1 shows a typical symmetric keys file used by the reference
1209 Following the header the keys are entered one per line in the format
1210 .D1 Ar keyno Ar type Ar key
1213 is a positive integer in the range 1-65534;
1215 is the key type for the message digest algorithm, which in the absence of the
1216 OpenSSL library must be
1218 to designate the MD5 message digest algorithm;
1219 if the OpenSSL library is installed, the key type can be any
1220 message digest algorithm supported by that library;
1221 however, if compatibility with FIPS 140-2 is required,
1222 the key type must be either
1228 which is a printable ASCII string 20 characters or less in length:
1229 each character is chosen from the 93 printable characters
1230 in the range 0x21 through 0x7e (
1234 \&) excluding space and the
1236 character, and terminated by whitespace or a
1239 An OpenSSL key consists of a hex-encoded ASCII string of 40 characters, which
1240 is truncated as necessary.
1242 Note that the keys used by the
1245 .Xr ntpdc 1ntpdcmdoc
1247 are checked against passwords requested by the programs
1248 and entered by hand, so it is generally appropriate to specify these keys
1249 in human readable ASCII format.
1253 program generates a symmetric keys file
1254 .Pa ntpkey_MD5key_ Ns Ar hostname Ns . Ns Ar filestamp .
1255 Since the file contains private shared keys,
1256 it should be visible only to root and distributed by secure means
1257 to other subnet hosts.
1258 The NTP daemon loads the file
1262 installs a soft link from this name to the generated file.
1263 Subsequently, similar soft links must be installed by manual
1264 or automated means on the other subnet hosts.
1265 While this file is not used with the Autokey Version 2 protocol,
1266 it is needed to authenticate some remote configuration commands
1270 .Xr ntpdc 1ntpdcmdoc
1272 _END_PROG_MDOC_DESCRIP;
1278 ds-text = <<- _END_MDOC_USAGE
1285 ds-text = <<- _END_MDOC_NOTES
1286 Portions of this document came from FreeBSD.
1293 ds-text = <<- _END_MDOC_BUGS
1294 It can take quite a while to generate some cryptographic values.
1296 Please report bugs to http://bugs.ntp.org .