ntp-keygen.1ntp-keygenman revision 309007
1.de1 NOP 2. it 1 an-trap 3. if \\n[.$] \,\\$*\/ 4.. 5.ie t \ 6.ds B-Font [CB] 7.ds I-Font [CI] 8.ds R-Font [CR] 9.el \ 10.ds B-Font B 11.ds I-Font I 12.ds R-Font R 13.TH ntp-keygen 1ntp-keygenman "21 Nov 2016" "ntp (4.2.8p9)" "User Commands" 14.\" 15.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-psaWZm/ag-DsaOYm) 16.\" 17.\" It has been AutoGen-ed November 21, 2016 at 08:03:41 AM by AutoGen 5.18.5 18.\" From the definitions ntp-keygen-opts.def 19.\" and the template file agman-cmd.tpl 20.SH NAME 21\f\*[B-Font]ntp-keygen\fP 22\- Create a NTP host key 23.SH SYNOPSIS 24\f\*[B-Font]ntp-keygen\fP 25.\" Mixture of short (flag) options and long options 26[\f\*[B-Font]\-flags\f[]] 27[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] 28[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] 29.sp \n(Ppu 30.ne 2 31 32All arguments must be options. 33.sp \n(Ppu 34.ne 2 35 36.SH DESCRIPTION 37This program generates cryptographic data files used by the NTPv4 38authentication and identification schemes. 39It generates MD5 key files used in symmetric key cryptography. 40In addition, if the OpenSSL software library has been installed, 41it generates keys, certificate and identity files used in public key 42cryptography. 43These files are used for cookie encryption, 44digital signature and challenge/response identification algorithms 45compatible with the Internet standard security infrastructure. 46.sp \n(Ppu 47.ne 2 48 49All files are in PEM-encoded printable ASCII format, 50so they can be embedded as MIME attachments in mail to other sites 51and certificate authorities. 52By default, files are not encrypted. 53.sp \n(Ppu 54.ne 2 55 56When used to generate message digest keys, the program produces a file 57containing ten pseudo-random printable ASCII strings suitable for the 58MD5 message digest algorithm included in the distribution. 59If the OpenSSL library is installed, it produces an additional ten 60hex-encoded random bit strings suitable for the SHA1 and other message 61digest algorithms. 62The message digest keys file must be distributed and stored 63using secure means beyond the scope of NTP itself. 64Besides the keys used for ordinary NTP associations, additional keys 65can be defined as passwords for the 66\fCntpq\f[]\fR(1ntpqmdoc)\f[] 67and 68\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 69utility programs. 70.sp \n(Ppu 71.ne 2 72 73The remaining generated files are compatible with other OpenSSL 74applications and other Public Key Infrastructure (PKI) resources. 75Certificates generated by this program are compatible with extant 76industry practice, although some users might find the interpretation of 77X509v3 extension fields somewhat liberal. 78However, the identity keys are probably not compatible with anything 79other than Autokey. 80.sp \n(Ppu 81.ne 2 82 83Some files used by this program are encrypted using a private password. 84The 85\f\*[B-Font]\-p\f[] 86option specifies the password for local encrypted files and the 87\f\*[B-Font]\-q\f[] 88option the password for encrypted files sent to remote sites. 89If no password is specified, the host name returned by the Unix 90\fBgethostname\f[]\fR()\f[] 91function, normally the DNS name of the host is used. 92.sp \n(Ppu 93.ne 2 94 95The 96\f\*[I-Font]pw\f[] 97option of the 98\f\*[I-Font]crypto\f[] 99configuration command specifies the read 100password for previously encrypted local files. 101This must match the local password used by this program. 102If not specified, the host name is used. 103Thus, if files are generated by this program without password, 104they can be read back by 105\f\*[I-Font]ntpd\f[] 106without password but only on the same host. 107.sp \n(Ppu 108.ne 2 109 110Normally, encrypted files for each host are generated by that host and 111used only by that host, although exceptions exist as noted later on 112this page. 113The symmetric keys file, normally called 114\f\*[I-Font]ntp.keys\f[], 115is usually installed in 116\fI/etc\f[]. 117Other files and links are usually installed in 118\fI/usr/local/etc\f[], 119which is normally in a shared filesystem in 120NFS-mounted networks and cannot be changed by shared clients. 121The location of the keys directory can be changed by the 122\f\*[I-Font]keysdir\f[] 123configuration command in such cases. 124Normally, this is in 125\fI/etc\f[]. 126.sp \n(Ppu 127.ne 2 128 129This program directs commentary and error messages to the standard 130error stream 131\f\*[I-Font]stderr\f[] 132and remote files to the standard output stream 133\f\*[I-Font]stdout\f[] 134where they can be piped to other applications or redirected to files. 135The names used for generated files and links all begin with the 136string 137\f\*[I-Font]ntpkey\f[] 138and include the file type, generating host and filestamp, 139as described in the 140\*[Lq]Cryptographic Data Files\*[Rq] 141section below. 142.SS Running the Program 143To test and gain experience with Autokey concepts, log in as root and 144change to the keys directory, usually 145\fI/usr/local/etc\f[] 146When run for the first time, or if all files with names beginning with 147\f\*[I-Font]ntpkey\f[] 148have been removed, use the 149\f\*[B-Font]ntp-keygen\fP 150command without arguments to generate a 151default RSA host key and matching RSA-MD5 certificate with expiration 152date one year hence. 153If run again without options, the program uses the 154existing keys and parameters and generates only a new certificate with 155new expiration date one year hence. 156.sp \n(Ppu 157.ne 2 158 159Run the command on as many hosts as necessary. 160Designate one of them as the trusted host (TH) using 161\f\*[B-Font]ntp-keygen\fP 162with the 163\f\*[B-Font]\-T\f[] 164option and configure it to synchronize from reliable Internet servers. 165Then configure the other hosts to synchronize to the TH directly or 166indirectly. 167A certificate trail is created when Autokey asks the immediately 168ascendant host towards the TH to sign its certificate, which is then 169provided to the immediately descendant host on request. 170All group hosts should have acyclic certificate trails ending on the TH. 171.sp \n(Ppu 172.ne 2 173 174The host key is used to encrypt the cookie when required and so must be 175RSA type. 176By default, the host key is also the sign key used to encrypt 177signatures. 178A different sign key can be assigned using the 179\f\*[B-Font]\-S\f[] 180option and this can be either RSA or DSA type. 181By default, the signature 182message digest type is MD5, but any combination of sign key type and 183message digest type supported by the OpenSSL library can be specified 184using the 185\f\*[B-Font]\-c\f[] 186option. 187The rules say cryptographic media should be generated with proventic 188filestamps, which means the host should already be synchronized before 189this program is run. 190This of course creates a chicken-and-egg problem 191when the host is started for the first time. 192Accordingly, the host time 193should be set by some other means, such as eyeball-and-wristwatch, at 194least so that the certificate lifetime is within the current year. 195After that and when the host is synchronized to a proventic source, the 196certificate should be re-generated. 197.sp \n(Ppu 198.ne 2 199 200Additional information on trusted groups and identity schemes is on the 201\*[Lq]Autokey Public-Key Authentication\*[Rq] 202page. 203.sp \n(Ppu 204.ne 2 205 206The 207\fCntpd\f[]\fR(1ntpdmdoc)\f[] 208configuration command 209\f\*[B-Font]crypto\f[] \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[] 210specifies the read password for previously encrypted files. 211The daemon expires on the spot if the password is missing 212or incorrect. 213For convenience, if a file has been previously encrypted, 214the default read password is the name of the host running 215the program. 216If the previous write password is specified as the host name, 217these files can be read by that host with no explicit password. 218.sp \n(Ppu 219.ne 2 220 221File names begin with the prefix 222\f\*[B-Font]ntpkey_\f[] 223and end with the postfix 224\f\*[I-Font]_hostname.filestamp\f[], 225where 226\f\*[I-Font]hostname\f[] 227is the owner name, usually the string returned 228by the Unix gethostname() routine, and 229\f\*[I-Font]filestamp\f[] 230is the NTP seconds when the file was generated, in decimal digits. 231This both guarantees uniqueness and simplifies maintenance 232procedures, since all files can be quickly removed 233by a 234\f\*[B-Font]rm\f[] \f\*[B-Font]ntpkey\&*\f[] 235command or all files generated 236at a specific time can be removed by a 237\f\*[B-Font]rm\f[] 238\f\*[I-Font]\&*filestamp\f[] 239command. 240To further reduce the risk of misconfiguration, 241the first two lines of a file contain the file name 242and generation date and time as comments. 243.sp \n(Ppu 244.ne 2 245 246All files are installed by default in the keys directory 247\fI/usr/local/etc\f[], 248which is normally in a shared filesystem 249in NFS-mounted networks. 250The actual location of the keys directory 251and each file can be overridden by configuration commands, 252but this is not recommended. 253Normally, the files for each host are generated by that host 254and used only by that host, although exceptions exist 255as noted later on this page. 256.sp \n(Ppu 257.ne 2 258 259Normally, files containing private values, 260including the host key, sign key and identification parameters, 261are permitted root read/write-only; 262while others containing public values are permitted world readable. 263Alternatively, files containing private values can be encrypted 264and these files permitted world readable, 265which simplifies maintenance in shared file systems. 266Since uniqueness is insured by the hostname and 267file name extensions, the files for a NFS server and 268dependent clients can all be installed in the same shared directory. 269.sp \n(Ppu 270.ne 2 271 272The recommended practice is to keep the file name extensions 273when installing a file and to install a soft link 274from the generic names specified elsewhere on this page 275to the generated files. 276This allows new file generations to be activated simply 277by changing the link. 278If a link is present, ntpd follows it to the file name 279to extract the filestamp. 280If a link is not present, 281\fCntpd\f[]\fR(1ntpdmdoc)\f[] 282extracts the filestamp from the file itself. 283This allows clients to verify that the file and generation times 284are always current. 285The 286\f\*[B-Font]ntp-keygen\fP 287program uses the same timestamp extension for all files generated 288at one time, so each generation is distinct and can be readily 289recognized in monitoring data. 290.SS Running the program 291The safest way to run the 292\f\*[B-Font]ntp-keygen\fP 293program is logged in directly as root. 294The recommended procedure is change to the keys directory, 295usually 296\fI/usr/local/etc\f[], 297then run the program. 298When run for the first time, 299or if all 300\f\*[B-Font]ntpkey\f[] 301files have been removed, 302the program generates a RSA host key file and matching RSA-MD5 certificate file, 303which is all that is necessary in many cases. 304The program also generates soft links from the generic names 305to the respective files. 306If run again, the program uses the same host key file, 307but generates a new certificate file and link. 308.sp \n(Ppu 309.ne 2 310 311The host key is used to encrypt the cookie when required and so must be RSA type. 312By default, the host key is also the sign key used to encrypt signatures. 313When necessary, a different sign key can be specified and this can be 314either RSA or DSA type. 315By default, the message digest type is MD5, but any combination 316of sign key type and message digest type supported by the OpenSSL library 317can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 318and RIPE160 message digest algorithms. 319However, the scheme specified in the certificate must be compatible 320with the sign key. 321Certificates using any digest algorithm are compatible with RSA sign keys; 322however, only SHA and SHA1 certificates are compatible with DSA sign keys. 323.sp \n(Ppu 324.ne 2 325 326Private/public key files and certificates are compatible with 327other OpenSSL applications and very likely other libraries as well. 328Certificates or certificate requests derived from them should be compatible 329with extant industry practice, although some users might find 330the interpretation of X509v3 extension fields somewhat liberal. 331However, the identification parameter files, although encoded 332as the other files, are probably not compatible with anything other than Autokey. 333.sp \n(Ppu 334.ne 2 335 336Running the program as other than root and using the Unix 337\f\*[B-Font]su\f[] 338command 339to assume root may not work properly, since by default the OpenSSL library 340looks for the random seed file 341\f\*[B-Font].rnd\f[] 342in the user home directory. 343However, there should be only one 344\f\*[B-Font].rnd\f[], 345most conveniently 346in the root directory, so it is convenient to define the 347\f\*[B-Font]$RANDFILE\f[] 348environment variable used by the OpenSSL library as the path to 349\f\*[B-Font]/.rnd\f[]. 350.sp \n(Ppu 351.ne 2 352 353Installing the keys as root might not work in NFS-mounted 354shared file systems, as NFS clients may not be able to write 355to the shared keys directory, even as root. 356In this case, NFS clients can specify the files in another 357directory such as 358\fI/etc\f[] 359using the 360\f\*[B-Font]keysdir\f[] 361command. 362There is no need for one client to read the keys and certificates 363of other clients or servers, as these data are obtained automatically 364by the Autokey protocol. 365.sp \n(Ppu 366.ne 2 367 368Ordinarily, cryptographic files are generated by the host that uses them, 369but it is possible for a trusted agent (TA) to generate these files 370for other hosts; however, in such cases files should always be encrypted. 371The subject name and trusted name default to the hostname 372of the host generating the files, but can be changed by command line options. 373It is convenient to designate the owner name and trusted name 374as the subject and issuer fields, respectively, of the certificate. 375The owner name is also used for the host and sign key files, 376while the trusted name is used for the identity files. 377.sp \n(Ppu 378.ne 2 379 380All files are installed by default in the keys directory 381\fI/usr/local/etc\f[], 382which is normally in a shared filesystem 383in NFS-mounted networks. 384The actual location of the keys directory 385and each file can be overridden by configuration commands, 386but this is not recommended. 387Normally, the files for each host are generated by that host 388and used only by that host, although exceptions exist 389as noted later on this page. 390.sp \n(Ppu 391.ne 2 392 393Normally, files containing private values, 394including the host key, sign key and identification parameters, 395are permitted root read/write-only; 396while others containing public values are permitted world readable. 397Alternatively, files containing private values can be encrypted 398and these files permitted world readable, 399which simplifies maintenance in shared file systems. 400Since uniqueness is insured by the hostname and 401file name extensions, the files for a NFS server and 402dependent clients can all be installed in the same shared directory. 403.sp \n(Ppu 404.ne 2 405 406The recommended practice is to keep the file name extensions 407when installing a file and to install a soft link 408from the generic names specified elsewhere on this page 409to the generated files. 410This allows new file generations to be activated simply 411by changing the link. 412If a link is present, ntpd follows it to the file name 413to extract the filestamp. 414If a link is not present, 415\fCntpd\f[]\fR(1ntpdmdoc)\f[] 416extracts the filestamp from the file itself. 417This allows clients to verify that the file and generation times 418are always current. 419The 420\f\*[B-Font]ntp-keygen\fP 421program uses the same timestamp extension for all files generated 422at one time, so each generation is distinct and can be readily 423recognized in monitoring data. 424.SS Running the program 425The safest way to run the 426\f\*[B-Font]ntp-keygen\fP 427program is logged in directly as root. 428The recommended procedure is change to the keys directory, 429usually 430\fI/usr/local/etc\f[], 431then run the program. 432When run for the first time, 433or if all 434\f\*[B-Font]ntpkey\f[] 435files have been removed, 436the program generates a RSA host key file and matching RSA-MD5 certificate file, 437which is all that is necessary in many cases. 438The program also generates soft links from the generic names 439to the respective files. 440If run again, the program uses the same host key file, 441but generates a new certificate file and link. 442.sp \n(Ppu 443.ne 2 444 445The host key is used to encrypt the cookie when required and so must be RSA type. 446By default, the host key is also the sign key used to encrypt signatures. 447When necessary, a different sign key can be specified and this can be 448either RSA or DSA type. 449By default, the message digest type is MD5, but any combination 450of sign key type and message digest type supported by the OpenSSL library 451can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 452and RIPE160 message digest algorithms. 453However, the scheme specified in the certificate must be compatible 454with the sign key. 455Certificates using any digest algorithm are compatible with RSA sign keys; 456however, only SHA and SHA1 certificates are compatible with DSA sign keys. 457.sp \n(Ppu 458.ne 2 459 460Private/public key files and certificates are compatible with 461other OpenSSL applications and very likely other libraries as well. 462Certificates or certificate requests derived from them should be compatible 463with extant industry practice, although some users might find 464the interpretation of X509v3 extension fields somewhat liberal. 465However, the identification parameter files, although encoded 466as the other files, are probably not compatible with anything other than Autokey. 467.sp \n(Ppu 468.ne 2 469 470Running the program as other than root and using the Unix 471\f\*[B-Font]su\f[] 472command 473to assume root may not work properly, since by default the OpenSSL library 474looks for the random seed file 475\f\*[B-Font].rnd\f[] 476in the user home directory. 477However, there should be only one 478\f\*[B-Font].rnd\f[], 479most conveniently 480in the root directory, so it is convenient to define the 481\f\*[B-Font]$RANDFILE\f[] 482environment variable used by the OpenSSL library as the path to 483\f\*[B-Font]/.rnd\f[]. 484.sp \n(Ppu 485.ne 2 486 487Installing the keys as root might not work in NFS-mounted 488shared file systems, as NFS clients may not be able to write 489to the shared keys directory, even as root. 490In this case, NFS clients can specify the files in another 491directory such as 492\fI/etc\f[] 493using the 494\f\*[B-Font]keysdir\f[] 495command. 496There is no need for one client to read the keys and certificates 497of other clients or servers, as these data are obtained automatically 498by the Autokey protocol. 499.sp \n(Ppu 500.ne 2 501 502Ordinarily, cryptographic files are generated by the host that uses them, 503but it is possible for a trusted agent (TA) to generate these files 504for other hosts; however, in such cases files should always be encrypted. 505The subject name and trusted name default to the hostname 506of the host generating the files, but can be changed by command line options. 507It is convenient to designate the owner name and trusted name 508as the subject and issuer fields, respectively, of the certificate. 509The owner name is also used for the host and sign key files, 510while the trusted name is used for the identity files. 511seconds. 512seconds. 513s Trusted Hosts and Groups 514Each cryptographic configuration involves selection of a signature scheme 515and identification scheme, called a cryptotype, 516as explained in the 517\fIAuthentication\f[] \fIOptions\f[] 518section of 519\fCntp.conf\f[]\fR(5)\f[]. 520The default cryptotype uses RSA encryption, MD5 message digest 521and TC identification. 522First, configure a NTP subnet including one or more low-stratum 523trusted hosts from which all other hosts derive synchronization 524directly or indirectly. 525Trusted hosts have trusted certificates; 526all other hosts have nontrusted certificates. 527These hosts will automatically and dynamically build authoritative 528certificate trails to one or more trusted hosts. 529A trusted group is the set of all hosts that have, directly or indirectly, 530a certificate trail ending at a trusted host. 531The trail is defined by static configuration file entries 532or dynamic means described on the 533\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[] 534section of 535\fCntp.conf\f[]\fR(5)\f[]. 536.sp \n(Ppu 537.ne 2 538 539On each trusted host as root, change to the keys directory. 540To insure a fresh fileset, remove all 541\f\*[B-Font]ntpkey\f[] 542files. 543Then run 544\f\*[B-Font]ntp-keygen\fP 545\f\*[B-Font]\-T\f[] 546to generate keys and a trusted certificate. 547On all other hosts do the same, but leave off the 548\f\*[B-Font]\-T\f[] 549flag to generate keys and nontrusted certificates. 550When complete, start the NTP daemons beginning at the lowest stratum 551and working up the tree. 552It may take some time for Autokey to instantiate the certificate trails 553throughout the subnet, but setting up the environment is completely automatic. 554.sp \n(Ppu 555.ne 2 556 557If it is necessary to use a different sign key or different digest/signature 558scheme than the default, run 559\f\*[B-Font]ntp-keygen\fP 560with the 561\f\*[B-Font]\-S\f[] \f\*[I-Font]type\f[] 562option, where 563\f\*[I-Font]type\f[] 564is either 565\f\*[B-Font]RSA\f[] 566or 567\f\*[B-Font]DSA\f[]. 568The most often need to do this is when a DSA-signed certificate is used. 569If it is necessary to use a different certificate scheme than the default, 570run 571\f\*[B-Font]ntp-keygen\fP 572with the 573\f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[] 574option and selected 575\f\*[I-Font]scheme\f[] 576as needed. 577f 578\f\*[B-Font]ntp-keygen\fP 579is run again without these options, it generates a new certificate 580using the same scheme and sign key. 581.sp \n(Ppu 582.ne 2 583 584After setting up the environment it is advisable to update certificates 585from time to time, if only to extend the validity interval. 586Simply run 587\f\*[B-Font]ntp-keygen\fP 588with the same flags as before to generate new certificates 589using existing keys. 590However, if the host or sign key is changed, 591\fCntpd\f[]\fR(1ntpdmdoc)\f[] 592should be restarted. 593When 594\fCntpd\f[]\fR(1ntpdmdoc)\f[] 595is restarted, it loads any new files and restarts the protocol. 596Other dependent hosts will continue as usual until signatures are refreshed, 597at which time the protocol is restarted. 598.SS Identity Schemes 599As mentioned on the Autonomous Authentication page, 600the default TC identity scheme is vulnerable to a middleman attack. 601However, there are more secure identity schemes available, 602including PC, IFF, GQ and MV described on the 603"Identification Schemes" 604page 605(maybe available at 606\f[C]http://www.eecis.udel.edu/%7emills/keygen.html\f[]). 607These schemes are based on a TA, one or more trusted hosts 608and some number of nontrusted hosts. 609Trusted hosts prove identity using values provided by the TA, 610while the remaining hosts prove identity using values provided 611by a trusted host and certificate trails that end on that host. 612The name of a trusted host is also the name of its sugroup 613and also the subject and issuer name on its trusted certificate. 614The TA is not necessarily a trusted host in this sense, but often is. 615.sp \n(Ppu 616.ne 2 617 618In some schemes there are separate keys for servers and clients. 619A server can also be a client of another server, 620but a client can never be a server for another client. 621In general, trusted hosts and nontrusted hosts that operate 622as both server and client have parameter files that contain 623both server and client keys. 624Hosts that operate 625only as clients have key files that contain only client keys. 626.sp \n(Ppu 627.ne 2 628 629The PC scheme supports only one trusted host in the group. 630On trusted host alice run 631\f\*[B-Font]ntp-keygen\fP 632\f\*[B-Font]\-P\f[] 633\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] 634to generate the host key file 635\fIntpkey_RSAkey_\f[]\f\*[I-Font]alice.filestamp\f[] 636and trusted private certificate file 637\fIntpkey_RSA-MD5_cert_\f[]\f\*[I-Font]alice.filestamp\f[]. 638Copy both files to all group hosts; 639they replace the files which would be generated in other schemes. 640On each host bob install a soft link from the generic name 641\fIntpkey_host_\f[]\f\*[I-Font]bob\f[] 642to the host key file and soft link 643\fIntpkey_cert_\f[]\f\*[I-Font]bob\f[] 644to the private certificate file. 645Note the generic links are on bob, but point to files generated 646by trusted host alice. 647In this scheme it is not possible to refresh 648either the keys or certificates without copying them 649to all other hosts in the group. 650.sp \n(Ppu 651.ne 2 652 653For the IFF scheme proceed as in the TC scheme to generate keys 654and certificates for all group hosts, then for every trusted host in the group, 655generate the IFF parameter file. 656On trusted host alice run 657\f\*[B-Font]ntp-keygen\fP 658\f\*[B-Font]\-T\f[] 659\f\*[B-Font]\-I\f[] 660\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] 661to produce her parameter file 662\fIntpkey_IFFpar_\f[]\f\*[I-Font]alice.filestamp\f[], 663which includes both server and client keys. 664Copy this file to all group hosts that operate as both servers 665and clients and install a soft link from the generic 666\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[] 667to this file. 668If there are no hosts restricted to operate only as clients, 669there is nothing further to do. 670As the IFF scheme is independent 671of keys and certificates, these files can be refreshed as needed. 672.sp \n(Ppu 673.ne 2 674 675If a rogue client has the parameter file, it could masquerade 676as a legitimate server and present a middleman threat. 677To eliminate this threat, the client keys can be extracted 678from the parameter file and distributed to all restricted clients. 679After generating the parameter file, on alice run 680\f\*[B-Font]ntp-keygen\fP 681\f\*[B-Font]\-e\f[] 682and pipe the output to a file or mail program. 683Copy or mail this file to all restricted clients. 684On these clients install a soft link from the generic 685\fIntpkey_iff_\f[]\f\*[I-Font]alice\f[] 686to this file. 687To further protect the integrity of the keys, 688each file can be encrypted with a secret password. 689.sp \n(Ppu 690.ne 2 691 692For the GQ scheme proceed as in the TC scheme to generate keys 693and certificates for all group hosts, then for every trusted host 694in the group, generate the IFF parameter file. 695On trusted host alice run 696\f\*[B-Font]ntp-keygen\fP 697\f\*[B-Font]\-T\f[] 698\f\*[B-Font]\-G\f[] 699\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] 700to produce her parameter file 701\fIntpkey_GQpar_\f[]\f\*[I-Font]alice.filestamp\f[], 702which includes both server and client keys. 703Copy this file to all group hosts and install a soft link 704from the generic 705\fIntpkey_gq_\f[]\f\*[I-Font]alice\f[] 706to this file. 707In addition, on each host bob install a soft link 708from generic 709\fIntpkey_gq_\f[]\f\*[I-Font]bob\f[] 710to this file. 711As the GQ scheme updates the GQ parameters file and certificate 712at the same time, keys and certificates can be regenerated as needed. 713.sp \n(Ppu 714.ne 2 715 716For the MV scheme, proceed as in the TC scheme to generate keys 717and certificates for all group hosts. 718For illustration assume trish is the TA, alice one of several trusted hosts 719and bob one of her clients. 720On TA trish run 721\f\*[B-Font]ntp-keygen\fP 722\f\*[B-Font]\-V\f[] \f\*[I-Font]n\f[] 723\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[], 724where 725\f\*[I-Font]n\f[] 726is the number of revokable keys (typically 5) to produce 727the parameter file 728\fIntpkeys_MVpar_\f[]\f\*[I-Font]trish.filestamp\f[] 729and client key files 730\fIntpkeys_MVkeyd_\f[]\f\*[I-Font]trish.filestamp\f[] 731where 732\f\*[I-Font]d\f[] 733is the key number (0 \&< 734\f\*[I-Font]d\f[] 735\&< 736\f\*[I-Font]n\f[]). 737Copy the parameter file to alice and install a soft link 738from the generic 739\fIntpkey_mv_\f[]\f\*[I-Font]alice\f[] 740to this file. 741Copy one of the client key files to alice for later distribution 742to her clients. 743It doesn't matter which client key file goes to alice, 744since they all work the same way. 745Alice copies the client key file to all of her cliens. 746On client bob install a soft link from generic 747\fIntpkey_mvkey_\f[]\f\*[I-Font]bob\f[] 748to the client key file. 749As the MV scheme is independent of keys and certificates, 750these files can be refreshed as needed. 751.SS Command Line Options 752.TP 7 753.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[] 754Select certificate message digest/signature encryption scheme. 755The 756\f\*[I-Font]scheme\f[] 757can be one of the following: 758. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , 759or 760\f\*[B-Font]DSA-SHA1\f[]. 761Note that RSA schemes must be used with a RSA sign key and DSA 762schemes must be used with a DSA sign key. 763The default without this option is 764\f\*[B-Font]RSA-MD5\f[]. 765.TP 7 766.NOP \f\*[B-Font]\-d\f[] 767Enable debugging. 768This option displays the cryptographic data produced in eye-friendly billboards. 769.TP 7 770.NOP \f\*[B-Font]\-e\f[] 771Write the IFF client keys to the standard output. 772This is intended for automatic key distribution by mail. 773.TP 7 774.NOP \f\*[B-Font]\-G\f[] 775Generate parameters and keys for the GQ identification scheme, 776obsoleting any that may exist. 777.TP 7 778.NOP \f\*[B-Font]\-g\f[] 779Generate keys for the GQ identification scheme 780using the existing GQ parameters. 781If the GQ parameters do not yet exist, create them first. 782.TP 7 783.NOP \f\*[B-Font]\-H\f[] 784Generate new host keys, obsoleting any that may exist. 785.TP 7 786.NOP \f\*[B-Font]\-I\f[] 787Generate parameters for the IFF identification scheme, 788obsoleting any that may exist. 789.TP 7 790.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]name\f[] 791Set the suject name to 792\f\*[I-Font]name\f[]. 793This is used as the subject field in certificates 794and in the file name for host and sign keys. 795.TP 7 796.NOP \f\*[B-Font]\-M\f[] 797Generate MD5 keys, obsoleting any that may exist. 798.TP 7 799.NOP \f\*[B-Font]\-P\f[] 800Generate a private certificate. 801By default, the program generates public certificates. 802.TP 7 803.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] 804Encrypt generated files containing private data with 805\f\*[I-Font]password\f[] 806and the DES-CBC algorithm. 807.TP 7 808.NOP \f\*[B-Font]\-q\f[] 809Set the password for reading files to password. 810.TP 7 811.NOP \f\*[B-Font]\-S\f[] [\f\*[B-Font]RSA\f[] | \f\*[B-Font]DSA\f[]] 812Generate a new sign key of the designated type, 813obsoleting any that may exist. 814By default, the program uses the host key as the sign key. 815.TP 7 816.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]name\f[] 817Set the issuer name to 818\f\*[I-Font]name\f[]. 819This is used for the issuer field in certificates 820and in the file name for identity files. 821.TP 7 822.NOP \f\*[B-Font]\-T\f[] 823Generate a trusted certificate. 824By default, the program generates a non-trusted certificate. 825.TP 7 826.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]nkeys\f[] 827Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. 828.PP 829.SS Random Seed File 830All cryptographically sound key generation schemes must have means 831to randomize the entropy seed used to initialize 832the internal pseudo-random number generator used 833by the library routines. 834The OpenSSL library uses a designated random seed file for this purpose. 835The file must be available when starting the NTP daemon and 836\f\*[B-Font]ntp-keygen\fP 837program. 838If a site supports OpenSSL or its companion OpenSSH, 839it is very likely that means to do this are already available. 840.sp \n(Ppu 841.ne 2 842 843It is important to understand that entropy must be evolved 844for each generation, for otherwise the random number sequence 845would be predictable. 846Various means dependent on external events, such as keystroke intervals, 847can be used to do this and some systems have built-in entropy sources. 848Suitable means are described in the OpenSSL software documentation, 849but are outside the scope of this page. 850.sp \n(Ppu 851.ne 2 852 853The entropy seed used by the OpenSSL library is contained in a file, 854usually called 855\f\*[B-Font].rnd\f[], 856which must be available when starting the NTP daemon 857or the 858\f\*[B-Font]ntp-keygen\fP 859program. 860The NTP daemon will first look for the file 861using the path specified by the 862\f\*[B-Font]randfile\f[] 863subcommand of the 864\f\*[B-Font]crypto\f[] 865configuration command. 866If not specified in this way, or when starting the 867\f\*[B-Font]ntp-keygen\fP 868program, 869the OpenSSL library will look for the file using the path specified 870by the 871RANDFILE 872environment variable in the user home directory, 873whether root or some other user. 874If the 875RANDFILE 876environment variable is not present, 877the library will look for the 878\f\*[B-Font].rnd\f[] 879file in the user home directory. 880If the file is not available or cannot be written, 881the daemon exits with a message to the system log and the program 882exits with a suitable error message. 883.SS Cryptographic Data Files 884All other file formats begin with two lines. 885The first contains the file name, including the generated host name 886and filestamp. 887The second contains the datestamp in conventional Unix date format. 888Lines beginning with # are considered comments and ignored by the 889\f\*[B-Font]ntp-keygen\fP 890program and 891\fCntpd\f[]\fR(1ntpdmdoc)\f[] 892daemon. 893Cryptographic values are encoded first using ASN.1 rules, 894then encrypted if necessary, and finally written PEM-encoded 895printable ASCII format preceded and followed by MIME content identifier lines. 896.sp \n(Ppu 897.ne 2 898 899The format of the symmetric keys file is somewhat different 900than the other files in the interest of backward compatibility. 901Since DES-CBC is deprecated in NTPv4, the only key format of interest 902is MD5 alphanumeric strings. 903Following hte heard the keys are 904entered one per line in the format 905.in +4 906\f\*[I-Font]keyno\f[] \f\*[I-Font]type\f[] \f\*[I-Font]key\f[] 907.in -4 908where 909\f\*[I-Font]keyno\f[] 910is a positive integer in the range 1-65,535, 911\f\*[I-Font]type\f[] 912is the string MD5 defining the key format and 913\f\*[I-Font]key\f[] 914is the key itself, 915which is a printable ASCII string 16 characters or less in length. 916Each character is chosen from the 93 printable characters 917in the range 0x21 through 0x7f excluding space and the 918\[oq]#\[cq] 919character. 920.sp \n(Ppu 921.ne 2 922 923Note that the keys used by the 924\fCntpq\f[]\fR(1ntpqmdoc)\f[] 925and 926\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 927programs 928are checked against passwords requested by the programs 929and entered by hand, so it is generally appropriate to specify these keys 930in human readable ASCII format. 931.sp \n(Ppu 932.ne 2 933 934The 935\f\*[B-Font]ntp-keygen\fP 936program generates a MD5 symmetric keys file 937\fIntpkey_MD5key_\f[]\f\*[I-Font]hostname.filestamp\f[]. 938Since the file contains private shared keys, 939it should be visible only to root and distributed by secure means 940to other subnet hosts. 941The NTP daemon loads the file 942\fIntp.keys\f[], 943so 944\f\*[B-Font]ntp-keygen\fP 945installs a soft link from this name to the generated file. 946Subsequently, similar soft links must be installed by manual 947or automated means on the other subnet hosts. 948While this file is not used with the Autokey Version 2 protocol, 949it is needed to authenticate some remote configuration commands 950used by the 951\fCntpq\f[]\fR(1ntpqmdoc)\f[] 952and 953\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 954utilities. 955.SH "OPTIONS" 956.TP 957.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]imbits\f[], \f\*[B-Font]\-\-imbits\f[]=\f\*[I-Font]imbits\f[] 958identity modulus bits. 959This option takes an integer number as its argument. 960The value of 961\f\*[I-Font]imbits\f[] 962is constrained to being: 963.in +4 964.nf 965.na 966in the range 256 through 2048 967.fi 968.in -4 969.sp 970The number of bits in the identity modulus. The default is 256. 971.TP 972.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]scheme\f[], \f\*[B-Font]\-\-certificate\f[]=\f\*[I-Font]scheme\f[] 973certificate scheme. 974.sp 975scheme is one of 976RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, 977DSA-SHA, or DSA-SHA1. 978.sp 979Select the certificate message digest/signature encryption scheme. 980Note that RSA schemes must be used with a RSA sign key and DSA 981schemes must be used with a DSA sign key. The default without 982this option is RSA-MD5. 983.TP 984.NOP \f\*[B-Font]\-C\f[] \f\*[I-Font]cipher\f[], \f\*[B-Font]\-\-cipher\f[]=\f\*[I-Font]cipher\f[] 985privatekey cipher. 986.sp 987Select the cipher which is used to encrypt the files containing 988private keys. The default is three-key triple DES in CBC mode, 989equivalent to "@code{-C des-ede3-cbc". The openssl tool lists ciphers 990available in "\fBopenssl \-h\fP" output. 991.TP 992.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] 993Increase debug verbosity level. 994This option may appear an unlimited number of times. 995.sp 996.TP 997.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] 998Set the debug verbosity level. 999This option may appear an unlimited number of times. 1000This option takes an integer number as its argument. 1001.sp 1002.TP 1003.NOP \f\*[B-Font]\-e\f[], \f\*[B-Font]\-\-id\-key\f[] 1004Write IFF or GQ identity keys. 1005.sp 1006Write the IFF or GQ client keys to the standard output. This is 1007intended for automatic key distribution by mail. 1008.TP 1009.NOP \f\*[B-Font]\-G\f[], \f\*[B-Font]\-\-gq\-params\f[] 1010Generate GQ parameters and keys. 1011.sp 1012Generate parameters and keys for the GQ identification scheme, 1013obsoleting any that may exist. 1014.TP 1015.NOP \f\*[B-Font]\-H\f[], \f\*[B-Font]\-\-host\-key\f[] 1016generate RSA host key. 1017.sp 1018Generate new host keys, obsoleting any that may exist. 1019.TP 1020.NOP \f\*[B-Font]\-I\f[], \f\*[B-Font]\-\-iffkey\f[] 1021generate IFF parameters. 1022.sp 1023Generate parameters for the IFF identification scheme, obsoleting 1024any that may exist. 1025.TP 1026.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]group\f[], \f\*[B-Font]\-\-ident\f[]=\f\*[I-Font]group\f[] 1027set Autokey group name. 1028.sp 1029Set the optional Autokey group name to name. This is used in 1030the file name of IFF, GQ, and MV client parameters files. In 1031that role, the default is the host name if this option is not 1032provided. The group name, if specified using \fB-i/--ident\fP or 1033using \fB-s/--subject-name\fP following an '\fB@\fP' character, 1034is also a part of the self-signed host certificate's subject and 1035issuer names in the form \fBhost@group\fP and should match the 1036'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in 1037\fBntpd\fP's configuration file. 1038.TP 1039.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]lifetime\f[], \f\*[B-Font]\-\-lifetime\f[]=\f\*[I-Font]lifetime\f[] 1040set certificate lifetime. 1041This option takes an integer number as its argument. 1042.sp 1043Set the certificate expiration to lifetime days from now. 1044.TP 1045.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-md5key\f[] 1046generate MD5 keys. 1047.sp 1048Generate MD5 keys, obsoleting any that may exist. 1049.TP 1050.NOP \f\*[B-Font]\-m\f[] \f\*[I-Font]modulus\f[], \f\*[B-Font]\-\-modulus\f[]=\f\*[I-Font]modulus\f[] 1051modulus. 1052This option takes an integer number as its argument. 1053The value of 1054\f\*[I-Font]modulus\f[] 1055is constrained to being: 1056.in +4 1057.nf 1058.na 1059in the range 256 through 2048 1060.fi 1061.in -4 1062.sp 1063The number of bits in the prime modulus. The default is 512. 1064.TP 1065.NOP \f\*[B-Font]\-P\f[], \f\*[B-Font]\-\-pvt\-cert\f[] 1066generate PC private certificate. 1067.sp 1068Generate a private certificate. By default, the program generates 1069public certificates. 1070.TP 1071.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-password\f[]=\f\*[I-Font]passwd\f[] 1072local private password. 1073.sp 1074Local files containing private data are encrypted with the 1075DES-CBC algorithm and the specified password. The same password 1076must be specified to the local ntpd via the "crypto pw password" 1077configuration command. The default password is the local 1078hostname. 1079.TP 1080.NOP \f\*[B-Font]\-q\f[] \f\*[I-Font]passwd\f[], \f\*[B-Font]\-\-export\-passwd\f[]=\f\*[I-Font]passwd\f[] 1081export IFF or GQ group keys with password. 1082.sp 1083Export IFF or GQ identity group keys to the standard output, 1084encrypted with the DES-CBC algorithm and the specified password. 1085The same password must be specified to the remote ntpd via the 1086"crypto pw password" configuration command. See also the option 1087--id-key (-e) for unencrypted exports. 1088.TP 1089.NOP \f\*[B-Font]\-S\f[] \f\*[I-Font]sign\f[], \f\*[B-Font]\-\-sign\-key\f[]=\f\*[I-Font]sign\f[] 1090generate sign key (RSA or DSA). 1091.sp 1092Generate a new sign key of the designated type, obsoleting any 1093that may exist. By default, the program uses the host key as the 1094sign key. 1095.TP 1096.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]host@group\f[], \f\*[B-Font]\-\-subject\-name\f[]=\f\*[I-Font]host@group\f[] 1097set host and optionally group name. 1098.sp 1099Set the Autokey host name, and optionally, group name specified 1100following an '\fB@\fP' character. The host name is used in the file 1101name of generated host and signing certificates, without the 1102group name. The host name, and if provided, group name are used 1103in \fBhost@group\fP form for the host certificate's subject and issuer 1104fields. Specifying '\fB-s @group\fP' is allowed, and results in 1105leaving the host name unchanged while appending \fB@group\fP to the 1106subject and issuer fields, as with \fB-i group\fP. The group name, or 1107if not provided, the host name are also used in the file names 1108of IFF, GQ, and MV client parameter files. 1109.TP 1110.NOP \f\*[B-Font]\-T\f[], \f\*[B-Font]\-\-trusted\-cert\f[] 1111trusted certificate (TC scheme). 1112.sp 1113Generate a trusted certificate. By default, the program generates 1114a non-trusted certificate. 1115.TP 1116.NOP \f\*[B-Font]\-V\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-params\f[]=\f\*[I-Font]num\f[] 1117generate <num> MV parameters. 1118This option takes an integer number as its argument. 1119.sp 1120Generate parameters and keys for the Mu-Varadharajan (MV) 1121identification scheme. 1122.TP 1123.NOP \f\*[B-Font]\-v\f[] \f\*[I-Font]num\f[], \f\*[B-Font]\-\-mv\-keys\f[]=\f\*[I-Font]num\f[] 1124update <num> MV keys. 1125This option takes an integer number as its argument. 1126.sp 1127This option has not been fully documented. 1128.TP 1129.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] 1130Display usage information and exit. 1131.TP 1132.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] 1133Pass the extended usage information through a pager. 1134.TP 1135.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] 1136Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 1137configuration file listed in the \fBOPTION PRESETS\fP section, below. 1138The command will exit after updating the config file. 1139.TP 1140.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[] 1141Load options from \fIcfgfile\fP. 1142The \fIno-load-opts\fP form will disable the loading 1143of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, 1144out of order. 1145.TP 1146.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 1147Output version of program and exit. The default mode is `v', a simple 1148version. The `c' mode will print copyright information and `n' will 1149print the full copyright notice. 1150.PP 1151.SH "OPTION PRESETS" 1152Any option that is not marked as \fInot presettable\fP may be preset 1153by loading values from configuration ("RC" or ".INI") file(s) and values from 1154environment variables named: 1155.nf 1156 \fBNTP_KEYGEN_<option-name>\fP or \fBNTP_KEYGEN\fP 1157.fi 1158.ad 1159The environmental presets take precedence (are processed later than) 1160the configuration files. 1161The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 1162If any of these are directories, then the file \fI.ntprc\fP 1163is searched for within those directories. 1164.SH USAGE 1165The 1166\f\*[B-Font]\-p\f[] \f\*[I-Font]password\f[] 1167option specifies the write password and 1168\f\*[B-Font]\-q\f[] \f\*[I-Font]password\f[] 1169option the read password for previously encrypted files. 1170The 1171\f\*[B-Font]ntp-keygen\fP 1172program prompts for the password if it reads an encrypted file 1173and the password is missing or incorrect. 1174If an encrypted file is read successfully and 1175no write password is specified, the read password is used 1176as the write password by default. 1177.SH "ENVIRONMENT" 1178See \fBOPTION PRESETS\fP for configuration environment variables. 1179.SH "FILES" 1180See \fBOPTION PRESETS\fP for configuration files. 1181.SH "EXIT STATUS" 1182One of the following exit values will be returned: 1183.TP 1184.NOP 0 " (EXIT_SUCCESS)" 1185Successful program execution. 1186.TP 1187.NOP 1 " (EXIT_FAILURE)" 1188The operation failed or the command syntax was not valid. 1189.TP 1190.NOP 66 " (EX_NOINPUT)" 1191A specified configuration file could not be loaded. 1192.TP 1193.NOP 70 " (EX_SOFTWARE)" 1194libopts had an internal operational error. Please report 1195it to autogen-users@lists.sourceforge.net. Thank you. 1196.PP 1197.SH "AUTHORS" 1198The University of Delaware and Network Time Foundation 1199.SH "COPYRIGHT" 1200Copyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved. 1201This program is released under the terms of the NTP license, <http://ntp.org/license>. 1202.SH BUGS 1203It can take quite a while to generate some cryptographic values, 1204from one to several minutes with modern architectures 1205such as UltraSPARC and up to tens of minutes to an hour 1206with older architectures such as SPARC IPC. 1207.sp \n(Ppu 1208.ne 2 1209 1210Please report bugs to http://bugs.ntp.org . 1211.sp \n(Ppu 1212.ne 2 1213 1214Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 1215.SH NOTES 1216Portions of this document came from FreeBSD. 1217.sp \n(Ppu 1218.ne 2 1219 1220This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP 1221option definitions. 1222