ntp-keygen-opts.def revision 330106
1/* -*- Mode: Text -*- */ 2 3autogen definitions options; 4 5#include copyright.def 6#include homerc.def 7#include autogen-version.def 8 9prog-name = "ntp-keygen"; 10prog-title = "Create a NTP host key"; 11package = ntp; 12 13include = '#include <stdlib.h>'; 14#include version.def 15 16flag = { 17 value = b; 18 name = imbits; 19 arg-type = number; 20 arg-name = imbits; 21 arg-range = '256->2048'; 22 ifdef = AUTOKEY; 23 descrip = "identity modulus bits"; 24 doc = <<- _EndOfDoc_ 25 The number of bits in the identity modulus. The default is 256. 26 _EndOfDoc_; 27}; 28 29flag = { 30 value = c; 31 name = certificate; 32 arg-type = string; 33 arg-name = scheme; 34 ifdef = AUTOKEY; 35 descrip = "certificate scheme"; 36 doc = <<- _EndOfDoc_ 37 scheme is one of 38 RSA-MD2, RSA-MD5, RSA-MDC2, RSA-SHA, RSA-SHA1, RSA-RIPEMD160, 39 DSA-SHA, or DSA-SHA1. 40 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. 45 _EndOfDoc_; 46}; 47 48flag = { 49 value = C; 50 name = cipher; 51 arg-type = string; 52 arg-name = cipher; 53 ifdef = AUTOKEY; 54 descrip = "privatekey cipher"; 55 doc = <<- _EndOfDoc_ 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. 60 _EndOfDoc_; 61}; 62 63#include debug-opt.def 64 65flag = { 66 value = e; 67 name = id-key; 68 ifdef = AUTOKEY; 69 descrip = "Write IFF or GQ identity keys"; 70 doc = <<- _EndOfDoc_ 71 Write the public parameters from the IFF or GQ client keys to 72 the standard output. 73 This is intended for automatic key distribution by email. 74 _EndOfDoc_; 75}; 76 77flag = { 78 value = G; 79 name = gq-params; 80 ifdef = AUTOKEY; 81 descrip = "Generate GQ parameters and keys"; 82 doc = <<- _EndOfDoc_ 83 Generate parameters and keys for the GQ identification scheme, 84 obsoleting any that may exist. 85 _EndOfDoc_; 86}; 87 88flag = { 89 value = H; 90 name = host-key; 91 ifdef = AUTOKEY; 92 descrip = "generate RSA host key"; 93 doc = <<- _EndOfDoc_ 94 Generate new host keys, obsoleting any that may exist. 95 _EndOfDoc_; 96}; 97 98flag = { 99 value = I; 100 name = iffkey; 101 ifdef = AUTOKEY; 102 descrip = "generate IFF parameters"; 103 doc = <<- _EndOfDoc_ 104 Generate parameters for the IFF identification scheme, obsoleting 105 any that may exist. 106 _EndOfDoc_; 107}; 108 109flag = { 110 value = i; 111 name = ident; 112 ifdef = AUTOKEY; 113 arg-type = string; 114 arg-name = group; 115 descrip = "set Autokey group name"; 116 doc = <<- _EndOfDoc_ 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. 126 _EndOfDoc_; 127}; 128 129flag = { 130 value = l; 131 name = lifetime; 132 ifdef = AUTOKEY; 133 arg-type = number; 134 arg-name = lifetime; 135 descrip = "set certificate lifetime"; 136 doc = <<- _EndOfDoc_ 137 Set the certificate expiration to lifetime days from now. 138 _EndOfDoc_; 139}; 140 141flag = { 142 value = m; 143 name = modulus; 144 arg-type = number; 145 arg-name = modulus; 146 arg-range = '256->2048'; 147 ifdef = AUTOKEY; 148 descrip = "prime modulus"; 149 doc = <<- _EndOfDoc_ 150 The number of bits in the prime modulus. The default is 512. 151 _EndOfDoc_; 152}; 153 154flag = { 155 value = M; 156 name = md5key; 157 descrip = "generate symmetric keys"; 158 doc = <<- _EndOfDoc_ 159 Generate symmetric keys, obsoleting any that may exist. 160 _EndOfDoc_; 161}; 162 163flag = { 164 value = P; 165 name = pvt-cert; 166 ifdef = AUTOKEY; 167 descrip = "generate PC private certificate"; 168 doc = <<- _EndOfDoc_ 169 Generate a private certificate. By default, the program generates 170 public certificates. 171 _EndOfDoc_; 172}; 173 174flag = { 175 value = p; 176 name = password; // was: pvt-passwd; 177 ifdef = AUTOKEY; 178 arg-type = string; 179 arg-name = passwd; 180 descrip = "local private password"; 181 doc = <<- _EndOfDoc_ 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 186 hostname. 187 _EndOfDoc_; 188}; 189 190flag = { 191 value = q; 192 name = export-passwd; // Was: get-pvt-passwd; 193 ifdef = AUTOKEY; 194 arg-type = string; 195 arg-name = passwd; 196 descrip = "export IFF or GQ group keys with password"; 197 doc = <<- _EndOfDoc_ 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. 203 _EndOfDoc_; 204}; 205 206flag = { 207 value = s; 208 name = subject-name; 209 arg-type = string; 210 arg-name = host@group; 211 ifdef = AUTOKEY; 212 descrip = "set host and optionally group name"; 213 doc = <<- _EndOfDoc_ 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. 224 _EndOfDoc_; 225}; 226 227flag = { 228 value = S; 229 name = sign-key; 230 arg-type = string; 231 arg-name = sign; 232 ifdef = AUTOKEY; 233 descrip = "generate sign key (RSA or DSA)"; 234 doc = <<- _EndOfDoc_ 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 237 sign key. 238 _EndOfDoc_; 239}; 240 241flag = { 242 value = T; 243 name = trusted-cert; 244 ifdef = AUTOKEY; 245 descrip = "trusted certificate (TC scheme)"; 246 doc = <<- _EndOfDoc_ 247 Generate a trusted certificate. By default, the program generates 248 a non-trusted certificate. 249 _EndOfDoc_; 250}; 251 252flag = { 253 value = V; 254 name = mv-params; 255 arg-type = number; 256 arg-name = num; 257 ifdef = AUTOKEY; 258 descrip = "generate <num> MV parameters"; 259 doc = <<- _EndOfDoc_ 260 Generate parameters and keys for the Mu-Varadharajan (MV) 261 identification scheme. 262 _EndOfDoc_; 263}; 264 265flag = { 266 value = v; 267 name = mv-keys; 268 arg-type = number; 269 arg-name = num; 270 ifdef = AUTOKEY; 271 descrip = "update <num> MV keys"; 272}; 273 274/* explain: Additional information whenever the usage routine is invoked */ 275explain = <<- _END_EXPLAIN 276 _END_EXPLAIN; 277 278doc-section = { 279 ds-type = 'DESCRIPTION'; 280 ds-format = 'mdoc'; 281 ds-text = <<- _END_PROG_MDOC_DESCRIP 282This program generates cryptographic data files used by the NTPv4 283authentication and identification schemes. 284It can generate message digest keys used in symmetric key cryptography and, 285if the OpenSSL software library has been installed, it can generate host keys, 286signing keys, certificates, and identity keys and parameters used in Autokey 287public key cryptography. 288These files are used for cookie encryption, 289digital signature, and challenge/response identification algorithms 290compatible with the Internet standard security infrastructure. 291.Pp 292The message digest symmetric keys file is generated in a format 293compatible with NTPv3. 294All other files are in PEM-encoded printable ASCII format, 295so they can be embedded as MIME attachments in email to other sites 296and certificate authorities. 297By default, files are not encrypted. 298.Pp 299When used to generate message digest symmetric keys, the program 300produces a file containing ten pseudo-random printable ASCII strings 301suitable for the MD5 message digest algorithm included in the 302distribution. 303If the OpenSSL library is installed, it produces an additional ten 304hex-encoded random bit strings suitable for SHA1, AES-128-CMAC, and 305other message digest algorithms. 306The message digest symmetric keys file must be distributed and stored 307using secure means beyond the scope of NTP itself. 308Besides the keys used for ordinary NTP associations, additional keys 309can be defined as passwords for the 310.Xr ntpq 1ntpqmdoc 311and 312.Xr ntpdc 1ntpdcmdoc 313utility programs. 314.Pp 315The remaining generated files are compatible with other OpenSSL 316applications and other Public Key Infrastructure (PKI) resources. 317Certificates generated by this program are compatible with extant 318industry practice, although some users might find the interpretation of 319X509v3 extension fields somewhat liberal. 320However, the identity keys are probably not compatible with anything 321other than Autokey. 322.Pp 323Some files used by this program are encrypted using a private password. 324The 325.Fl p 326option specifies the read password for local encrypted files and the 327.Fl q 328option the write password for encrypted files sent to remote sites. 329If no password is specified, the host name returned by the Unix 330.Xr hostname 1 331command, normally the DNS name of the host, is used as the the default read 332password, for convenience. 333The 334.Nm 335program prompts for the password if it reads an encrypted file 336and the password is missing or incorrect. 337If an encrypted file is read successfully and 338no write password is specified, the read password is used 339as the write password by default. 340.Pp 341The 342.Cm pw 343option of the 344.Ic crypto 345.Xr ntpd 1ntpdmdoc 346configuration command specifies the read 347password for previously encrypted local files. 348This must match the local read password used by this program. 349If not specified, the host name is used. 350Thus, if files are generated by this program without an explicit password, 351they can be read back by 352.Xr ntpd 1ntpdmdoc 353without specifying an explicit password but only on the same host. 354If the write password used for encryption is specified as the host name, 355these files can be read by that host with no explicit password. 356.Pp 357Normally, encrypted files for each host are generated by that host and 358used only by that host, although exceptions exist as noted later on 359this page. 360The symmetric keys file, normally called 361.Pa ntp.keys , 362is usually installed in 363.Pa /etc . 364Other files and links are usually installed in 365.Pa /usr/local/etc , 366which is normally in a shared filesystem in 367NFS-mounted networks and cannot be changed by shared clients. 368In these cases, NFS clients can specify the files in another 369directory such as 370.Pa /etc 371using the 372.Ic keysdir 373.Xr ntpd 1ntpdmdoc 374configuration file command. 375.Pp 376This program directs commentary and error messages to the standard 377error stream 378.Pa stderr 379and remote files to the standard output stream 380.Pa stdout 381where they can be piped to other applications or redirected to files. 382The names used for generated files and links all begin with the 383string 384.Pa ntpkey\&* 385and include the file type, generating host and filestamp, 386as described in the 387.Sx "Cryptographic Data Files" 388section below. 389 390.Ss Running the Program 391The safest way to run the 392.Nm 393program is logged in directly as root. 394The recommended procedure is change to the 395.Ar keys 396directory, usually 397.Pa /usr/local/etc , 398then run the program. 399.Pp 400To test and gain experience with Autokey concepts, log in as root and 401change to the 402.Ar keys 403directory, usually 404.Pa /usr/local/etc . 405When run for the first time, or if all files with names beginning with 406.Pa ntpkey\&* 407have been removed, use the 408.Nm 409command without arguments to generate a default 410.Cm RSA 411host key and matching 412.Cm RSA-MD5 413certificate file with expiration date one year hence, 414which is all that is necessary in many cases. 415The program also generates soft links from the generic names 416to the respective files. 417If run again without options, the program uses the 418existing keys and parameters and generates a new certificate file with 419new expiration date one year hence, and soft link. 420.Pp 421The host key is used to encrypt the cookie when required and so must be 422.Cm RSA 423type. 424By default, the host key is also the sign key used to encrypt signatures. 425When necessary, a different sign key can be specified and this can be 426either 427.Cm RSA 428or 429.Cm DSA 430type. 431By default, the message digest type is 432.Cm MD5 , 433but any combination 434of sign key type and message digest type supported by the OpenSSL library 435can be specified, including those using the 436.Cm AES128CMAC , MD2 , MD5 , MDC2 , SHA , SHA1 437and 438.Cm RIPE160 439message digest algorithms. 440However, the scheme specified in the certificate must be compatible 441with the sign key. 442Certificates using any digest algorithm are compatible with 443.Cm RSA 444sign keys; 445however, only 446.Cm SHA 447and 448.Cm SHA1 449certificates are compatible with 450.Cm DSA 451sign keys. 452.Pp 453Private/public key files and certificates are compatible with 454other OpenSSL applications and very likely other libraries as well. 455Certificates or certificate requests derived from them should be compatible 456with extant industry practice, although some users might find 457the interpretation of X509v3 extension fields somewhat liberal. 458However, the identification parameter files, although encoded 459as the other files, are probably not compatible with anything other than Autokey. 460.Pp 461Running the program as other than root and using the Unix 462.Xr su 1 463command 464to assume root may not work properly, since by default the OpenSSL library 465looks for the random seed file 466.Pa .rnd 467in the user home directory. 468However, there should be only one 469.Pa .rnd , 470most conveniently 471in the root directory, so it is convenient to define the 472.Ev RANDFILE 473environment variable used by the OpenSSL library as the path to 474.Pa .rnd . 475.Pp 476Installing the keys as root might not work in NFS-mounted 477shared file systems, as NFS clients may not be able to write 478to the shared keys directory, even as root. 479In this case, NFS clients can specify the files in another 480directory such as 481.Pa /etc 482using the 483.Ic keysdir 484.Xr ntpd 1ntpdmdoc 485configuration file command. 486There is no need for one client to read the keys and certificates 487of other clients or servers, as these data are obtained automatically 488by the Autokey protocol. 489.Pp 490Ordinarily, cryptographic files are generated by the host that uses them, 491but it is possible for a trusted agent (TA) to generate these files 492for other hosts; however, in such cases files should always be encrypted. 493The subject name and trusted name default to the hostname 494of the host generating the files, but can be changed by command line options. 495It is convenient to designate the owner name and trusted name 496as the subject and issuer fields, respectively, of the certificate. 497The owner name is also used for the host and sign key files, 498while the trusted name is used for the identity files. 499.Pp 500All files are installed by default in the keys directory 501.Pa /usr/local/etc , 502which is normally in a shared filesystem 503in NFS-mounted networks. 504The actual location of the keys directory 505and each file can be overridden by configuration commands, 506but this is not recommended. 507Normally, the files for each host are generated by that host 508and used only by that host, although exceptions exist 509as noted later on this page. 510.Pp 511Normally, files containing private values, 512including the host key, sign key and identification parameters, 513are permitted root read/write-only; 514while others containing public values are permitted world readable. 515Alternatively, files containing private values can be encrypted 516and these files permitted world readable, 517which simplifies maintenance in shared file systems. 518Since uniqueness is insured by the 519.Ar hostname 520and 521.Ar filestamp 522file name extensions, the files for an NTP server and 523dependent clients can all be installed in the same shared directory. 524.Pp 525The recommended practice is to keep the file name extensions 526when installing a file and to install a soft link 527from the generic names specified elsewhere on this page 528to the generated files. 529This allows new file generations to be activated simply 530by changing the link. 531If a link is present, 532.Xr ntpd 1ntpdmdoc 533follows it to the file name to extract the 534.Ar filestamp . 535If a link is not present, 536.Xr ntpd 1ntpdmdoc 537extracts the 538.Ar filestamp 539from the file itself. 540This allows clients to verify that the file and generation times 541are always current. 542The 543.Nm 544program uses the same 545.Ar filestamp 546extension for all files generated 547at one time, so each generation is distinct and can be readily 548recognized in monitoring data. 549.Pp 550Run the command on as many hosts as necessary. 551Designate one of them as the trusted host (TH) using 552.Nm 553with the 554.Fl T 555option and configure it to synchronize from reliable Internet servers. 556Then configure the other hosts to synchronize to the TH directly or 557indirectly. 558A certificate trail is created when Autokey asks the immediately 559ascendant host towards the TH to sign its certificate, which is then 560provided to the immediately descendant host on request. 561All group hosts should have acyclic certificate trails ending on the TH. 562.Pp 563The host key is used to encrypt the cookie when required and so must be 564RSA type. 565By default, the host key is also the sign key used to encrypt 566signatures. 567A different sign key can be assigned using the 568.Fl S 569option and this can be either 570.Cm RSA 571or 572.Cm DSA 573type. 574By default, the signature 575message digest type is 576.Cm MD5 , 577but any combination of sign key type and 578message digest type supported by the OpenSSL library can be specified 579using the 580.Fl c 581option. 582.Pp 583The rules say cryptographic media should be generated with proventic 584filestamps, which means the host should already be synchronized before 585this program is run. 586This of course creates a chicken-and-egg problem 587when the host is started for the first time. 588Accordingly, the host time 589should be set by some other means, such as eyeball-and-wristwatch, at 590least so that the certificate lifetime is within the current year. 591After that and when the host is synchronized to a proventic source, the 592certificate should be re-generated. 593.Pp 594Additional information on trusted groups and identity schemes is on the 595.Dq Autokey Public-Key Authentication 596page. 597.Pp 598File names begin with the prefix 599.Pa ntpkey Ns _ 600and end with the suffix 601.Pa _ Ns Ar hostname . Ar filestamp , 602where 603.Ar hostname 604is the owner name, usually the string returned 605by the Unix 606.Xr hostname 1 607command, and 608.Ar filestamp 609is the NTP seconds when the file was generated, in decimal digits. 610This both guarantees uniqueness and simplifies maintenance 611procedures, since all files can be quickly removed 612by a 613.Ic rm Pa ntpkey\&* 614command or all files generated 615at a specific time can be removed by a 616.Ic rm Pa \&* Ns Ar filestamp 617command. 618To further reduce the risk of misconfiguration, 619the first two lines of a file contain the file name 620and generation date and time as comments. 621 622.Ss Trusted Hosts and Groups 623Each cryptographic configuration involves selection of a signature scheme 624and identification scheme, called a cryptotype, 625as explained in the 626.Sx Authentication Options 627section of 628.Xr ntp.conf 5 . 629The default cryptotype uses 630.Cm RSA 631encryption, 632.Cm MD5 633message digest 634and 635.Cm TC 636identification. 637First, configure a NTP subnet including one or more low-stratum 638trusted hosts from which all other hosts derive synchronization 639directly or indirectly. 640Trusted hosts have trusted certificates; 641all other hosts have nontrusted certificates. 642These hosts will automatically and dynamically build authoritative 643certificate trails to one or more trusted hosts. 644A trusted group is the set of all hosts that have, directly or indirectly, 645a certificate trail ending at a trusted host. 646The trail is defined by static configuration file entries 647or dynamic means described on the 648.Sx Automatic NTP Configuration Options 649section of 650.Xr ntp.conf 5 . 651.Pp 652On each trusted host as root, change to the keys directory. 653To insure a fresh fileset, remove all 654.Pa ntpkey 655files. 656Then run 657.Nm 658.Fl T 659to generate keys and a trusted certificate. 660On all other hosts do the same, but leave off the 661.Fl T 662flag to generate keys and nontrusted certificates. 663When complete, start the NTP daemons beginning at the lowest stratum 664and working up the tree. 665It may take some time for Autokey to instantiate the certificate trails 666throughout the subnet, but setting up the environment is completely automatic. 667.Pp 668If it is necessary to use a different sign key or different digest/signature 669scheme than the default, run 670.Nm 671with the 672.Fl S Ar type 673option, where 674.Ar type 675is either 676.Cm RSA 677or 678.Cm DSA . 679The most frequent need to do this is when a 680.Cm DSA Ns -signed 681certificate is used. 682If it is necessary to use a different certificate scheme than the default, 683run 684.Nm 685with the 686.Fl c Ar scheme 687option and selected 688.Ar scheme 689as needed. 690If 691.Nm 692is run again without these options, it generates a new certificate 693using the same scheme and sign key, and soft link. 694.Pp 695After setting up the environment it is advisable to update certificates 696from time to time, if only to extend the validity interval. 697Simply run 698.Nm 699with the same flags as before to generate new certificates 700using existing keys, and soft links. 701However, if the host or sign key is changed, 702.Xr ntpd 1ntpdmdoc 703should be restarted. 704When 705.Xr ntpd 1ntpdmdoc 706is restarted, it loads any new files and restarts the protocol. 707Other dependent hosts will continue as usual until signatures are refreshed, 708at which time the protocol is restarted. 709 710.Ss Identity Schemes 711As mentioned on the Autonomous Authentication page, 712the default 713.Cm TC 714identity scheme is vulnerable to a middleman attack. 715However, there are more secure identity schemes available, 716including 717.Cm PC , IFF , GQ 718and 719.Cm MV 720schemes described below. 721These schemes are based on a TA, one or more trusted hosts 722and some number of nontrusted hosts. 723Trusted hosts prove identity using values provided by the TA, 724while the remaining hosts prove identity using values provided 725by a trusted host and certificate trails that end on that host. 726The name of a trusted host is also the name of its sugroup 727and also the subject and issuer name on its trusted certificate. 728The TA is not necessarily a trusted host in this sense, but often is. 729.Pp 730In some schemes there are separate keys for servers and clients. 731A server can also be a client of another server, 732but a client can never be a server for another client. 733In general, trusted hosts and nontrusted hosts that operate 734as both server and client have parameter files that contain 735both server and client keys. 736Hosts that operate 737only as clients have key files that contain only client keys. 738.Pp 739The PC scheme supports only one trusted host in the group. 740On trusted host alice run 741.Nm 742.Fl P 743.Fl p Ar password 744to generate the host key file 745.Pa ntpkey Ns _ Cm RSA Pa key_alice. Ar filestamp 746and trusted private certificate file 747.Pa ntpkey Ns _ Cm RSA-MD5 _ Pa cert_alice. Ar filestamp , 748and soft links. 749Copy both files to all group hosts; 750they replace the files which would be generated in other schemes. 751On each host 752.Ar bob 753install a soft link from the generic name 754.Pa ntpkey_host_ Ns Ar bob 755to the host key file and soft link 756.Pa ntpkey_cert_ Ns Ar bob 757to the private certificate file. 758Note the generic links are on bob, but point to files generated 759by trusted host alice. 760In this scheme it is not possible to refresh 761either the keys or certificates without copying them 762to all other hosts in the group, and recreating the soft links. 763.Pp 764For the 765.Cm IFF 766scheme proceed as in the 767.Cm TC 768scheme to generate keys 769and certificates for all group hosts, then for every trusted host in the group, 770generate the 771.Cm IFF 772parameter file. 773On trusted host alice run 774.Nm 775.Fl T 776.Fl I 777.Fl p Ar password 778to produce her parameter file 779.Pa ntpkey_IFFpar_alice. Ns Ar filestamp , 780which includes both server and client keys. 781Copy this file to all group hosts that operate as both servers 782and clients and install a soft link from the generic 783.Pa ntpkey_iff_alice 784to this file. 785If there are no hosts restricted to operate only as clients, 786there is nothing further to do. 787As the 788.Cm IFF 789scheme is independent 790of keys and certificates, these files can be refreshed as needed. 791.Pp 792If a rogue client has the parameter file, it could masquerade 793as a legitimate server and present a middleman threat. 794To eliminate this threat, the client keys can be extracted 795from the parameter file and distributed to all restricted clients. 796After generating the parameter file, on alice run 797.Nm 798.Fl e 799and pipe the output to a file or email program. 800Copy or email this file to all restricted clients. 801On these clients install a soft link from the generic 802.Pa ntpkey_iff_alice 803to this file. 804To further protect the integrity of the keys, 805each file can be encrypted with a secret password. 806.Pp 807For the 808.Cm GQ 809scheme proceed as in the 810.Cm TC 811scheme to generate keys 812and certificates for all group hosts, then for every trusted host 813in the group, generate the 814.Cm IFF 815parameter file. 816On trusted host alice run 817.Nm 818.Fl T 819.Fl G 820.Fl p Ar password 821to produce her parameter file 822.Pa ntpkey_GQpar_alice. Ns Ar filestamp , 823which includes both server and client keys. 824Copy this file to all group hosts and install a soft link 825from the generic 826.Pa ntpkey_gq_alice 827to this file. 828In addition, on each host 829.Ar bob 830install a soft link 831from generic 832.Pa ntpkey_gq_ Ns Ar bob 833to this file. 834As the 835.Cm GQ 836scheme updates the 837.Cm GQ 838parameters file and certificate 839at the same time, keys and certificates can be regenerated as needed. 840.Pp 841For the 842.Cm MV 843scheme, proceed as in the 844.Cm TC 845scheme to generate keys 846and certificates for all group hosts. 847For illustration assume trish is the TA, alice one of several trusted hosts 848and bob one of her clients. 849On TA trish run 850.Nm 851.Fl V Ar n 852.Fl p Ar password , 853where 854.Ar n 855is the number of revokable keys (typically 5) to produce 856the parameter file 857.Pa ntpkeys_MVpar_trish. Ns Ar filestamp 858and client key files 859.Pa ntpkeys_MVkey Ns Ar d _ Pa trish. Ar filestamp 860where 861.Ar d 862is the key number (0 \&< 863.Ar d 864\&< 865.Ar n ) . 866Copy the parameter file to alice and install a soft link 867from the generic 868.Pa ntpkey_mv_alice 869to this file. 870Copy one of the client key files to alice for later distribution 871to her clients. 872It does not matter which client key file goes to alice, 873since they all work the same way. 874Alice copies the client key file to all of her clients. 875On client bob install a soft link from generic 876.Pa ntpkey_mvkey_bob 877to the client key file. 878As the 879.Cm MV 880scheme is independent of keys and certificates, 881these files can be refreshed as needed. 882 883.Ss Command Line Options 884.Bl -tag -width indent 885.It Fl b Fl -imbits Ns = Ar modulus 886Set the number of bits in the identity modulus for generating identity keys to 887.Ar modulus 888bits. 889The number of bits in the identity modulus defaults to 256, but can be set to 890values from 256 to 2048 (32 to 256 octets). 891Use the larger moduli with caution, as this can consume considerable computing 892resources and increases the size of authenticated packets. 893.It Fl c Fl -certificate Ns = Ar scheme 894Select certificate signature encryption/message digest scheme. 895The 896.Ar scheme 897can be one of the following: 898.Cm RSA-MD2 , RSA-MD5 , RSA-MDC2 , RSA-SHA , RSA-SHA1 , RSA-RIPEMD160 , DSA-SHA , 899or 900.Cm DSA-SHA1 . 901Note that 902.Cm RSA 903schemes must be used with an 904.Cm RSA 905sign key and 906.Cm DSA 907schemes must be used with a 908.Cm DSA 909sign key. 910The default without this option is 911.Cm RSA-MD5 . 912If compatibility with FIPS 140-2 is required, either the 913.Cm DSA-SHA 914or 915.Cm DSA-SHA1 916scheme must be used. 917.It Fl C Fl -cipher Ns = Ar cipher 918Select the OpenSSL cipher to encrypt the files containing private keys. 919The default without this option is three-key triple DES in CBC mode, 920.Cm des-ede3-cbc . 921The 922.Ic openssl Fl h 923command provided with OpenSSL displays available ciphers. 924.It Fl d Fl -debug-level 925Increase debugging verbosity level. 926This option displays the cryptographic data produced in eye-friendly billboards. 927.It Fl D Fl -set-debug-level Ns = Ar level 928Set the debugging verbosity to 929.Ar level . 930This option displays the cryptographic data produced in eye-friendly billboards. 931.It Fl e Fl -id-key 932Write the 933.Cm IFF 934or 935.Cm GQ 936public parameters from the 937.Ar IFFkey or GQkey 938client keys file previously specified 939as unencrypted data to the standard output stream 940.Pa stdout . 941This is intended for automatic key distribution by email. 942.It Fl G Fl -gq-params 943Generate a new encrypted 944.Cm GQ 945parameters and key file for the Guillou-Quisquater (GQ) identity scheme. 946This option is mutually exclusive with the 947.Fl I 948and 949.Fl V 950options. 951.It Fl H Fl -host-key 952Generate a new encrypted 953.Cm RSA 954public/private host key file. 955.It Fl I Fl -iffkey 956Generate a new encrypted 957.Cm IFF 958key file for the Schnorr (IFF) identity scheme. 959This option is mutually exclusive with the 960.Fl G 961and 962Fl V 963options. 964.It Fl i Fl -ident Ns = Ar group 965Set the optional Autokey group name to 966.Ar group . 967This is used in the identity scheme parameter file names of 968.Cm IFF , GQ , 969and 970.Cm MV 971client parameters files. 972In that role, the default is the host name if no group is provided. 973The group name, if specified using 974.Fl i 975or 976.Fl s 977following an 978.Ql @@ 979character, is also used in certificate subject and issuer names in the form 980.Ar host @@ group 981and should match the group specified via 982.Ic crypto Cm ident 983or 984.Ic server Cm ident 985in the ntpd configuration file. 986.It Fl l Fl -lifetime Ns = Ar days 987Set the lifetime for certificate expiration to 988.Ar days . 989The default lifetime is one year (365 days). 990.It Fl m Fl -modulus Ns = Ar bits 991Set the number of bits in the prime modulus for generating files to 992.Ar bits . 993The modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets). 994Use the larger moduli with caution, as this can consume considerable computing 995resources and increases the size of authenticated packets. 996.It Fl M Fl -md5key 997Generate a new symmetric keys file containing 10 998.Cm MD5 999keys, and if OpenSSL is available, 10 1000.Cm SHA 1001keys. 1002An 1003.Cm MD5 1004key is a string of 20 random printable ASCII characters, while a 1005.Cm SHA 1006key is a string of 40 random hex digits. 1007The file can be edited using a text editor to change the key type or key content. 1008This option is mutually exclusive with all other options. 1009.It Fl p Fl -password Ns = Ar passwd 1010Set the password for reading and writing encrypted files to 1011.Ar passwd . 1012These include the host, sign and identify key files. 1013By default, the password is the string returned by the Unix 1014.Ic hostname 1015command. 1016.It Fl P Fl -pvt-cert 1017Generate a new private certificate used by the 1018.Cm PC 1019identity scheme. 1020By default, the program generates public certificates. 1021Note: the PC identity scheme is not recommended for new installations. 1022.It Fl q Fl -export-passwd Ns = Ar passwd 1023Set the password for writing encrypted 1024.Cm IFF , GQ and MV 1025identity files redirected to 1026.Pa stdout 1027to 1028.Ar passwd . 1029In effect, these files are decrypted with the 1030.Fl p 1031password, then encrypted with the 1032.Fl q 1033password. 1034By default, the password is the string returned by the Unix 1035.Ic hostname 1036command. 1037.It Fl s Fl -subject-key Ns = Ar Oo host Oc Op @@ Ar group 1038Specify the Autokey host name, where 1039.Ar host 1040is the optional host name and 1041.Ar group 1042is the optional group name. 1043The host name, and if provided, group name are used in 1044.Ar host @@ group 1045form as certificate subject and issuer. 1046Specifying 1047.Fl s @@ Ar group 1048is allowed, and results in leaving the host name unchanged, as with 1049.Fl i Ar group . 1050The group name, or if no group is provided, the host name are also used in the 1051file names of 1052.Cm IFF , GQ , 1053and 1054.Cm MV 1055identity scheme client parameter files. 1056If 1057.Ar host 1058is not specified, the default host name is the string returned by the Unix 1059.Ic hostname 1060command. 1061.It Fl S Fl -sign-key Ns = Op Cm RSA | DSA 1062Generate a new encrypted public/private sign key file of the specified type. 1063By default, the sign key is the host key and has the same type. 1064If compatibility with FIPS 140-2 is required, the sign key type must be 1065.Cm DSA . 1066.It Fl T Fl -trusted-cert 1067Generate a trusted certificate. 1068By default, the program generates a non-trusted certificate. 1069.It Fl V Fl -mv-params Ar nkeys 1070Generate 1071.Ar nkeys 1072encrypted server keys and parameters for the Mu-Varadharajan (MV) 1073identity scheme. 1074This option is mutually exclusive with the 1075.Fl I 1076and 1077.Fl G 1078options. 1079Note: support for this option should be considered a work in progress. 1080.El 1081 1082.Ss Random Seed File 1083All cryptographically sound key generation schemes must have means 1084to randomize the entropy seed used to initialize 1085the internal pseudo-random number generator used 1086by the library routines. 1087The OpenSSL library uses a designated random seed file for this purpose. 1088The file must be available when starting the NTP daemon and 1089.Nm 1090program. 1091If a site supports OpenSSL or its companion OpenSSH, 1092it is very likely that means to do this are already available. 1093.Pp 1094It is important to understand that entropy must be evolved 1095for each generation, for otherwise the random number sequence 1096would be predictable. 1097Various means dependent on external events, such as keystroke intervals, 1098can be used to do this and some systems have built-in entropy sources. 1099Suitable means are described in the OpenSSL software documentation, 1100but are outside the scope of this page. 1101.Pp 1102The entropy seed used by the OpenSSL library is contained in a file, 1103usually called 1104.Pa .rnd , 1105which must be available when starting the NTP daemon 1106or the 1107.Nm 1108program. 1109The NTP daemon will first look for the file 1110using the path specified by the 1111.Cm randfile 1112subcommand of the 1113.Ic crypto 1114configuration command. 1115If not specified in this way, or when starting the 1116.Nm 1117program, 1118the OpenSSL library will look for the file using the path specified 1119by the 1120.Ev RANDFILE 1121environment variable in the user home directory, 1122whether root or some other user. 1123If the 1124.Ev RANDFILE 1125environment variable is not present, 1126the library will look for the 1127.Pa .rnd 1128file in the user home directory. 1129Since both the 1130.Nm 1131program and 1132.Xr ntpd 1ntpdmdoc 1133daemon must run as root, the logical place to put this file is in 1134.Pa /.rnd 1135or 1136.Pa /root/.rnd . 1137If the file is not available or cannot be written, 1138the daemon exits with a message to the system log and the program 1139exits with a suitable error message. 1140 1141.Ss Cryptographic Data Files 1142All file formats begin with two nonencrypted lines. 1143The first line contains the file name, including the generated host name 1144and filestamp, in the format 1145.Pa ntpkey_ Ns Ar key _ Ar name . Ar filestamp , 1146where 1147.Ar key 1148is the key or parameter type, 1149.Ar name 1150is the host or group name and 1151.Ar filestamp 1152is the filestamp (NTP seconds) when the file was created. 1153By convention, 1154.Ar key 1155names in generated file names include both upper and lower case 1156characters, while 1157.Ar key 1158names in generated link names include only lower case characters. 1159The filestamp is not used in generated link names. 1160The second line contains the datestamp in conventional Unix 1161.Pa date 1162format. 1163Lines beginning with 1164.Ql # 1165are considered comments and ignored by the 1166.Nm 1167program and 1168.Xr ntpd 1ntpdmdoc 1169daemon. 1170.Pp 1171The remainder of the file contains cryptographic data, encoded first using ASN.1 1172rules, then encrypted if necessary, and finally written in PEM-encoded 1173printable ASCII text, preceded and followed by MIME content identifier lines. 1174.Pp 1175The format of the symmetric keys file, ordinarily named 1176.Pa ntp.keys , 1177is somewhat different than the other files in the interest of backward compatibility. 1178Ordinarily, the file is generated by this program, but it can be constructed 1179and 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 1183 11841 MD5 L";Nw<\`.I<f4U0)247"i # MD5 key 11852 MD5 &>l0%XXK9O'51VwV<xq~ # MD5 key 11863 MD5 lb4zLW~d^!K:]RsD'qb6 # MD5 key 11874 MD5 Yue:tL[+vR)M\`n~bY,'? # MD5 key 11885 MD5 B;fx'Kgr/&4ZTbL6=RxA # MD5 key 11896 MD5 4eYwa\`o@}3i@@@@V@@..R9!l # MD5 key 11907 MD5 \`A.([h+;wTQ|xfi%Sn_! # MD5 key 11918 MD5 45:V,r4]l6y^JH6"Sh?F # MD5 key 11929 MD5 3-5vcn*6l29DS?Xdsg)* # MD5 key 119310 MD5 2late4Me # MD5 key 119411 SHA1 a27872d3030a9025b8446c751b4551a7629af65c # SHA1 key 119512 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74 # SHA1 key 119613 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9 # SHA1 key 119714 SHA a5332809c8878dd3a5b918819108a111509aeceb # SHA key 119815 MD2 2fe16c88c760ff2f16d4267e36c1aa6c926e6964 # MD2 key 119916 MD4 b2691811dc19cfc0e2f9bcacd74213f29812183d # MD4 key 120017 MD5 e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c # MD5 key 120118 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc # MDC2 key 120219 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2 # RIPEMD160 key 120320 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878 # AES128CMAC key 1204.Ed 1205.D1 Figure 1. Typical Symmetric Key File 1206.Pp 1207Figure 1 shows a typical symmetric keys file used by the reference 1208implementation. 1209Following the header the keys are entered one per line in the format 1210.D1 Ar keyno Ar type Ar key 1211where 1212.Ar keyno 1213is a positive integer in the range 1-65534; 1214.Ar type 1215is the key type for the message digest algorithm, which in the absence of the 1216OpenSSL library must be 1217.Cm MD5 1218to designate the MD5 message digest algorithm; 1219if the OpenSSL library is installed, the key type can be any 1220message digest algorithm supported by that library; 1221however, if compatibility with FIPS 140-2 is required, 1222the key type must be either 1223.Cm SHA 1224or 1225.Cm SHA1 ; 1226.Ar key 1227is the key itself, 1228which is a printable ASCII string 20 characters or less in length: 1229each character is chosen from the 93 printable characters 1230in the range 0x21 through 0x7e ( 1231.Ql ! 1232through 1233.Ql ~ 1234\&) excluding space and the 1235.Ql # 1236character, and terminated by whitespace or a 1237.Ql # 1238character. 1239An OpenSSL key consists of a hex-encoded ASCII string of 40 characters, which 1240is truncated as necessary. 1241.Pp 1242Note that the keys used by the 1243.Xr ntpq 1ntpqmdoc 1244and 1245.Xr ntpdc 1ntpdcmdoc 1246programs 1247are checked against passwords requested by the programs 1248and entered by hand, so it is generally appropriate to specify these keys 1249in human readable ASCII format. 1250.Pp 1251The 1252.Nm 1253program generates a symmetric keys file 1254.Pa ntpkey_MD5key_ Ns Ar hostname Ns . Ns Ar filestamp . 1255Since the file contains private shared keys, 1256it should be visible only to root and distributed by secure means 1257to other subnet hosts. 1258The NTP daemon loads the file 1259.Pa ntp.keys , 1260so 1261.Nm 1262installs a soft link from this name to the generated file. 1263Subsequently, similar soft links must be installed by manual 1264or automated means on the other subnet hosts. 1265While this file is not used with the Autokey Version 2 protocol, 1266it is needed to authenticate some remote configuration commands 1267used by the 1268.Xr ntpq 1ntpqmdoc 1269and 1270.Xr ntpdc 1ntpdcmdoc 1271utilities. 1272 _END_PROG_MDOC_DESCRIP; 1273}; 1274 1275doc-section = { 1276 ds-type = 'USAGE'; 1277 ds-format = 'mdoc'; 1278 ds-text = <<- _END_MDOC_USAGE 1279 _END_MDOC_USAGE; 1280}; 1281 1282doc-section = { 1283 ds-type = 'NOTES'; 1284 ds-format = 'mdoc'; 1285 ds-text = <<- _END_MDOC_NOTES 1286Portions of this document came from FreeBSD. 1287 _END_MDOC_NOTES; 1288}; 1289 1290doc-section = { 1291 ds-type = 'BUGS'; 1292 ds-format = 'mdoc'; 1293 ds-text = <<- _END_MDOC_BUGS 1294It can take quite a while to generate some cryptographic values. 1295.Pp 1296Please report bugs to http://bugs.ntp.org . 1297 _END_MDOC_BUGS; 1298}; 1299