invoke-ntp-keygen.texi revision 309007
1@node ntp-keygen Invocation 2@section Invoking ntp-keygen 3@pindex ntp-keygen 4@cindex Create a NTP host key 5@ignore 6# 7# EDIT THIS FILE WITH CAUTION (invoke-ntp-keygen.texi) 8# 9# It has been AutoGen-ed November 21, 2016 at 08:03:45 AM by AutoGen 5.18.5 10# From the definitions ntp-keygen-opts.def 11# and the template file agtexi-cmd.tpl 12@end ignore 13 14 15 16This program generates cryptographic data files used by the NTPv4 17authentication and identification schemes. 18It generates MD5 key files used in symmetric key cryptography. 19In addition, if the OpenSSL software library has been installed, 20it generates keys, certificate and identity files used in public key 21cryptography. 22These files are used for cookie encryption, 23digital signature and challenge/response identification algorithms 24compatible with the Internet standard security infrastructure. 25 26All files are in PEM-encoded printable ASCII format, 27so they can be embedded as MIME attachments in mail to other sites 28and certificate authorities. 29By default, files are not encrypted. 30 31When used to generate message digest keys, the program produces a file 32containing ten pseudo-random printable ASCII strings suitable for the 33MD5 message digest algorithm included in the distribution. 34If the OpenSSL library is installed, it produces an additional ten 35hex-encoded random bit strings suitable for the SHA1 and other message 36digest algorithms. 37The message digest keys file must be distributed and stored 38using secure means beyond the scope of NTP itself. 39Besides the keys used for ordinary NTP associations, additional keys 40can be defined as passwords for the 41@code{ntpq(1ntpqmdoc)} 42and 43@code{ntpdc(1ntpdcmdoc)} 44utility programs. 45 46The remaining generated files are compatible with other OpenSSL 47applications and other Public Key Infrastructure (PKI) resources. 48Certificates generated by this program are compatible with extant 49industry practice, although some users might find the interpretation of 50X509v3 extension fields somewhat liberal. 51However, the identity keys are probably not compatible with anything 52other than Autokey. 53 54Some files used by this program are encrypted using a private password. 55The 56@code{-p} 57option specifies the password for local encrypted files and the 58@code{-q} 59option the password for encrypted files sent to remote sites. 60If no password is specified, the host name returned by the Unix 61@code{gethostname()} 62function, normally the DNS name of the host is used. 63 64The 65@kbd{pw} 66option of the 67@kbd{crypto} 68configuration command specifies the read 69password for previously encrypted local files. 70This must match the local password used by this program. 71If not specified, the host name is used. 72Thus, if files are generated by this program without password, 73they can be read back by 74@kbd{ntpd} 75without password but only on the same host. 76 77Normally, encrypted files for each host are generated by that host and 78used only by that host, although exceptions exist as noted later on 79this page. 80The symmetric keys file, normally called 81@kbd{ntp.keys}, 82is usually installed in 83@file{/etc}. 84Other files and links are usually installed in 85@file{/usr/local/etc}, 86which is normally in a shared filesystem in 87NFS-mounted networks and cannot be changed by shared clients. 88The location of the keys directory can be changed by the 89@kbd{keysdir} 90configuration command in such cases. 91Normally, this is in 92@file{/etc}. 93 94This program directs commentary and error messages to the standard 95error stream 96@kbd{stderr} 97and remote files to the standard output stream 98@kbd{stdout} 99where they can be piped to other applications or redirected to files. 100The names used for generated files and links all begin with the 101string 102@kbd{ntpkey} 103and include the file type, generating host and filestamp, 104as described in the 105@quotedblleft{}Cryptographic Data Files@quotedblright{} 106section below. 107@subsubsection Running the Program 108To test and gain experience with Autokey concepts, log in as root and 109change to the keys directory, usually 110@file{/usr/local/etc} 111When run for the first time, or if all files with names beginning with 112@kbd{ntpkey} 113have been removed, use the 114@code{ntp-keygen} 115command without arguments to generate a 116default RSA host key and matching RSA-MD5 certificate with expiration 117date one year hence. 118If run again without options, the program uses the 119existing keys and parameters and generates only a new certificate with 120new expiration date one year hence. 121 122Run the command on as many hosts as necessary. 123Designate one of them as the trusted host (TH) using 124@code{ntp-keygen} 125with the 126@code{-T} 127option and configure it to synchronize from reliable Internet servers. 128Then configure the other hosts to synchronize to the TH directly or 129indirectly. 130A certificate trail is created when Autokey asks the immediately 131ascendant host towards the TH to sign its certificate, which is then 132provided to the immediately descendant host on request. 133All group hosts should have acyclic certificate trails ending on the TH. 134 135The host key is used to encrypt the cookie when required and so must be 136RSA type. 137By default, the host key is also the sign key used to encrypt 138signatures. 139A different sign key can be assigned using the 140@code{-S} 141option and this can be either RSA or DSA type. 142By default, the signature 143message digest type is MD5, but any combination of sign key type and 144message digest type supported by the OpenSSL library can be specified 145using the 146@code{-c} 147option. 148The rules say cryptographic media should be generated with proventic 149filestamps, which means the host should already be synchronized before 150this program is run. 151This of course creates a chicken-and-egg problem 152when the host is started for the first time. 153Accordingly, the host time 154should be set by some other means, such as eyeball-and-wristwatch, at 155least so that the certificate lifetime is within the current year. 156After that and when the host is synchronized to a proventic source, the 157certificate should be re-generated. 158 159Additional information on trusted groups and identity schemes is on the 160@quotedblleft{}Autokey Public-Key Authentication@quotedblright{} 161page. 162 163 164 165The 166@code{ntpd(1ntpdmdoc)} 167configuration command 168@code{crypto} @code{pw} @kbd{password} 169specifies the read password for previously encrypted files. 170The daemon expires on the spot if the password is missing 171or incorrect. 172For convenience, if a file has been previously encrypted, 173the default read password is the name of the host running 174the program. 175If the previous write password is specified as the host name, 176these files can be read by that host with no explicit password. 177 178 179File names begin with the prefix 180@code{ntpkey_} 181and end with the postfix 182@kbd{_hostname.filestamp}, 183where 184@kbd{hostname} 185is the owner name, usually the string returned 186by the Unix gethostname() routine, and 187@kbd{filestamp} 188is the NTP seconds when the file was generated, in decimal digits. 189This both guarantees uniqueness and simplifies maintenance 190procedures, since all files can be quickly removed 191by a 192@code{rm} @code{ntpkey*} 193command or all files generated 194at a specific time can be removed by a 195@code{rm} 196@kbd{*filestamp} 197command. 198To further reduce the risk of misconfiguration, 199the first two lines of a file contain the file name 200and generation date and time as comments. 201 202All files are installed by default in the keys directory 203@file{/usr/local/etc}, 204which is normally in a shared filesystem 205in NFS-mounted networks. 206The actual location of the keys directory 207and each file can be overridden by configuration commands, 208but this is not recommended. 209Normally, the files for each host are generated by that host 210and used only by that host, although exceptions exist 211as noted later on this page. 212 213Normally, files containing private values, 214including the host key, sign key and identification parameters, 215are permitted root read/write-only; 216while others containing public values are permitted world readable. 217Alternatively, files containing private values can be encrypted 218and these files permitted world readable, 219which simplifies maintenance in shared file systems. 220Since uniqueness is insured by the hostname and 221file name extensions, the files for a NFS server and 222dependent clients can all be installed in the same shared directory. 223 224The recommended practice is to keep the file name extensions 225when installing a file and to install a soft link 226from the generic names specified elsewhere on this page 227to the generated files. 228This allows new file generations to be activated simply 229by changing the link. 230If a link is present, ntpd follows it to the file name 231to extract the filestamp. 232If a link is not present, 233@code{ntpd(1ntpdmdoc)} 234extracts the filestamp from the file itself. 235This allows clients to verify that the file and generation times 236are always current. 237The 238@code{ntp-keygen} 239program uses the same timestamp extension for all files generated 240at one time, so each generation is distinct and can be readily 241recognized in monitoring data. 242@subsubsection Running the program 243The safest way to run the 244@code{ntp-keygen} 245program is logged in directly as root. 246The recommended procedure is change to the keys directory, 247usually 248@file{/usr/local/etc}, 249then run the program. 250When run for the first time, 251or if all 252@code{ntpkey} 253files have been removed, 254the program generates a RSA host key file and matching RSA-MD5 certificate file, 255which is all that is necessary in many cases. 256The program also generates soft links from the generic names 257to the respective files. 258If run again, the program uses the same host key file, 259but generates a new certificate file and link. 260 261The host key is used to encrypt the cookie when required and so must be RSA type. 262By default, the host key is also the sign key used to encrypt signatures. 263When necessary, a different sign key can be specified and this can be 264either RSA or DSA type. 265By default, the message digest type is MD5, but any combination 266of sign key type and message digest type supported by the OpenSSL library 267can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 268and RIPE160 message digest algorithms. 269However, the scheme specified in the certificate must be compatible 270with the sign key. 271Certificates using any digest algorithm are compatible with RSA sign keys; 272however, only SHA and SHA1 certificates are compatible with DSA sign keys. 273 274Private/public key files and certificates are compatible with 275other OpenSSL applications and very likely other libraries as well. 276Certificates or certificate requests derived from them should be compatible 277with extant industry practice, although some users might find 278the interpretation of X509v3 extension fields somewhat liberal. 279However, the identification parameter files, although encoded 280as the other files, are probably not compatible with anything other than Autokey. 281 282Running the program as other than root and using the Unix 283@code{su} 284command 285to assume root may not work properly, since by default the OpenSSL library 286looks for the random seed file 287@code{.rnd} 288in the user home directory. 289However, there should be only one 290@code{.rnd}, 291most conveniently 292in the root directory, so it is convenient to define the 293@code{$RANDFILE} 294environment variable used by the OpenSSL library as the path to 295@code{/.rnd}. 296 297Installing the keys as root might not work in NFS-mounted 298shared file systems, as NFS clients may not be able to write 299to the shared keys directory, even as root. 300In this case, NFS clients can specify the files in another 301directory such as 302@file{/etc} 303using the 304@code{keysdir} 305command. 306There is no need for one client to read the keys and certificates 307of other clients or servers, as these data are obtained automatically 308by the Autokey protocol. 309 310Ordinarily, cryptographic files are generated by the host that uses them, 311but it is possible for a trusted agent (TA) to generate these files 312for other hosts; however, in such cases files should always be encrypted. 313The subject name and trusted name default to the hostname 314of the host generating the files, but can be changed by command line options. 315It is convenient to designate the owner name and trusted name 316as the subject and issuer fields, respectively, of the certificate. 317The owner name is also used for the host and sign key files, 318while the trusted name is used for the identity files. 319 320 321All files are installed by default in the keys directory 322@file{/usr/local/etc}, 323which is normally in a shared filesystem 324in NFS-mounted networks. 325The actual location of the keys directory 326and each file can be overridden by configuration commands, 327but this is not recommended. 328Normally, the files for each host are generated by that host 329and used only by that host, although exceptions exist 330as noted later on this page. 331 332Normally, files containing private values, 333including the host key, sign key and identification parameters, 334are permitted root read/write-only; 335while others containing public values are permitted world readable. 336Alternatively, files containing private values can be encrypted 337and these files permitted world readable, 338which simplifies maintenance in shared file systems. 339Since uniqueness is insured by the hostname and 340file name extensions, the files for a NFS server and 341dependent clients can all be installed in the same shared directory. 342 343The recommended practice is to keep the file name extensions 344when installing a file and to install a soft link 345from the generic names specified elsewhere on this page 346to the generated files. 347This allows new file generations to be activated simply 348by changing the link. 349If a link is present, ntpd follows it to the file name 350to extract the filestamp. 351If a link is not present, 352@code{ntpd(1ntpdmdoc)} 353extracts the filestamp from the file itself. 354This allows clients to verify that the file and generation times 355are always current. 356The 357@code{ntp-keygen} 358program uses the same timestamp extension for all files generated 359at one time, so each generation is distinct and can be readily 360recognized in monitoring data. 361@subsubsection Running the program 362The safest way to run the 363@code{ntp-keygen} 364program is logged in directly as root. 365The recommended procedure is change to the keys directory, 366usually 367@file{/usr/local/etc}, 368then run the program. 369When run for the first time, 370or if all 371@code{ntpkey} 372files have been removed, 373the program generates a RSA host key file and matching RSA-MD5 certificate file, 374which is all that is necessary in many cases. 375The program also generates soft links from the generic names 376to the respective files. 377If run again, the program uses the same host key file, 378but generates a new certificate file and link. 379 380The host key is used to encrypt the cookie when required and so must be RSA type. 381By default, the host key is also the sign key used to encrypt signatures. 382When necessary, a different sign key can be specified and this can be 383either RSA or DSA type. 384By default, the message digest type is MD5, but any combination 385of sign key type and message digest type supported by the OpenSSL library 386can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 387and RIPE160 message digest algorithms. 388However, the scheme specified in the certificate must be compatible 389with the sign key. 390Certificates using any digest algorithm are compatible with RSA sign keys; 391however, only SHA and SHA1 certificates are compatible with DSA sign keys. 392 393Private/public key files and certificates are compatible with 394other OpenSSL applications and very likely other libraries as well. 395Certificates or certificate requests derived from them should be compatible 396with extant industry practice, although some users might find 397the interpretation of X509v3 extension fields somewhat liberal. 398However, the identification parameter files, although encoded 399as the other files, are probably not compatible with anything other than Autokey. 400 401Running the program as other than root and using the Unix 402@code{su} 403command 404to assume root may not work properly, since by default the OpenSSL library 405looks for the random seed file 406@code{.rnd} 407in the user home directory. 408However, there should be only one 409@code{.rnd}, 410most conveniently 411in the root directory, so it is convenient to define the 412@code{$RANDFILE} 413environment variable used by the OpenSSL library as the path to 414@code{/.rnd}. 415 416Installing the keys as root might not work in NFS-mounted 417shared file systems, as NFS clients may not be able to write 418to the shared keys directory, even as root. 419In this case, NFS clients can specify the files in another 420directory such as 421@file{/etc} 422using the 423@code{keysdir} 424command. 425There is no need for one client to read the keys and certificates 426of other clients or servers, as these data are obtained automatically 427by the Autokey protocol. 428 429Ordinarily, cryptographic files are generated by the host that uses them, 430but it is possible for a trusted agent (TA) to generate these files 431for other hosts; however, in such cases files should always be encrypted. 432The subject name and trusted name default to the hostname 433of the host generating the files, but can be changed by command line options. 434It is convenient to designate the owner name and trusted name 435as the subject and issuer fields, respectively, of the certificate. 436The owner name is also used for the host and sign key files, 437while the trusted name is used for the identity files. 438seconds. 439seconds. 440 441s Trusted Hosts and Groups 442Each cryptographic configuration involves selection of a signature scheme 443and identification scheme, called a cryptotype, 444as explained in the 445@ref{Authentication Options} 446section of 447@code{ntp.conf(5)}. 448The default cryptotype uses RSA encryption, MD5 message digest 449and TC identification. 450First, configure a NTP subnet including one or more low-stratum 451trusted hosts from which all other hosts derive synchronization 452directly or indirectly. 453Trusted hosts have trusted certificates; 454all other hosts have nontrusted certificates. 455These hosts will automatically and dynamically build authoritative 456certificate trails to one or more trusted hosts. 457A trusted group is the set of all hosts that have, directly or indirectly, 458a certificate trail ending at a trusted host. 459The trail is defined by static configuration file entries 460or dynamic means described on the 461@ref{Automatic NTP Configuration Options} 462section of 463@code{ntp.conf(5)}. 464 465On each trusted host as root, change to the keys directory. 466To insure a fresh fileset, remove all 467@code{ntpkey} 468files. 469Then run 470@code{ntp-keygen} 471@code{-T} 472to generate keys and a trusted certificate. 473On all other hosts do the same, but leave off the 474@code{-T} 475flag to generate keys and nontrusted certificates. 476When complete, start the NTP daemons beginning at the lowest stratum 477and working up the tree. 478It may take some time for Autokey to instantiate the certificate trails 479throughout the subnet, but setting up the environment is completely automatic. 480 481If it is necessary to use a different sign key or different digest/signature 482scheme than the default, run 483@code{ntp-keygen} 484with the 485@code{-S} @kbd{type} 486option, where 487@kbd{type} 488is either 489@code{RSA} 490or 491@code{DSA}. 492The most often need to do this is when a DSA-signed certificate is used. 493If it is necessary to use a different certificate scheme than the default, 494run 495@code{ntp-keygen} 496with the 497@code{-c} @kbd{scheme} 498option and selected 499@kbd{scheme} 500as needed. 501f 502@code{ntp-keygen} 503is run again without these options, it generates a new certificate 504using the same scheme and sign key. 505 506After setting up the environment it is advisable to update certificates 507from time to time, if only to extend the validity interval. 508Simply run 509@code{ntp-keygen} 510with the same flags as before to generate new certificates 511using existing keys. 512However, if the host or sign key is changed, 513@code{ntpd(1ntpdmdoc)} 514should be restarted. 515When 516@code{ntpd(1ntpdmdoc)} 517is restarted, it loads any new files and restarts the protocol. 518Other dependent hosts will continue as usual until signatures are refreshed, 519at which time the protocol is restarted. 520@subsubsection Identity Schemes 521As mentioned on the Autonomous Authentication page, 522the default TC identity scheme is vulnerable to a middleman attack. 523However, there are more secure identity schemes available, 524including PC, IFF, GQ and MV described on the 525"Identification Schemes" 526page 527(maybe available at 528@code{http://www.eecis.udel.edu/%7emills/keygen.html}). 529These schemes are based on a TA, one or more trusted hosts 530and some number of nontrusted hosts. 531Trusted hosts prove identity using values provided by the TA, 532while the remaining hosts prove identity using values provided 533by a trusted host and certificate trails that end on that host. 534The name of a trusted host is also the name of its sugroup 535and also the subject and issuer name on its trusted certificate. 536The TA is not necessarily a trusted host in this sense, but often is. 537 538In some schemes there are separate keys for servers and clients. 539A server can also be a client of another server, 540but a client can never be a server for another client. 541In general, trusted hosts and nontrusted hosts that operate 542as both server and client have parameter files that contain 543both server and client keys. 544Hosts that operate 545only as clients have key files that contain only client keys. 546 547The PC scheme supports only one trusted host in the group. 548On trusted host alice run 549@code{ntp-keygen} 550@code{-P} 551@code{-p} @kbd{password} 552to generate the host key file 553@file{ntpkey_RSAkey_}@kbd{alice.filestamp} 554and trusted private certificate file 555@file{ntpkey_RSA-MD5_cert_}@kbd{alice.filestamp}. 556Copy both files to all group hosts; 557they replace the files which would be generated in other schemes. 558On each host bob install a soft link from the generic name 559@file{ntpkey_host_}@kbd{bob} 560to the host key file and soft link 561@file{ntpkey_cert_}@kbd{bob} 562to the private certificate file. 563Note the generic links are on bob, but point to files generated 564by trusted host alice. 565In this scheme it is not possible to refresh 566either the keys or certificates without copying them 567to all other hosts in the group. 568 569For the IFF scheme proceed as in the TC scheme to generate keys 570and certificates for all group hosts, then for every trusted host in the group, 571generate the IFF parameter file. 572On trusted host alice run 573@code{ntp-keygen} 574@code{-T} 575@code{-I} 576@code{-p} @kbd{password} 577to produce her parameter file 578@file{ntpkey_IFFpar_}@kbd{alice.filestamp}, 579which includes both server and client keys. 580Copy this file to all group hosts that operate as both servers 581and clients and install a soft link from the generic 582@file{ntpkey_iff_}@kbd{alice} 583to this file. 584If there are no hosts restricted to operate only as clients, 585there is nothing further to do. 586As the IFF scheme is independent 587of keys and certificates, these files can be refreshed as needed. 588 589If a rogue client has the parameter file, it could masquerade 590as a legitimate server and present a middleman threat. 591To eliminate this threat, the client keys can be extracted 592from the parameter file and distributed to all restricted clients. 593After generating the parameter file, on alice run 594@code{ntp-keygen} 595@code{-e} 596and pipe the output to a file or mail program. 597Copy or mail this file to all restricted clients. 598On these clients install a soft link from the generic 599@file{ntpkey_iff_}@kbd{alice} 600to this file. 601To further protect the integrity of the keys, 602each file can be encrypted with a secret password. 603 604For the GQ scheme proceed as in the TC scheme to generate keys 605and certificates for all group hosts, then for every trusted host 606in the group, generate the IFF parameter file. 607On trusted host alice run 608@code{ntp-keygen} 609@code{-T} 610@code{-G} 611@code{-p} @kbd{password} 612to produce her parameter file 613@file{ntpkey_GQpar_}@kbd{alice.filestamp}, 614which includes both server and client keys. 615Copy this file to all group hosts and install a soft link 616from the generic 617@file{ntpkey_gq_}@kbd{alice} 618to this file. 619In addition, on each host bob install a soft link 620from generic 621@file{ntpkey_gq_}@kbd{bob} 622to this file. 623As the GQ scheme updates the GQ parameters file and certificate 624at the same time, keys and certificates can be regenerated as needed. 625 626For the MV scheme, proceed as in the TC scheme to generate keys 627and certificates for all group hosts. 628For illustration assume trish is the TA, alice one of several trusted hosts 629and bob one of her clients. 630On TA trish run 631@code{ntp-keygen} 632@code{-V} @kbd{n} 633@code{-p} @kbd{password}, 634where 635@kbd{n} 636is the number of revokable keys (typically 5) to produce 637the parameter file 638@file{ntpkeys_MVpar_}@kbd{trish.filestamp} 639and client key files 640@file{ntpkeys_MVkeyd_}@kbd{trish.filestamp} 641where 642@kbd{d} 643is the key number (0 < 644@kbd{d} 645< 646@kbd{n}). 647Copy the parameter file to alice and install a soft link 648from the generic 649@file{ntpkey_mv_}@kbd{alice} 650to this file. 651Copy one of the client key files to alice for later distribution 652to her clients. 653It doesn't matter which client key file goes to alice, 654since they all work the same way. 655Alice copies the client key file to all of her cliens. 656On client bob install a soft link from generic 657@file{ntpkey_mvkey_}@kbd{bob} 658to the client key file. 659As the MV scheme is independent of keys and certificates, 660these files can be refreshed as needed. 661@subsubsection Command Line Options 662@table @asis 663@item @code{-c} @kbd{scheme} 664Select certificate message digest/signature encryption scheme. 665The 666@kbd{scheme} 667can be one of the following: 668. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , 669or 670@code{DSA-SHA1}. 671Note that RSA schemes must be used with a RSA sign key and DSA 672schemes must be used with a DSA sign key. 673The default without this option is 674@code{RSA-MD5}. 675@item @code{-d} 676Enable debugging. 677This option displays the cryptographic data produced in eye-friendly billboards. 678@item @code{-e} 679Write the IFF client keys to the standard output. 680This is intended for automatic key distribution by mail. 681@item @code{-G} 682Generate parameters and keys for the GQ identification scheme, 683obsoleting any that may exist. 684@item @code{-g} 685Generate keys for the GQ identification scheme 686using the existing GQ parameters. 687If the GQ parameters do not yet exist, create them first. 688@item @code{-H} 689Generate new host keys, obsoleting any that may exist. 690@item @code{-I} 691Generate parameters for the IFF identification scheme, 692obsoleting any that may exist. 693@item @code{-i} @kbd{name} 694Set the suject name to 695@kbd{name}. 696This is used as the subject field in certificates 697and in the file name for host and sign keys. 698@item @code{-M} 699Generate MD5 keys, obsoleting any that may exist. 700@item @code{-P} 701Generate a private certificate. 702By default, the program generates public certificates. 703@item @code{-p} @kbd{password} 704Encrypt generated files containing private data with 705@kbd{password} 706and the DES-CBC algorithm. 707@item @code{-q} 708Set the password for reading files to password. 709@item @code{-S} @code{[@code{RSA} | @code{DSA}]} 710Generate a new sign key of the designated type, 711obsoleting any that may exist. 712By default, the program uses the host key as the sign key. 713@item @code{-s} @kbd{name} 714Set the issuer name to 715@kbd{name}. 716This is used for the issuer field in certificates 717and in the file name for identity files. 718@item @code{-T} 719Generate a trusted certificate. 720By default, the program generates a non-trusted certificate. 721@item @code{-V} @kbd{nkeys} 722Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. 723@end table 724@subsubsection Random Seed File 725All cryptographically sound key generation schemes must have means 726to randomize the entropy seed used to initialize 727the internal pseudo-random number generator used 728by the library routines. 729The OpenSSL library uses a designated random seed file for this purpose. 730The file must be available when starting the NTP daemon and 731@code{ntp-keygen} 732program. 733If a site supports OpenSSL or its companion OpenSSH, 734it is very likely that means to do this are already available. 735 736It is important to understand that entropy must be evolved 737for each generation, for otherwise the random number sequence 738would be predictable. 739Various means dependent on external events, such as keystroke intervals, 740can be used to do this and some systems have built-in entropy sources. 741Suitable means are described in the OpenSSL software documentation, 742but are outside the scope of this page. 743 744The entropy seed used by the OpenSSL library is contained in a file, 745usually called 746@code{.rnd}, 747which must be available when starting the NTP daemon 748or the 749@code{ntp-keygen} 750program. 751The NTP daemon will first look for the file 752using the path specified by the 753@code{randfile} 754subcommand of the 755@code{crypto} 756configuration command. 757If not specified in this way, or when starting the 758@code{ntp-keygen} 759program, 760the OpenSSL library will look for the file using the path specified 761by the 762.Ev RANDFILE 763environment variable in the user home directory, 764whether root or some other user. 765If the 766.Ev RANDFILE 767environment variable is not present, 768the library will look for the 769@code{.rnd} 770file in the user home directory. 771If the file is not available or cannot be written, 772the daemon exits with a message to the system log and the program 773exits with a suitable error message. 774@subsubsection Cryptographic Data Files 775All other file formats begin with two lines. 776The first contains the file name, including the generated host name 777and filestamp. 778The second contains the datestamp in conventional Unix date format. 779Lines beginning with # are considered comments and ignored by the 780@code{ntp-keygen} 781program and 782@code{ntpd(1ntpdmdoc)} 783daemon. 784Cryptographic values are encoded first using ASN.1 rules, 785then encrypted if necessary, and finally written PEM-encoded 786printable ASCII format preceded and followed by MIME content identifier lines. 787 788The format of the symmetric keys file is somewhat different 789than the other files in the interest of backward compatibility. 790Since DES-CBC is deprecated in NTPv4, the only key format of interest 791is MD5 alphanumeric strings. 792Following hte heard the keys are 793entered one per line in the format 794@example 795@kbd{keyno} @kbd{type} @kbd{key} 796@end example 797where 798@kbd{keyno} 799is a positive integer in the range 1-65,535, 800@kbd{type} 801is the string MD5 defining the key format and 802@kbd{key} 803is the key itself, 804which is a printable ASCII string 16 characters or less in length. 805Each character is chosen from the 93 printable characters 806in the range 0x21 through 0x7f excluding space and the 807@quoteleft{}#@quoteright{} 808character. 809 810Note that the keys used by the 811@code{ntpq(1ntpqmdoc)} 812and 813@code{ntpdc(1ntpdcmdoc)} 814programs 815are checked against passwords requested by the programs 816and entered by hand, so it is generally appropriate to specify these keys 817in human readable ASCII format. 818 819The 820@code{ntp-keygen} 821program generates a MD5 symmetric keys file 822@file{ntpkey_MD5key_}@kbd{hostname.filestamp}. 823Since the file contains private shared keys, 824it should be visible only to root and distributed by secure means 825to other subnet hosts. 826The NTP daemon loads the file 827@file{ntp.keys}, 828so 829@code{ntp-keygen} 830installs a soft link from this name to the generated file. 831Subsequently, similar soft links must be installed by manual 832or automated means on the other subnet hosts. 833While this file is not used with the Autokey Version 2 protocol, 834it is needed to authenticate some remote configuration commands 835used by the 836@code{ntpq(1ntpqmdoc)} 837and 838@code{ntpdc(1ntpdcmdoc)} 839utilities. 840 841This section was generated by @strong{AutoGen}, 842using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp-keygen} program. 843This software is released under the NTP license, <http://ntp.org/license>. 844 845@menu 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 871@end menu 872 873@node ntp-keygen usage 874@subsection ntp-keygen help/usage (@option{--help}) 875@cindex ntp-keygen help 876 877This is the automatically generated usage text for ntp-keygen. 878 879The 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 881the 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 884used to select the program, defaulting to @file{more}. Both will exit 885with a status code of 0. 886 887@exampleindent 0 888@example 889ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.8p9 890Usage: 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: 894 256 to 2048 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: 910 256 to 2048 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 926 927Options are specified by doubled hyphens and their name or by a single 928hyphen and the flag character. 929 930 931The following option preset mechanisms are supported: 932 - reading file $HOME/.ntprc 933 - reading file ./.ntprc 934 - examining environment variables named NTP_KEYGEN_* 935 936Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> 937@end example 938@exampleindent 4 939 940@node ntp-keygen imbits 941@subsection imbits option (-b) 942@cindex ntp-keygen-imbits 943 944This is the ``identity modulus bits'' option. 945This option takes a number argument @file{imbits}. 946 947@noindent 948This option has some usage constraints. It: 949@itemize @bullet 950@item 951must be compiled in by defining @code{AUTOKEY} during the compilation. 952@end itemize 953 954The 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 958 959This is the ``certificate scheme'' option. 960This option takes a string argument @file{scheme}. 961 962@noindent 963This option has some usage constraints. It: 964@itemize @bullet 965@item 966must be compiled in by defining @code{AUTOKEY} during the compilation. 967@end itemize 968 969scheme is one of 970RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, 971DSA-SHA, or DSA-SHA1. 972 973Select the certificate message digest/signature encryption scheme. 974Note that RSA schemes must be used with a RSA sign key and DSA 975schemes must be used with a DSA sign key. The default without 976this option is RSA-MD5. 977@node ntp-keygen cipher 978@subsection cipher option (-C) 979@cindex ntp-keygen-cipher 980 981This is the ``privatekey cipher'' option. 982This option takes a string argument @file{cipher}. 983 984@noindent 985This option has some usage constraints. It: 986@itemize @bullet 987@item 988must be compiled in by defining @code{AUTOKEY} during the compilation. 989@end itemize 990 991Select the cipher which is used to encrypt the files containing 992private keys. The default is three-key triple DES in CBC mode, 993equivalent to "@code{-C des-ede3-cbc". The openssl tool lists ciphers 994available in "@code{openssl -h}" output. 995@node ntp-keygen id-key 996@subsection id-key option (-e) 997@cindex ntp-keygen-id-key 998 999This is the ``write iff or gq identity keys'' option. 1000 1001@noindent 1002This option has some usage constraints. It: 1003@itemize @bullet 1004@item 1005must be compiled in by defining @code{AUTOKEY} during the compilation. 1006@end itemize 1007 1008Write the IFF or GQ client keys to the standard output. This is 1009intended for automatic key distribution by mail. 1010@node ntp-keygen gq-params 1011@subsection gq-params option (-G) 1012@cindex ntp-keygen-gq-params 1013 1014This is the ``generate gq parameters and keys'' option. 1015 1016@noindent 1017This option has some usage constraints. It: 1018@itemize @bullet 1019@item 1020must be compiled in by defining @code{AUTOKEY} during the compilation. 1021@end itemize 1022 1023Generate parameters and keys for the GQ identification scheme, 1024obsoleting any that may exist. 1025@node ntp-keygen host-key 1026@subsection host-key option (-H) 1027@cindex ntp-keygen-host-key 1028 1029This is the ``generate rsa host key'' option. 1030 1031@noindent 1032This option has some usage constraints. It: 1033@itemize @bullet 1034@item 1035must be compiled in by defining @code{AUTOKEY} during the compilation. 1036@end itemize 1037 1038Generate new host keys, obsoleting any that may exist. 1039@node ntp-keygen iffkey 1040@subsection iffkey option (-I) 1041@cindex ntp-keygen-iffkey 1042 1043This is the ``generate iff parameters'' option. 1044 1045@noindent 1046This option has some usage constraints. It: 1047@itemize @bullet 1048@item 1049must be compiled in by defining @code{AUTOKEY} during the compilation. 1050@end itemize 1051 1052Generate parameters for the IFF identification scheme, obsoleting 1053any that may exist. 1054@node ntp-keygen ident 1055@subsection ident option (-i) 1056@cindex ntp-keygen-ident 1057 1058This is the ``set autokey group name'' option. 1059This option takes a string argument @file{group}. 1060 1061@noindent 1062This option has some usage constraints. It: 1063@itemize @bullet 1064@item 1065must be compiled in by defining @code{AUTOKEY} during the compilation. 1066@end itemize 1067 1068Set the optional Autokey group name to name. This is used in 1069the file name of IFF, GQ, and MV client parameters files. In 1070that role, the default is the host name if this option is not 1071provided. The group name, if specified using @code{-i/--ident} or 1072using @code{-s/--subject-name} following an '@code{@}' character, 1073is also a part of the self-signed host certificate's subject and 1074issuer 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 1080 1081This is the ``set certificate lifetime'' option. 1082This option takes a number argument @file{lifetime}. 1083 1084@noindent 1085This option has some usage constraints. It: 1086@itemize @bullet 1087@item 1088must be compiled in by defining @code{AUTOKEY} during the compilation. 1089@end itemize 1090 1091Set the certificate expiration to lifetime days from now. 1092@node ntp-keygen md5key 1093@subsection md5key option (-M) 1094@cindex ntp-keygen-md5key 1095 1096This is the ``generate md5 keys'' option. 1097Generate MD5 keys, obsoleting any that may exist. 1098@node ntp-keygen modulus 1099@subsection modulus option (-m) 1100@cindex ntp-keygen-modulus 1101 1102This is the ``modulus'' option. 1103This option takes a number argument @file{modulus}. 1104 1105@noindent 1106This option has some usage constraints. It: 1107@itemize @bullet 1108@item 1109must be compiled in by defining @code{AUTOKEY} during the compilation. 1110@end itemize 1111 1112The 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 1116 1117This is the ``generate pc private certificate'' option. 1118 1119@noindent 1120This option has some usage constraints. It: 1121@itemize @bullet 1122@item 1123must be compiled in by defining @code{AUTOKEY} during the compilation. 1124@end itemize 1125 1126Generate a private certificate. By default, the program generates 1127public certificates. 1128@node ntp-keygen password 1129@subsection password option (-p) 1130@cindex ntp-keygen-password 1131 1132This is the ``local private password'' option. 1133This option takes a string argument @file{passwd}. 1134 1135@noindent 1136This option has some usage constraints. It: 1137@itemize @bullet 1138@item 1139must be compiled in by defining @code{AUTOKEY} during the compilation. 1140@end itemize 1141 1142Local files containing private data are encrypted with the 1143DES-CBC algorithm and the specified password. The same password 1144must be specified to the local ntpd via the "crypto pw password" 1145configuration command. The default password is the local 1146hostname. 1147@node ntp-keygen export-passwd 1148@subsection export-passwd option (-q) 1149@cindex ntp-keygen-export-passwd 1150 1151This is the ``export iff or gq group keys with password'' option. 1152This option takes a string argument @file{passwd}. 1153 1154@noindent 1155This option has some usage constraints. It: 1156@itemize @bullet 1157@item 1158must be compiled in by defining @code{AUTOKEY} during the compilation. 1159@end itemize 1160 1161Export IFF or GQ identity group keys to the standard output, 1162encrypted with the DES-CBC algorithm and the specified password. 1163The 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 1169 1170This is the ``generate sign key (rsa or dsa)'' option. 1171This option takes a string argument @file{sign}. 1172 1173@noindent 1174This option has some usage constraints. It: 1175@itemize @bullet 1176@item 1177must be compiled in by defining @code{AUTOKEY} during the compilation. 1178@end itemize 1179 1180Generate a new sign key of the designated type, obsoleting any 1181that may exist. By default, the program uses the host key as the 1182sign key. 1183@node ntp-keygen subject-name 1184@subsection subject-name option (-s) 1185@cindex ntp-keygen-subject-name 1186 1187This is the ``set host and optionally group name'' option. 1188This option takes a string argument @file{host@@group}. 1189 1190@noindent 1191This option has some usage constraints. It: 1192@itemize @bullet 1193@item 1194must be compiled in by defining @code{AUTOKEY} during the compilation. 1195@end itemize 1196 1197Set the Autokey host name, and optionally, group name specified 1198following an '@code{@}' character. The host name is used in the file 1199name of generated host and signing certificates, without the 1200group name. The host name, and if provided, group name are used 1201in @code{host@group} form for the host certificate's subject and issuer 1202fields. Specifying '@code{-s @group}' is allowed, and results in 1203leaving the host name unchanged while appending @code{@group} to the 1204subject and issuer fields, as with @code{-i group}. The group name, or 1205if not provided, the host name are also used in the file names 1206of 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 1210 1211This is the ``trusted certificate (tc scheme)'' option. 1212 1213@noindent 1214This option has some usage constraints. It: 1215@itemize @bullet 1216@item 1217must be compiled in by defining @code{AUTOKEY} during the compilation. 1218@end itemize 1219 1220Generate a trusted certificate. By default, the program generates 1221a non-trusted certificate. 1222@node ntp-keygen mv-params 1223@subsection mv-params option (-V) 1224@cindex ntp-keygen-mv-params 1225 1226This is the ``generate <num> mv parameters'' option. 1227This option takes a number argument @file{num}. 1228 1229@noindent 1230This option has some usage constraints. It: 1231@itemize @bullet 1232@item 1233must be compiled in by defining @code{AUTOKEY} during the compilation. 1234@end itemize 1235 1236Generate parameters and keys for the Mu-Varadharajan (MV) 1237identification scheme. 1238@node ntp-keygen mv-keys 1239@subsection mv-keys option (-v) 1240@cindex ntp-keygen-mv-keys 1241 1242This is the ``update <num> mv keys'' option. 1243This option takes a number argument @file{num}. 1244 1245@noindent 1246This option has some usage constraints. It: 1247@itemize @bullet 1248@item 1249must be compiled in by defining @code{AUTOKEY} during the compilation. 1250@end itemize 1251 1252This option has no @samp{doc} documentation. 1253 1254 1255@node ntp-keygen config 1256@subsection presetting/configuring ntp-keygen 1257 1258Any option that is not marked as @i{not presettable} may be preset by 1259loading 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 1260the options listed above in upper case and segmented with underscores. 1261The @code{NTP-KEYGEN} variable will be tokenized and parsed like 1262the command line. The remaining variables are tested for existence and their 1263values are treated like option arguments. 1264 1265 1266@noindent 1267@code{libopts} will search in 2 places for configuration files: 1268@itemize @bullet 1269@item 1270$HOME 1271@item 1272$PWD 1273@end itemize 1274The environment variables @code{HOME}, and @code{PWD} 1275are expanded and replaced when @file{ntp-keygen} runs. 1276For any of these that are plain files, they are simply processed. 1277For any that are directories, then a file named @file{.ntprc} is searched for 1278within that directory and processed. 1279 1280Configuration files may be in a wide variety of formats. 1281The basic format is an option name followed by a value (argument) on the 1282same line. Values may be separated from the option name with a colon, 1283equal sign or simply white space. Values may be continued across multiple 1284lines by escaping the newline with a backslash. 1285 1286Multiple programs may also share the same initialization file. 1287Common options are collected at the top, followed by program specific 1288segments. The segments are separated by lines like: 1289@example 1290[NTP-KEYGEN] 1291@end example 1292@noindent 1293or by 1294@example 1295<?program ntp-keygen> 1296@end example 1297@noindent 1298Do not mix these styles within one configuration file. 1299 1300Compound values and carefully constructed string values may also be 1301specified using XML syntax: 1302@example 1303<option-name> 1304 <sub-opt>...<...>...</sub-opt> 1305</option-name> 1306@end example 1307@noindent 1308yielding an @code{option-name.sub-opt} string value of 1309@example 1310"...<...>..." 1311@end example 1312@code{AutoOpts} does not track suboptions. You simply note that it is a 1313hierarchicly valued option. @code{AutoOpts} does provide a means for searching 1314the associated name/value pair list (see: optionFindValue). 1315 1316The command line options relating to configuration and/or usage help are: 1317 1318@subsubheading version (-) 1319 1320Print the program version to standard out, optionally with licensing 1321information, then exit 0. The optional argument specifies how much licensing 1322detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 1323Only the first letter of the argument is examined: 1324 1325@table @samp 1326@item version 1327Only print the version. This is the default. 1328@item copyright 1329Name the copyright usage licensing terms. 1330@item verbose 1331Print the full copyright usage licensing terms. 1332@end table 1333 1334@node ntp-keygen exit status 1335@subsection ntp-keygen exit status 1336 1337One of the following exit values will be returned: 1338@table @samp 1339@item 0 (EXIT_SUCCESS) 1340Successful program execution. 1341@item 1 (EXIT_FAILURE) 1342The operation failed or the command syntax was not valid. 1343@item 66 (EX_NOINPUT) 1344A specified configuration file could not be loaded. 1345@item 70 (EX_SOFTWARE) 1346libopts had an internal operational error. Please report 1347it to autogen-users@@lists.sourceforge.net. Thank you. 1348@end table 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 1355