1330567Sgordon.Dd February 27 2018 2275970Scy.Dt NTP_KEYGEN @NTP_KEYGEN_MS@ User Commands 3275970Scy.Os 4275970Scy.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) 5275970Scy.\" 6330567Sgordon.\" It has been AutoGen-ed February 27, 2018 at 05:16:00 PM by AutoGen 5.18.5 7275970Scy.\" From the definitions ntp-keygen-opts.def 8275970Scy.\" and the template file agmdoc-cmd.tpl 9275970Scy.Sh NAME 10275970Scy.Nm ntp-keygen 11275970Scy.Nd Create a NTP host key 12275970Scy.Sh SYNOPSIS 13275970Scy.Nm 14275970Scy.\" Mixture of short (flag) options and long options 15275970Scy.Op Fl flags 16275970Scy.Op Fl flag Op Ar value 17275970Scy.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 18275970Scy.Pp 19275970ScyAll arguments must be options. 20275970Scy.Pp 21275970Scy.Sh DESCRIPTION 22275970ScyThis program generates cryptographic data files used by the NTPv4 23275970Scyauthentication and identification schemes. 24330567SgordonIt can generate message digest keys used in symmetric key cryptography and, 25330567Sgordonif the OpenSSL software library has been installed, it can generate host keys, 26330567Sgordonsigning keys, certificates, and identity keys and parameters used in Autokey 27330567Sgordonpublic key cryptography. 28275970ScyThese files are used for cookie encryption, 29330567Sgordondigital signature, and challenge/response identification algorithms 30275970Scycompatible with the Internet standard security infrastructure. 31275970Scy.Pp 32330567SgordonThe message digest symmetric keys file is generated in a format 33330567Sgordoncompatible with NTPv3. 34330567SgordonAll other files are in PEM\-encoded printable ASCII format, 35330567Sgordonso they can be embedded as MIME attachments in email to other sites 36275970Scyand certificate authorities. 37275970ScyBy default, files are not encrypted. 38275970Scy.Pp 39330567SgordonWhen used to generate message digest symmetric keys, the program 40330567Sgordonproduces a file containing ten pseudo\-random printable ASCII strings 41330567Sgordonsuitable for the MD5 message digest algorithm included in the 42330567Sgordondistribution. 43275970ScyIf the OpenSSL library is installed, it produces an additional ten 44330567Sgordonhex\-encoded random bit strings suitable for SHA1, AES\-128\-CMAC, and 45330567Sgordonother message digest algorithms. 46330567SgordonThe message digest symmetric keys file must be distributed and stored 47275970Scyusing secure means beyond the scope of NTP itself. 48275970ScyBesides the keys used for ordinary NTP associations, additional keys 49275970Scycan be defined as passwords for the 50275970Scy.Xr ntpq @NTPQ_MS@ 51275970Scyand 52275970Scy.Xr ntpdc @NTPDC_MS@ 53275970Scyutility programs. 54275970Scy.Pp 55275970ScyThe remaining generated files are compatible with other OpenSSL 56275970Scyapplications and other Public Key Infrastructure (PKI) resources. 57275970ScyCertificates generated by this program are compatible with extant 58275970Scyindustry practice, although some users might find the interpretation of 59275970ScyX509v3 extension fields somewhat liberal. 60275970ScyHowever, the identity keys are probably not compatible with anything 61275970Scyother than Autokey. 62275970Scy.Pp 63275970ScySome files used by this program are encrypted using a private password. 64275970ScyThe 65275970Scy.Fl p 66330567Sgordonoption specifies the read password for local encrypted files and the 67275970Scy.Fl q 68330567Sgordonoption the write password for encrypted files sent to remote sites. 69275970ScyIf no password is specified, the host name returned by the Unix 70330567Sgordon.Xr hostname 1 71330567Sgordoncommand, normally the DNS name of the host, is used as the the default read 72330567Sgordonpassword, for convenience. 73330567SgordonThe 74330567Sgordon.Nm 75330567Sgordonprogram prompts for the password if it reads an encrypted file 76330567Sgordonand the password is missing or incorrect. 77330567SgordonIf an encrypted file is read successfully and 78330567Sgordonno write password is specified, the read password is used 79330567Sgordonas the write password by default. 80275970Scy.Pp 81275970ScyThe 82330567Sgordon.Cm pw 83275970Scyoption of the 84330567Sgordon.Ic crypto 85330567Sgordon.Xr ntpd @NTPD_MS@ 86275970Scyconfiguration command specifies the read 87275970Scypassword for previously encrypted local files. 88330567SgordonThis must match the local read password used by this program. 89275970ScyIf not specified, the host name is used. 90330567SgordonThus, if files are generated by this program without an explicit password, 91275970Scythey can be read back by 92330567Sgordon.Xr ntpd @NTPD_MS@ 93330567Sgordonwithout specifying an explicit password but only on the same host. 94330567SgordonIf the write password used for encryption is specified as the host name, 95330567Sgordonthese files can be read by that host with no explicit password. 96275970Scy.Pp 97275970ScyNormally, encrypted files for each host are generated by that host and 98275970Scyused only by that host, although exceptions exist as noted later on 99275970Scythis page. 100275970ScyThe symmetric keys file, normally called 101330567Sgordon.Pa ntp.keys , 102275970Scyis usually installed in 103275970Scy.Pa /etc . 104275970ScyOther files and links are usually installed in 105275970Scy.Pa /usr/local/etc , 106275970Scywhich is normally in a shared filesystem in 107275970ScyNFS\-mounted networks and cannot be changed by shared clients. 108330567SgordonIn these cases, NFS clients can specify the files in another 109330567Sgordondirectory such as 110330567Sgordon.Pa /etc 111330567Sgordonusing the 112330567Sgordon.Ic keysdir 113330567Sgordon.Xr ntpd @NTPD_MS@ 114330567Sgordonconfiguration file command. 115275970Scy.Pp 116275970ScyThis program directs commentary and error messages to the standard 117275970Scyerror stream 118330567Sgordon.Pa stderr 119275970Scyand remote files to the standard output stream 120330567Sgordon.Pa stdout 121275970Scywhere they can be piped to other applications or redirected to files. 122275970ScyThe names used for generated files and links all begin with the 123275970Scystring 124330567Sgordon.Pa ntpkey\&* 125275970Scyand include the file type, generating host and filestamp, 126275970Scyas described in the 127330567Sgordon.Sx "Cryptographic Data Files" 128275970Scysection below. 129275970Scy.Ss Running the Program 130275970ScyThe safest way to run the 131275970Scy.Nm 132275970Scyprogram is logged in directly as root. 133330567SgordonThe recommended procedure is change to the 134330567Sgordon.Ar keys 135330567Sgordondirectory, usually 136275970Scy.Pa /usr/local/etc , 137275970Scythen run the program. 138330567Sgordon.Pp 139330567SgordonTo test and gain experience with Autokey concepts, log in as root and 140330567Sgordonchange to the 141330567Sgordon.Ar keys 142330567Sgordondirectory, usually 143330567Sgordon.Pa /usr/local/etc . 144330567SgordonWhen run for the first time, or if all files with names beginning with 145330567Sgordon.Pa ntpkey\&* 146330567Sgordonhave been removed, use the 147330567Sgordon.Nm 148330567Sgordoncommand without arguments to generate a default 149330567Sgordon.Cm RSA 150330567Sgordonhost key and matching 151330567Sgordon.Cm RSA\-MD5 152330567Sgordoncertificate file with expiration date one year hence, 153275970Scywhich is all that is necessary in many cases. 154275970ScyThe program also generates soft links from the generic names 155275970Scyto the respective files. 156330567SgordonIf run again without options, the program uses the 157330567Sgordonexisting keys and parameters and generates a new certificate file with 158330567Sgordonnew expiration date one year hence, and soft link. 159275970Scy.Pp 160330567SgordonThe host key is used to encrypt the cookie when required and so must be 161330567Sgordon.Cm RSA 162330567Sgordontype. 163275970ScyBy default, the host key is also the sign key used to encrypt signatures. 164275970ScyWhen necessary, a different sign key can be specified and this can be 165330567Sgordoneither 166330567Sgordon.Cm RSA 167330567Sgordonor 168330567Sgordon.Cm DSA 169330567Sgordontype. 170330567SgordonBy default, the message digest type is 171330567Sgordon.Cm MD5 , 172330567Sgordonbut any combination 173275970Scyof sign key type and message digest type supported by the OpenSSL library 174330567Sgordoncan be specified, including those using the 175330567Sgordon.Cm AES128CMAC , MD2 , MD5 , MDC2 , SHA , SHA1 176330567Sgordonand 177330567Sgordon.Cm RIPE160 178330567Sgordonmessage digest algorithms. 179275970ScyHowever, the scheme specified in the certificate must be compatible 180275970Scywith the sign key. 181330567SgordonCertificates using any digest algorithm are compatible with 182330567Sgordon.Cm RSA 183330567Sgordonsign keys; 184330567Sgordonhowever, only 185330567Sgordon.Cm SHA 186330567Sgordonand 187330567Sgordon.Cm SHA1 188330567Sgordoncertificates are compatible with 189330567Sgordon.Cm DSA 190330567Sgordonsign keys. 191275970Scy.Pp 192275970ScyPrivate/public key files and certificates are compatible with 193275970Scyother OpenSSL applications and very likely other libraries as well. 194275970ScyCertificates or certificate requests derived from them should be compatible 195275970Scywith extant industry practice, although some users might find 196275970Scythe interpretation of X509v3 extension fields somewhat liberal. 197275970ScyHowever, the identification parameter files, although encoded 198275970Scyas the other files, are probably not compatible with anything other than Autokey. 199275970Scy.Pp 200275970ScyRunning the program as other than root and using the Unix 201330567Sgordon.Xr su 1 202275970Scycommand 203275970Scyto assume root may not work properly, since by default the OpenSSL library 204275970Scylooks for the random seed file 205330567Sgordon.Pa .rnd 206275970Scyin the user home directory. 207275970ScyHowever, there should be only one 208330567Sgordon.Pa .rnd , 209275970Scymost conveniently 210275970Scyin the root directory, so it is convenient to define the 211330567Sgordon.Ev RANDFILE 212275970Scyenvironment variable used by the OpenSSL library as the path to 213330567Sgordon.Pa .rnd . 214275970Scy.Pp 215275970ScyInstalling the keys as root might not work in NFS\-mounted 216275970Scyshared file systems, as NFS clients may not be able to write 217275970Scyto the shared keys directory, even as root. 218275970ScyIn this case, NFS clients can specify the files in another 219275970Scydirectory such as 220275970Scy.Pa /etc 221275970Scyusing the 222275970Scy.Ic keysdir 223330567Sgordon.Xr ntpd @NTPD_MS@ 224330567Sgordonconfiguration file command. 225275970ScyThere is no need for one client to read the keys and certificates 226275970Scyof other clients or servers, as these data are obtained automatically 227275970Scyby the Autokey protocol. 228275970Scy.Pp 229275970ScyOrdinarily, cryptographic files are generated by the host that uses them, 230275970Scybut it is possible for a trusted agent (TA) to generate these files 231275970Scyfor other hosts; however, in such cases files should always be encrypted. 232275970ScyThe subject name and trusted name default to the hostname 233275970Scyof the host generating the files, but can be changed by command line options. 234275970ScyIt is convenient to designate the owner name and trusted name 235275970Scyas the subject and issuer fields, respectively, of the certificate. 236275970ScyThe owner name is also used for the host and sign key files, 237275970Scywhile the trusted name is used for the identity files. 238275970Scy.Pp 239275970ScyAll files are installed by default in the keys directory 240275970Scy.Pa /usr/local/etc , 241275970Scywhich is normally in a shared filesystem 242275970Scyin NFS\-mounted networks. 243275970ScyThe actual location of the keys directory 244275970Scyand each file can be overridden by configuration commands, 245275970Scybut this is not recommended. 246275970ScyNormally, the files for each host are generated by that host 247275970Scyand used only by that host, although exceptions exist 248275970Scyas noted later on this page. 249275970Scy.Pp 250275970ScyNormally, files containing private values, 251275970Scyincluding the host key, sign key and identification parameters, 252275970Scyare permitted root read/write\-only; 253275970Scywhile others containing public values are permitted world readable. 254275970ScyAlternatively, files containing private values can be encrypted 255275970Scyand these files permitted world readable, 256275970Scywhich simplifies maintenance in shared file systems. 257330567SgordonSince uniqueness is insured by the 258330567Sgordon.Ar hostname 259330567Sgordonand 260330567Sgordon.Ar filestamp 261330567Sgordonfile name extensions, the files for an NTP server and 262275970Scydependent clients can all be installed in the same shared directory. 263275970Scy.Pp 264275970ScyThe recommended practice is to keep the file name extensions 265275970Scywhen installing a file and to install a soft link 266275970Scyfrom the generic names specified elsewhere on this page 267275970Scyto the generated files. 268275970ScyThis allows new file generations to be activated simply 269275970Scyby changing the link. 270330567SgordonIf a link is present, 271330567Sgordon.Xr ntpd @NTPD_MS@ 272330567Sgordonfollows it to the file name to extract the 273330567Sgordon.Ar filestamp . 274275970ScyIf a link is not present, 275275970Scy.Xr ntpd @NTPD_MS@ 276330567Sgordonextracts the 277330567Sgordon.Ar filestamp 278330567Sgordonfrom the file itself. 279275970ScyThis allows clients to verify that the file and generation times 280275970Scyare always current. 281275970ScyThe 282275970Scy.Nm 283330567Sgordonprogram uses the same 284330567Sgordon.Ar filestamp 285330567Sgordonextension for all files generated 286275970Scyat one time, so each generation is distinct and can be readily 287275970Scyrecognized in monitoring data. 288330567Sgordon.Pp 289330567SgordonRun the command on as many hosts as necessary. 290330567SgordonDesignate one of them as the trusted host (TH) using 291275970Scy.Nm 292330567Sgordonwith the 293330567Sgordon.Fl T 294330567Sgordonoption and configure it to synchronize from reliable Internet servers. 295330567SgordonThen configure the other hosts to synchronize to the TH directly or 296330567Sgordonindirectly. 297330567SgordonA certificate trail is created when Autokey asks the immediately 298330567Sgordonascendant host towards the TH to sign its certificate, which is then 299330567Sgordonprovided to the immediately descendant host on request. 300330567SgordonAll group hosts should have acyclic certificate trails ending on the TH. 301275970Scy.Pp 302330567SgordonThe host key is used to encrypt the cookie when required and so must be 303330567SgordonRSA type. 304330567SgordonBy default, the host key is also the sign key used to encrypt 305330567Sgordonsignatures. 306330567SgordonA different sign key can be assigned using the 307330567Sgordon.Fl S 308330567Sgordonoption and this can be either 309330567Sgordon.Cm RSA 310330567Sgordonor 311330567Sgordon.Cm DSA 312330567Sgordontype. 313330567SgordonBy default, the signature 314330567Sgordonmessage digest type is 315330567Sgordon.Cm MD5 , 316330567Sgordonbut any combination of sign key type and 317330567Sgordonmessage digest type supported by the OpenSSL library can be specified 318330567Sgordonusing the 319330567Sgordon.Fl c 320330567Sgordonoption. 321275970Scy.Pp 322330567SgordonThe rules say cryptographic media should be generated with proventic 323330567Sgordonfilestamps, which means the host should already be synchronized before 324330567Sgordonthis program is run. 325330567SgordonThis of course creates a chicken\-and\-egg problem 326330567Sgordonwhen the host is started for the first time. 327330567SgordonAccordingly, the host time 328330567Sgordonshould be set by some other means, such as eyeball\-and\-wristwatch, at 329330567Sgordonleast so that the certificate lifetime is within the current year. 330330567SgordonAfter that and when the host is synchronized to a proventic source, the 331330567Sgordoncertificate should be re\-generated. 332275970Scy.Pp 333330567SgordonAdditional information on trusted groups and identity schemes is on the 334330567Sgordon.Dq Autokey Public\-Key Authentication 335330567Sgordonpage. 336275970Scy.Pp 337330567SgordonFile names begin with the prefix 338330567Sgordon.Pa ntpkey Ns _ 339330567Sgordonand end with the suffix 340330567Sgordon.Pa _ Ns Ar hostname . Ar filestamp , 341330567Sgordonwhere 342330567Sgordon.Ar hostname 343330567Sgordonis the owner name, usually the string returned 344330567Sgordonby the Unix 345330567Sgordon.Xr hostname 1 346330567Sgordoncommand, and 347330567Sgordon.Ar filestamp 348330567Sgordonis the NTP seconds when the file was generated, in decimal digits. 349330567SgordonThis both guarantees uniqueness and simplifies maintenance 350330567Sgordonprocedures, since all files can be quickly removed 351330567Sgordonby a 352330567Sgordon.Ic rm Pa ntpkey\&* 353330567Sgordoncommand or all files generated 354330567Sgordonat a specific time can be removed by a 355330567Sgordon.Ic rm Pa \&* Ns Ar filestamp 356275970Scycommand. 357330567SgordonTo further reduce the risk of misconfiguration, 358330567Sgordonthe first two lines of a file contain the file name 359330567Sgordonand generation date and time as comments. 360330567Sgordon.Ss Trusted Hosts and Groups 361275970ScyEach cryptographic configuration involves selection of a signature scheme 362275970Scyand identification scheme, called a cryptotype, 363275970Scyas explained in the 364275970Scy.Sx Authentication Options 365275970Scysection of 366275970Scy.Xr ntp.conf 5 . 367330567SgordonThe default cryptotype uses 368330567Sgordon.Cm RSA 369330567Sgordonencryption, 370330567Sgordon.Cm MD5 371330567Sgordonmessage digest 372330567Sgordonand 373330567Sgordon.Cm TC 374330567Sgordonidentification. 375275970ScyFirst, configure a NTP subnet including one or more low\-stratum 376275970Scytrusted hosts from which all other hosts derive synchronization 377275970Scydirectly or indirectly. 378275970ScyTrusted hosts have trusted certificates; 379275970Scyall other hosts have nontrusted certificates. 380275970ScyThese hosts will automatically and dynamically build authoritative 381275970Scycertificate trails to one or more trusted hosts. 382275970ScyA trusted group is the set of all hosts that have, directly or indirectly, 383275970Scya certificate trail ending at a trusted host. 384275970ScyThe trail is defined by static configuration file entries 385275970Scyor dynamic means described on the 386275970Scy.Sx Automatic NTP Configuration Options 387275970Scysection of 388275970Scy.Xr ntp.conf 5 . 389275970Scy.Pp 390275970ScyOn each trusted host as root, change to the keys directory. 391275970ScyTo insure a fresh fileset, remove all 392330567Sgordon.Pa ntpkey 393275970Scyfiles. 394275970ScyThen run 395275970Scy.Nm 396275970Scy.Fl T 397275970Scyto generate keys and a trusted certificate. 398275970ScyOn all other hosts do the same, but leave off the 399275970Scy.Fl T 400275970Scyflag to generate keys and nontrusted certificates. 401275970ScyWhen complete, start the NTP daemons beginning at the lowest stratum 402275970Scyand working up the tree. 403275970ScyIt may take some time for Autokey to instantiate the certificate trails 404275970Scythroughout the subnet, but setting up the environment is completely automatic. 405275970Scy.Pp 406275970ScyIf it is necessary to use a different sign key or different digest/signature 407275970Scyscheme than the default, run 408275970Scy.Nm 409275970Scywith the 410275970Scy.Fl S Ar type 411275970Scyoption, where 412275970Scy.Ar type 413275970Scyis either 414275970Scy.Cm RSA 415275970Scyor 416275970Scy.Cm DSA . 417330567SgordonThe most frequent need to do this is when a 418330567Sgordon.Cm DSA Ns \-signed 419330567Sgordoncertificate is used. 420275970ScyIf it is necessary to use a different certificate scheme than the default, 421275970Scyrun 422275970Scy.Nm 423275970Scywith the 424275970Scy.Fl c Ar scheme 425275970Scyoption and selected 426275970Scy.Ar scheme 427275970Scyas needed. 428330567SgordonIf 429275970Scy.Nm 430275970Scyis run again without these options, it generates a new certificate 431330567Sgordonusing the same scheme and sign key, and soft link. 432275970Scy.Pp 433275970ScyAfter setting up the environment it is advisable to update certificates 434275970Scyfrom time to time, if only to extend the validity interval. 435275970ScySimply run 436275970Scy.Nm 437275970Scywith the same flags as before to generate new certificates 438330567Sgordonusing existing keys, and soft links. 439275970ScyHowever, if the host or sign key is changed, 440275970Scy.Xr ntpd @NTPD_MS@ 441275970Scyshould be restarted. 442275970ScyWhen 443275970Scy.Xr ntpd @NTPD_MS@ 444275970Scyis restarted, it loads any new files and restarts the protocol. 445275970ScyOther dependent hosts will continue as usual until signatures are refreshed, 446275970Scyat which time the protocol is restarted. 447275970Scy.Ss Identity Schemes 448275970ScyAs mentioned on the Autonomous Authentication page, 449330567Sgordonthe default 450330567Sgordon.Cm TC 451330567Sgordonidentity scheme is vulnerable to a middleman attack. 452275970ScyHowever, there are more secure identity schemes available, 453330567Sgordonincluding 454330567Sgordon.Cm PC , IFF , GQ 455330567Sgordonand 456330567Sgordon.Cm MV 457330567Sgordonschemes described below. 458275970ScyThese schemes are based on a TA, one or more trusted hosts 459275970Scyand some number of nontrusted hosts. 460275970ScyTrusted hosts prove identity using values provided by the TA, 461275970Scywhile the remaining hosts prove identity using values provided 462275970Scyby a trusted host and certificate trails that end on that host. 463275970ScyThe name of a trusted host is also the name of its sugroup 464275970Scyand also the subject and issuer name on its trusted certificate. 465275970ScyThe TA is not necessarily a trusted host in this sense, but often is. 466275970Scy.Pp 467275970ScyIn some schemes there are separate keys for servers and clients. 468275970ScyA server can also be a client of another server, 469275970Scybut a client can never be a server for another client. 470275970ScyIn general, trusted hosts and nontrusted hosts that operate 471275970Scyas both server and client have parameter files that contain 472275970Scyboth server and client keys. 473275970ScyHosts that operate 474275970Scyonly as clients have key files that contain only client keys. 475275970Scy.Pp 476275970ScyThe PC scheme supports only one trusted host in the group. 477275970ScyOn trusted host alice run 478275970Scy.Nm 479275970Scy.Fl P 480275970Scy.Fl p Ar password 481275970Scyto generate the host key file 482330567Sgordon.Pa ntpkey Ns _ Cm RSA Pa key_alice. Ar filestamp 483275970Scyand trusted private certificate file 484330567Sgordon.Pa ntpkey Ns _ Cm RSA\-MD5 _ Pa cert_alice. Ar filestamp , 485330567Sgordonand soft links. 486275970ScyCopy both files to all group hosts; 487275970Scythey replace the files which would be generated in other schemes. 488330567SgordonOn each host 489330567Sgordon.Ar bob 490330567Sgordoninstall a soft link from the generic name 491275970Scy.Pa ntpkey_host_ Ns Ar bob 492275970Scyto the host key file and soft link 493275970Scy.Pa ntpkey_cert_ Ns Ar bob 494275970Scyto the private certificate file. 495275970ScyNote the generic links are on bob, but point to files generated 496275970Scyby trusted host alice. 497275970ScyIn this scheme it is not possible to refresh 498275970Scyeither the keys or certificates without copying them 499330567Sgordonto all other hosts in the group, and recreating the soft links. 500275970Scy.Pp 501330567SgordonFor the 502330567Sgordon.Cm IFF 503330567Sgordonscheme proceed as in the 504330567Sgordon.Cm TC 505330567Sgordonscheme to generate keys 506275970Scyand certificates for all group hosts, then for every trusted host in the group, 507330567Sgordongenerate the 508330567Sgordon.Cm IFF 509330567Sgordonparameter file. 510275970ScyOn trusted host alice run 511275970Scy.Nm 512275970Scy.Fl T 513275970Scy.Fl I 514275970Scy.Fl p Ar password 515275970Scyto produce her parameter file 516330567Sgordon.Pa ntpkey_IFFpar_alice. Ns Ar filestamp , 517275970Scywhich includes both server and client keys. 518275970ScyCopy this file to all group hosts that operate as both servers 519275970Scyand clients and install a soft link from the generic 520330567Sgordon.Pa ntpkey_iff_alice 521275970Scyto this file. 522275970ScyIf there are no hosts restricted to operate only as clients, 523275970Scythere is nothing further to do. 524330567SgordonAs the 525330567Sgordon.Cm IFF 526330567Sgordonscheme is independent 527275970Scyof keys and certificates, these files can be refreshed as needed. 528275970Scy.Pp 529275970ScyIf a rogue client has the parameter file, it could masquerade 530275970Scyas a legitimate server and present a middleman threat. 531275970ScyTo eliminate this threat, the client keys can be extracted 532275970Scyfrom the parameter file and distributed to all restricted clients. 533275970ScyAfter generating the parameter file, on alice run 534275970Scy.Nm 535275970Scy.Fl e 536330567Sgordonand pipe the output to a file or email program. 537330567SgordonCopy or email this file to all restricted clients. 538275970ScyOn these clients install a soft link from the generic 539330567Sgordon.Pa ntpkey_iff_alice 540275970Scyto this file. 541275970ScyTo further protect the integrity of the keys, 542275970Scyeach file can be encrypted with a secret password. 543275970Scy.Pp 544330567SgordonFor the 545330567Sgordon.Cm GQ 546330567Sgordonscheme proceed as in the 547330567Sgordon.Cm TC 548330567Sgordonscheme to generate keys 549275970Scyand certificates for all group hosts, then for every trusted host 550330567Sgordonin the group, generate the 551330567Sgordon.Cm IFF 552330567Sgordonparameter file. 553275970ScyOn trusted host alice run 554275970Scy.Nm 555275970Scy.Fl T 556275970Scy.Fl G 557275970Scy.Fl p Ar password 558275970Scyto produce her parameter file 559330567Sgordon.Pa ntpkey_GQpar_alice. Ns Ar filestamp , 560275970Scywhich includes both server and client keys. 561275970ScyCopy this file to all group hosts and install a soft link 562275970Scyfrom the generic 563330567Sgordon.Pa ntpkey_gq_alice 564275970Scyto this file. 565330567SgordonIn addition, on each host 566330567Sgordon.Ar bob 567330567Sgordoninstall a soft link 568275970Scyfrom generic 569275970Scy.Pa ntpkey_gq_ Ns Ar bob 570275970Scyto this file. 571330567SgordonAs the 572330567Sgordon.Cm GQ 573330567Sgordonscheme updates the 574330567Sgordon.Cm GQ 575330567Sgordonparameters file and certificate 576275970Scyat the same time, keys and certificates can be regenerated as needed. 577275970Scy.Pp 578330567SgordonFor the 579330567Sgordon.Cm MV 580330567Sgordonscheme, proceed as in the 581330567Sgordon.Cm TC 582330567Sgordonscheme to generate keys 583275970Scyand certificates for all group hosts. 584275970ScyFor illustration assume trish is the TA, alice one of several trusted hosts 585275970Scyand bob one of her clients. 586275970ScyOn TA trish run 587275970Scy.Nm 588275970Scy.Fl V Ar n 589275970Scy.Fl p Ar password , 590275970Scywhere 591275970Scy.Ar n 592275970Scyis the number of revokable keys (typically 5) to produce 593275970Scythe parameter file 594330567Sgordon.Pa ntpkeys_MVpar_trish. Ns Ar filestamp 595275970Scyand client key files 596330567Sgordon.Pa ntpkeys_MVkey Ns Ar d _ Pa trish. Ar filestamp 597275970Scywhere 598275970Scy.Ar d 599275970Scyis the key number (0 \&< 600275970Scy.Ar d 601275970Scy\&< 602275970Scy.Ar n ) . 603275970ScyCopy the parameter file to alice and install a soft link 604275970Scyfrom the generic 605330567Sgordon.Pa ntpkey_mv_alice 606275970Scyto this file. 607275970ScyCopy one of the client key files to alice for later distribution 608275970Scyto her clients. 609330567SgordonIt does not matter which client key file goes to alice, 610275970Scysince they all work the same way. 611330567SgordonAlice copies the client key file to all of her clients. 612275970ScyOn client bob install a soft link from generic 613330567Sgordon.Pa ntpkey_mvkey_bob 614275970Scyto the client key file. 615330567SgordonAs the 616330567Sgordon.Cm MV 617330567Sgordonscheme is independent of keys and certificates, 618275970Scythese files can be refreshed as needed. 619275970Scy.Ss Command Line Options 620275970Scy.Bl -tag -width indent 621330567Sgordon.It Fl b Fl \-imbits Ns = Ar modulus 622330567SgordonSet the number of bits in the identity modulus for generating identity keys to 623330567Sgordon.Ar modulus 624330567Sgordonbits. 625330567SgordonThe number of bits in the identity modulus defaults to 256, but can be set to 626330567Sgordonvalues from 256 to 2048 (32 to 256 octets). 627330567SgordonUse the larger moduli with caution, as this can consume considerable computing 628330567Sgordonresources and increases the size of authenticated packets. 629330567Sgordon.It Fl c Fl \-certificate Ns = Ar scheme 630330567SgordonSelect certificate signature encryption/message digest scheme. 631275970ScyThe 632275970Scy.Ar scheme 633275970Scycan be one of the following: 634330567Sgordon.Cm RSA\-MD2 , RSA\-MD5 , RSA\-MDC2 , RSA\-SHA , RSA\-SHA1 , RSA\-RIPEMD160 , DSA\-SHA , 635275970Scyor 636275970Scy.Cm DSA\-SHA1 . 637330567SgordonNote that 638330567Sgordon.Cm RSA 639330567Sgordonschemes must be used with an 640330567Sgordon.Cm RSA 641330567Sgordonsign key and 642330567Sgordon.Cm DSA 643330567Sgordonschemes must be used with a 644330567Sgordon.Cm DSA 645330567Sgordonsign key. 646275970ScyThe default without this option is 647275970Scy.Cm RSA\-MD5 . 648330567SgordonIf compatibility with FIPS 140\-2 is required, either the 649330567Sgordon.Cm DSA\-SHA 650330567Sgordonor 651330567Sgordon.Cm DSA\-SHA1 652330567Sgordonscheme must be used. 653330567Sgordon.It Fl C Fl \-cipher Ns = Ar cipher 654330567SgordonSelect the OpenSSL cipher to encrypt the files containing private keys. 655330567SgordonThe default without this option is three\-key triple DES in CBC mode, 656330567Sgordon.Cm des\-ede3\-cbc . 657330567SgordonThe 658330567Sgordon.Ic openssl Fl h 659330567Sgordoncommand provided with OpenSSL displays available ciphers. 660330567Sgordon.It Fl d Fl \-debug\-level 661330567SgordonIncrease debugging verbosity level. 662275970ScyThis option displays the cryptographic data produced in eye\-friendly billboards. 663330567Sgordon.It Fl D Fl \-set\-debug\-level Ns = Ar level 664330567SgordonSet the debugging verbosity to 665330567Sgordon.Ar level . 666330567SgordonThis option displays the cryptographic data produced in eye\-friendly billboards. 667330567Sgordon.It Fl e Fl \-id\-key 668330567SgordonWrite the 669330567Sgordon.Cm IFF 670330567Sgordonor 671330567Sgordon.Cm GQ 672330567Sgordonpublic parameters from the 673330567Sgordon.Ar IFFkey or GQkey 674330567Sgordonclient keys file previously specified 675330567Sgordonas unencrypted data to the standard output stream 676330567Sgordon.Pa stdout . 677330567SgordonThis is intended for automatic key distribution by email. 678330567Sgordon.It Fl G Fl \-gq\-params 679330567SgordonGenerate a new encrypted 680330567Sgordon.Cm GQ 681330567Sgordonparameters and key file for the Guillou\-Quisquater (GQ) identity scheme. 682330567SgordonThis option is mutually exclusive with the 683330567Sgordon.Fl I 684330567Sgordonand 685330567Sgordon.Fl V 686330567Sgordonoptions. 687330567Sgordon.It Fl H Fl \-host\-key 688330567SgordonGenerate a new encrypted 689330567Sgordon.Cm RSA 690330567Sgordonpublic/private host key file. 691330567Sgordon.It Fl I Fl \-iffkey 692330567SgordonGenerate a new encrypted 693330567Sgordon.Cm IFF 694330567Sgordonkey file for the Schnorr (IFF) identity scheme. 695330567SgordonThis option is mutually exclusive with the 696330567Sgordon.Fl G 697330567Sgordonand 698330567SgordonFl V 699330567Sgordonoptions. 700330567Sgordon.It Fl i Fl \-ident Ns = Ar group 701330567SgordonSet the optional Autokey group name to 702330567Sgordon.Ar group . 703330567SgordonThis is used in the identity scheme parameter file names of 704330567Sgordon.Cm IFF , GQ , 705330567Sgordonand 706330567Sgordon.Cm MV 707330567Sgordonclient parameters files. 708330567SgordonIn that role, the default is the host name if no group is provided. 709330567SgordonThe group name, if specified using 710330567Sgordon.Fl i 711330567Sgordonor 712330567Sgordon.Fl s 713330567Sgordonfollowing an 714330567Sgordon.Ql @ 715330567Sgordoncharacter, is also used in certificate subject and issuer names in the form 716330567Sgordon.Ar host @ group 717330567Sgordonand should match the group specified via 718330567Sgordon.Ic crypto Cm ident 719330567Sgordonor 720330567Sgordon.Ic server Cm ident 721330567Sgordonin the ntpd configuration file. 722330567Sgordon.It Fl l Fl \-lifetime Ns = Ar days 723330567SgordonSet the lifetime for certificate expiration to 724330567Sgordon.Ar days . 725330567SgordonThe default lifetime is one year (365 days). 726330567Sgordon.It Fl m Fl \-modulus Ns = Ar bits 727330567SgordonSet the number of bits in the prime modulus for generating files to 728330567Sgordon.Ar bits . 729330567SgordonThe modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets). 730330567SgordonUse the larger moduli with caution, as this can consume considerable computing 731330567Sgordonresources and increases the size of authenticated packets. 732330567Sgordon.It Fl M Fl \-md5key 733330567SgordonGenerate a new symmetric keys file containing 10 734330567Sgordon.Cm MD5 735330567Sgordonkeys, and if OpenSSL is available, 10 736330567Sgordon.Cm SHA 737330567Sgordonkeys. 738330567SgordonAn 739330567Sgordon.Cm MD5 740330567Sgordonkey is a string of 20 random printable ASCII characters, while a 741330567Sgordon.Cm SHA 742330567Sgordonkey is a string of 40 random hex digits. 743330567SgordonThe file can be edited using a text editor to change the key type or key content. 744330567SgordonThis option is mutually exclusive with all other options. 745330567Sgordon.It Fl p Fl \-password Ns = Ar passwd 746330567SgordonSet the password for reading and writing encrypted files to 747330567Sgordon.Ar passwd . 748330567SgordonThese include the host, sign and identify key files. 749330567SgordonBy default, the password is the string returned by the Unix 750330567Sgordon.Ic hostname 751330567Sgordoncommand. 752330567Sgordon.It Fl P Fl \-pvt\-cert 753330567SgordonGenerate a new private certificate used by the 754330567Sgordon.Cm PC 755330567Sgordonidentity scheme. 756275970ScyBy default, the program generates public certificates. 757330567SgordonNote: the PC identity scheme is not recommended for new installations. 758330567Sgordon.It Fl q Fl \-export\-passwd Ns = Ar passwd 759330567SgordonSet the password for writing encrypted 760330567Sgordon.Cm IFF , GQ and MV 761330567Sgordonidentity files redirected to 762330567Sgordon.Pa stdout 763330567Sgordonto 764330567Sgordon.Ar passwd . 765330567SgordonIn effect, these files are decrypted with the 766330567Sgordon.Fl p 767330567Sgordonpassword, then encrypted with the 768330567Sgordon.Fl q 769330567Sgordonpassword. 770330567SgordonBy default, the password is the string returned by the Unix 771330567Sgordon.Ic hostname 772330567Sgordoncommand. 773330567Sgordon.It Fl s Fl \-subject\-key Ns = Ar Oo host Oc Op @ Ar group 774330567SgordonSpecify the Autokey host name, where 775330567Sgordon.Ar host 776330567Sgordonis the optional host name and 777330567Sgordon.Ar group 778330567Sgordonis the optional group name. 779330567SgordonThe host name, and if provided, group name are used in 780330567Sgordon.Ar host @ group 781330567Sgordonform as certificate subject and issuer. 782330567SgordonSpecifying 783330567Sgordon.Fl s @ Ar group 784330567Sgordonis allowed, and results in leaving the host name unchanged, as with 785330567Sgordon.Fl i Ar group . 786330567SgordonThe group name, or if no group is provided, the host name are also used in the 787330567Sgordonfile names of 788330567Sgordon.Cm IFF , GQ , 789330567Sgordonand 790330567Sgordon.Cm MV 791330567Sgordonidentity scheme client parameter files. 792330567SgordonIf 793330567Sgordon.Ar host 794330567Sgordonis not specified, the default host name is the string returned by the Unix 795330567Sgordon.Ic hostname 796330567Sgordoncommand. 797330567Sgordon.It Fl S Fl \-sign\-key Ns = Op Cm RSA | DSA 798330567SgordonGenerate a new encrypted public/private sign key file of the specified type. 799330567SgordonBy default, the sign key is the host key and has the same type. 800330567SgordonIf compatibility with FIPS 140\-2 is required, the sign key type must be 801330567Sgordon.Cm DSA . 802330567Sgordon.It Fl T Fl \-trusted\-cert 803275970ScyGenerate a trusted certificate. 804275970ScyBy default, the program generates a non\-trusted certificate. 805330567Sgordon.It Fl V Fl \-mv\-params Ar nkeys 806330567SgordonGenerate 807330567Sgordon.Ar nkeys 808330567Sgordonencrypted server keys and parameters for the Mu\-Varadharajan (MV) 809330567Sgordonidentity scheme. 810330567SgordonThis option is mutually exclusive with the 811330567Sgordon.Fl I 812330567Sgordonand 813330567Sgordon.Fl G 814330567Sgordonoptions. 815330567SgordonNote: support for this option should be considered a work in progress. 816275970Scy.El 817275970Scy.Ss Random Seed File 818275970ScyAll cryptographically sound key generation schemes must have means 819275970Scyto randomize the entropy seed used to initialize 820275970Scythe internal pseudo\-random number generator used 821275970Scyby the library routines. 822275970ScyThe OpenSSL library uses a designated random seed file for this purpose. 823275970ScyThe file must be available when starting the NTP daemon and 824275970Scy.Nm 825275970Scyprogram. 826275970ScyIf a site supports OpenSSL or its companion OpenSSH, 827275970Scyit is very likely that means to do this are already available. 828275970Scy.Pp 829275970ScyIt is important to understand that entropy must be evolved 830275970Scyfor each generation, for otherwise the random number sequence 831275970Scywould be predictable. 832275970ScyVarious means dependent on external events, such as keystroke intervals, 833275970Scycan be used to do this and some systems have built\-in entropy sources. 834275970ScySuitable means are described in the OpenSSL software documentation, 835275970Scybut are outside the scope of this page. 836275970Scy.Pp 837275970ScyThe entropy seed used by the OpenSSL library is contained in a file, 838275970Scyusually called 839330567Sgordon.Pa .rnd , 840275970Scywhich must be available when starting the NTP daemon 841275970Scyor the 842275970Scy.Nm 843275970Scyprogram. 844275970ScyThe NTP daemon will first look for the file 845275970Scyusing the path specified by the 846330567Sgordon.Cm randfile 847275970Scysubcommand of the 848275970Scy.Ic crypto 849275970Scyconfiguration command. 850275970ScyIf not specified in this way, or when starting the 851275970Scy.Nm 852275970Scyprogram, 853275970Scythe OpenSSL library will look for the file using the path specified 854275970Scyby the 855275970Scy.Ev RANDFILE 856275970Scyenvironment variable in the user home directory, 857275970Scywhether root or some other user. 858275970ScyIf the 859275970Scy.Ev RANDFILE 860275970Scyenvironment variable is not present, 861275970Scythe library will look for the 862330567Sgordon.Pa .rnd 863275970Scyfile in the user home directory. 864330567SgordonSince both the 865330567Sgordon.Nm 866330567Sgordonprogram and 867330567Sgordon.Xr ntpd @NTPD_MS@ 868330567Sgordondaemon must run as root, the logical place to put this file is in 869330567Sgordon.Pa /.rnd 870330567Sgordonor 871330567Sgordon.Pa /root/.rnd . 872275970ScyIf the file is not available or cannot be written, 873275970Scythe daemon exits with a message to the system log and the program 874275970Scyexits with a suitable error message. 875275970Scy.Ss Cryptographic Data Files 876330567SgordonAll file formats begin with two nonencrypted lines. 877330567SgordonThe first line contains the file name, including the generated host name 878330567Sgordonand filestamp, in the format 879330567Sgordon.Pa ntpkey_ Ns Ar key _ Ar name . Ar filestamp , 880330567Sgordonwhere 881330567Sgordon.Ar key 882330567Sgordonis the key or parameter type, 883330567Sgordon.Ar name 884330567Sgordonis the host or group name and 885330567Sgordon.Ar filestamp 886330567Sgordonis the filestamp (NTP seconds) when the file was created. 887330567SgordonBy convention, 888330567Sgordon.Ar key 889330567Sgordonnames in generated file names include both upper and lower case 890330567Sgordoncharacters, while 891330567Sgordon.Ar key 892330567Sgordonnames in generated link names include only lower case characters. 893330567SgordonThe filestamp is not used in generated link names. 894330567SgordonThe second line contains the datestamp in conventional Unix 895330567Sgordon.Pa date 896330567Sgordonformat. 897330567SgordonLines beginning with 898330567Sgordon.Ql # 899330567Sgordonare considered comments and ignored by the 900275970Scy.Nm 901275970Scyprogram and 902275970Scy.Xr ntpd @NTPD_MS@ 903275970Scydaemon. 904275970Scy.Pp 905330567SgordonThe remainder of the file contains cryptographic data, encoded first using ASN.1 906330567Sgordonrules, then encrypted if necessary, and finally written in PEM\-encoded 907330567Sgordonprintable ASCII text, preceded and followed by MIME content identifier lines. 908330567Sgordon.Pp 909330567SgordonThe format of the symmetric keys file, ordinarily named 910330567Sgordon.Pa ntp.keys , 911330567Sgordonis somewhat different than the other files in the interest of backward compatibility. 912330567SgordonOrdinarily, the file is generated by this program, but it can be constructed 913330567Sgordonand edited using an ordinary text editor. 914330567Sgordon.Bd -literal -unfilled -offset center 915330567Sgordon# ntpkey_MD5key_bk.ntp.org.3595864945 916330567Sgordon# Thu Dec 12 19:22:25 2013 917330567Sgordon1 MD5 L";Nw<\`.I<f4U0)247"i # MD5 key 918330567Sgordon2 MD5 &>l0%XXK9O'51VwV<xq~ # MD5 key 919330567Sgordon3 MD5 lb4zLW~d^!K:]RsD'qb6 # MD5 key 920330567Sgordon4 MD5 Yue:tL[+vR)M\`n~bY,'? # MD5 key 921330567Sgordon5 MD5 B;fx'Kgr/&4ZTbL6=RxA # MD5 key 922330567Sgordon6 MD5 4eYwa\`o}3i@@V@..R9!l # MD5 key 923330567Sgordon7 MD5 \`A.([h+;wTQ|xfi%Sn_! # MD5 key 924330567Sgordon8 MD5 45:V,r4]l6y^JH6"Sh?F # MD5 key 925330567Sgordon9 MD5 3\-5vcn*6l29DS?Xdsg)* # MD5 key 926330567Sgordon10 MD5 2late4Me # MD5 key 927330567Sgordon11 SHA1 a27872d3030a9025b8446c751b4551a7629af65c # SHA1 key 928330567Sgordon12 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74 # SHA1 key 929330567Sgordon13 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9 # SHA1 key 930330567Sgordon14 SHA a5332809c8878dd3a5b918819108a111509aeceb # SHA key 931330567Sgordon15 MD2 2fe16c88c760ff2f16d4267e36c1aa6c926e6964 # MD2 key 932330567Sgordon16 MD4 b2691811dc19cfc0e2f9bcacd74213f29812183d # MD4 key 933330567Sgordon17 MD5 e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c # MD5 key 934330567Sgordon18 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc # MDC2 key 935330567Sgordon19 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2 # RIPEMD160 key 936330567Sgordon20 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878 # AES128CMAC key 937330567Sgordon.Ed 938330567Sgordon.D1 Figure 1. Typical Symmetric Key File 939330567Sgordon.Pp 940330567SgordonFigure 1 shows a typical symmetric keys file used by the reference 941330567Sgordonimplementation. 942330567SgordonFollowing the header the keys are entered one per line in the format 943330567Sgordon.D1 Ar keyno Ar type Ar key 944275970Scywhere 945275970Scy.Ar keyno 946330567Sgordonis a positive integer in the range 1\-65534; 947275970Scy.Ar type 948330567Sgordonis the key type for the message digest algorithm, which in the absence of the 949330567SgordonOpenSSL library must be 950330567Sgordon.Cm MD5 951330567Sgordonto designate the MD5 message digest algorithm; 952330567Sgordonif the OpenSSL library is installed, the key type can be any 953330567Sgordonmessage digest algorithm supported by that library; 954330567Sgordonhowever, if compatibility with FIPS 140\-2 is required, 955330567Sgordonthe key type must be either 956330567Sgordon.Cm SHA 957330567Sgordonor 958330567Sgordon.Cm SHA1 ; 959275970Scy.Ar key 960275970Scyis the key itself, 961330567Sgordonwhich is a printable ASCII string 20 characters or less in length: 962330567Sgordoneach character is chosen from the 93 printable characters 963330567Sgordonin the range 0x21 through 0x7e ( 964330567Sgordon.Ql ! 965330567Sgordonthrough 966330567Sgordon.Ql ~ 967330567Sgordon\&) excluding space and the 968275970Scy.Ql # 969330567Sgordoncharacter, and terminated by whitespace or a 970330567Sgordon.Ql # 971275970Scycharacter. 972330567SgordonAn OpenSSL key consists of a hex\-encoded ASCII string of 40 characters, which 973330567Sgordonis truncated as necessary. 974275970Scy.Pp 975275970ScyNote that the keys used by the 976275970Scy.Xr ntpq @NTPQ_MS@ 977275970Scyand 978275970Scy.Xr ntpdc @NTPDC_MS@ 979275970Scyprograms 980275970Scyare checked against passwords requested by the programs 981275970Scyand entered by hand, so it is generally appropriate to specify these keys 982275970Scyin human readable ASCII format. 983275970Scy.Pp 984275970ScyThe 985275970Scy.Nm 986330567Sgordonprogram generates a symmetric keys file 987330567Sgordon.Pa ntpkey_MD5key_ Ns Ar hostname Ns . Ns Ar filestamp . 988275970ScySince the file contains private shared keys, 989275970Scyit should be visible only to root and distributed by secure means 990275970Scyto other subnet hosts. 991275970ScyThe NTP daemon loads the file 992275970Scy.Pa ntp.keys , 993275970Scyso 994275970Scy.Nm 995275970Scyinstalls a soft link from this name to the generated file. 996275970ScySubsequently, similar soft links must be installed by manual 997275970Scyor automated means on the other subnet hosts. 998275970ScyWhile this file is not used with the Autokey Version 2 protocol, 999275970Scyit is needed to authenticate some remote configuration commands 1000275970Scyused by the 1001275970Scy.Xr ntpq @NTPQ_MS@ 1002275970Scyand 1003275970Scy.Xr ntpdc @NTPDC_MS@ 1004275970Scyutilities. 1005275970Scy.Sh "OPTIONS" 1006275970Scy.Bl -tag 1007275970Scy.It Fl b Ar imbits , Fl \-imbits Ns = Ns Ar imbits 1008275970Scyidentity modulus bits. 1009275970ScyThis option takes an integer number as its argument. 1010275970ScyThe value of 1011275970Scy.Ar imbits 1012275970Scyis constrained to being: 1013275970Scy.in +4 1014275970Scy.nf 1015275970Scy.na 1016275970Scyin the range 256 through 2048 1017275970Scy.fi 1018275970Scy.in -4 1019275970Scy.sp 1020275970ScyThe number of bits in the identity modulus. The default is 256. 1021275970Scy.It Fl c Ar scheme , Fl \-certificate Ns = Ns Ar scheme 1022275970Scycertificate scheme. 1023275970Scy.sp 1024275970Scyscheme is one of 1025330567SgordonRSA\-MD2, RSA\-MD5, RSA\-MDC2, RSA\-SHA, RSA\-SHA1, RSA\-RIPEMD160, 1026275970ScyDSA\-SHA, or DSA\-SHA1. 1027275970Scy.sp 1028330567SgordonSelect the certificate signature encryption/message digest scheme. 1029275970ScyNote that RSA schemes must be used with a RSA sign key and DSA 1030275970Scyschemes must be used with a DSA sign key. The default without 1031275970Scythis option is RSA\-MD5. 1032275970Scy.It Fl C Ar cipher , Fl \-cipher Ns = Ns Ar cipher 1033275970Scyprivatekey cipher. 1034275970Scy.sp 1035275970ScySelect the cipher which is used to encrypt the files containing 1036275970Scyprivate keys. The default is three\-key triple DES in CBC mode, 1037330567Sgordonequivalent to "\fB\-C des\-ede3\-cbc\fP". The openssl tool lists ciphers 1038275970Scyavailable in "\fBopenssl \-h\fP" output. 1039275970Scy.It Fl d , Fl \-debug\-level 1040275970ScyIncrease debug verbosity level. 1041275970ScyThis option may appear an unlimited number of times. 1042275970Scy.sp 1043275970Scy.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 1044275970ScySet the debug verbosity level. 1045275970ScyThis option may appear an unlimited number of times. 1046275970ScyThis option takes an integer number as its argument. 1047275970Scy.sp 1048275970Scy.It Fl e , Fl \-id\-key 1049275970ScyWrite IFF or GQ identity keys. 1050275970Scy.sp 1051330567SgordonWrite the public parameters from the IFF or GQ client keys to 1052330567Sgordonthe standard output. 1053330567SgordonThis is intended for automatic key distribution by email. 1054275970Scy.It Fl G , Fl \-gq\-params 1055275970ScyGenerate GQ parameters and keys. 1056275970Scy.sp 1057275970ScyGenerate parameters and keys for the GQ identification scheme, 1058275970Scyobsoleting any that may exist. 1059275970Scy.It Fl H , Fl \-host\-key 1060275970Scygenerate RSA host key. 1061275970Scy.sp 1062275970ScyGenerate new host keys, obsoleting any that may exist. 1063275970Scy.It Fl I , Fl \-iffkey 1064275970Scygenerate IFF parameters. 1065275970Scy.sp 1066275970ScyGenerate parameters for the IFF identification scheme, obsoleting 1067275970Scyany that may exist. 1068275970Scy.It Fl i Ar group , Fl \-ident Ns = Ns Ar group 1069275970Scyset Autokey group name. 1070275970Scy.sp 1071275970ScySet the optional Autokey group name to name. This is used in 1072275970Scythe file name of IFF, GQ, and MV client parameters files. In 1073275970Scythat role, the default is the host name if this option is not 1074275970Scyprovided. The group name, if specified using \fB\-i/\-\-ident\fP or 1075275970Scyusing \fB\-s/\-\-subject\-name\fP following an '\fB@\fP' character, 1076330567Sgordonis also a part of the self\-signed host certificate subject and 1077275970Scyissuer names in the form \fBhost@group\fP and should match the 1078330567Sgordon\'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in the 1079330567Sgordon\fBntpd\fP configuration file. 1080275970Scy.It Fl l Ar lifetime , Fl \-lifetime Ns = Ns Ar lifetime 1081275970Scyset certificate lifetime. 1082275970ScyThis option takes an integer number as its argument. 1083275970Scy.sp 1084275970ScySet the certificate expiration to lifetime days from now. 1085275970Scy.It Fl m Ar modulus , Fl \-modulus Ns = Ns Ar modulus 1086330567Sgordonprime modulus. 1087275970ScyThis option takes an integer number as its argument. 1088275970ScyThe value of 1089275970Scy.Ar modulus 1090275970Scyis constrained to being: 1091275970Scy.in +4 1092275970Scy.nf 1093275970Scy.na 1094275970Scyin the range 256 through 2048 1095275970Scy.fi 1096275970Scy.in -4 1097275970Scy.sp 1098275970ScyThe number of bits in the prime modulus. The default is 512. 1099330567Sgordon.It Fl M , Fl \-md5key 1100330567Sgordongenerate symmetric keys. 1101330567Sgordon.sp 1102330567SgordonGenerate symmetric keys, obsoleting any that may exist. 1103275970Scy.It Fl P , Fl \-pvt\-cert 1104275970Scygenerate PC private certificate. 1105275970Scy.sp 1106275970ScyGenerate a private certificate. By default, the program generates 1107275970Scypublic certificates. 1108275970Scy.It Fl p Ar passwd , Fl \-password Ns = Ns Ar passwd 1109275970Scylocal private password. 1110275970Scy.sp 1111275970ScyLocal files containing private data are encrypted with the 1112275970ScyDES\-CBC algorithm and the specified password. The same password 1113275970Scymust be specified to the local ntpd via the "crypto pw password" 1114275970Scyconfiguration command. The default password is the local 1115275970Scyhostname. 1116275970Scy.It Fl q Ar passwd , Fl \-export\-passwd Ns = Ns Ar passwd 1117275970Scyexport IFF or GQ group keys with password. 1118275970Scy.sp 1119275970ScyExport IFF or GQ identity group keys to the standard output, 1120275970Scyencrypted with the DES\-CBC algorithm and the specified password. 1121275970ScyThe same password must be specified to the remote ntpd via the 1122275970Scy"crypto pw password" configuration command. See also the option 1123275970Scy-\-id\-key (\-e) for unencrypted exports. 1124275970Scy.It Fl s Ar host@group , Fl \-subject\-name Ns = Ns Ar host@group 1125275970Scyset host and optionally group name. 1126275970Scy.sp 1127275970ScySet the Autokey host name, and optionally, group name specified 1128275970Scyfollowing an '\fB@\fP' character. The host name is used in the file 1129275970Scyname of generated host and signing certificates, without the 1130275970Scygroup name. The host name, and if provided, group name are used 1131330567Sgordonin \fBhost@group\fP form for the host certificate subject and issuer 1132275970Scyfields. Specifying '\fB\-s @group\fP' is allowed, and results in 1133275970Scyleaving the host name unchanged while appending \fB@group\fP to the 1134275970Scysubject and issuer fields, as with \fB\-i group\fP. The group name, or 1135275970Scyif not provided, the host name are also used in the file names 1136275970Scyof IFF, GQ, and MV client parameter files. 1137330567Sgordon.It Fl S Ar sign , Fl \-sign\-key Ns = Ns Ar sign 1138330567Sgordongenerate sign key (RSA or DSA). 1139330567Sgordon.sp 1140330567SgordonGenerate a new sign key of the designated type, obsoleting any 1141330567Sgordonthat may exist. By default, the program uses the host key as the 1142330567Sgordonsign key. 1143275970Scy.It Fl T , Fl \-trusted\-cert 1144275970Scytrusted certificate (TC scheme). 1145275970Scy.sp 1146275970ScyGenerate a trusted certificate. By default, the program generates 1147275970Scya non\-trusted certificate. 1148275970Scy.It Fl V Ar num , Fl \-mv\-params Ns = Ns Ar num 1149275970Scygenerate <num> MV parameters. 1150275970ScyThis option takes an integer number as its argument. 1151275970Scy.sp 1152275970ScyGenerate parameters and keys for the Mu\-Varadharajan (MV) 1153275970Scyidentification scheme. 1154275970Scy.It Fl v Ar num , Fl \-mv\-keys Ns = Ns Ar num 1155275970Scyupdate <num> MV keys. 1156275970ScyThis option takes an integer number as its argument. 1157275970Scy.sp 1158275970ScyThis option has not been fully documented. 1159275970Scy.It Fl \&? , Fl \-help 1160275970ScyDisplay usage information and exit. 1161275970Scy.It Fl \&! , Fl \-more\-help 1162275970ScyPass the extended usage information through a pager. 1163275970Scy.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc 1164275970ScySave the option state to \fIcfgfile\fP. The default is the \fIlast\fP 1165275970Scyconfiguration file listed in the \fBOPTION PRESETS\fP section, below. 1166275970ScyThe command will exit after updating the config file. 1167275970Scy.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts 1168275970ScyLoad options from \fIcfgfile\fP. 1169275970ScyThe \fIno\-load\-opts\fP form will disable the loading 1170275970Scyof earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, 1171275970Scyout of order. 1172275970Scy.It Fl \-version Op Brq Ar v|c|n 1173275970ScyOutput version of program and exit. The default mode is `v', a simple 1174275970Scyversion. The `c' mode will print copyright information and `n' will 1175275970Scyprint the full copyright notice. 1176275970Scy.El 1177275970Scy.Sh "OPTION PRESETS" 1178275970ScyAny option that is not marked as \fInot presettable\fP may be preset 1179275970Scyby loading values from configuration ("RC" or ".INI") file(s) and values from 1180275970Scyenvironment variables named: 1181275970Scy.nf 1182275970Scy \fBNTP_KEYGEN_<option\-name>\fP or \fBNTP_KEYGEN\fP 1183275970Scy.fi 1184275970Scy.ad 1185275970ScyThe environmental presets take precedence (are processed later than) 1186275970Scythe configuration files. 1187275970ScyThe \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 1188275970ScyIf any of these are directories, then the file \fI.ntprc\fP 1189275970Scyis searched for within those directories. 1190275970Scy.Sh USAGE 1191275970Scy.Sh "ENVIRONMENT" 1192275970ScySee \fBOPTION PRESETS\fP for configuration environment variables. 1193275970Scy.Sh "FILES" 1194275970ScySee \fBOPTION PRESETS\fP for configuration files. 1195275970Scy.Sh "EXIT STATUS" 1196275970ScyOne of the following exit values will be returned: 1197275970Scy.Bl -tag 1198275970Scy.It 0 " (EXIT_SUCCESS)" 1199275970ScySuccessful program execution. 1200275970Scy.It 1 " (EXIT_FAILURE)" 1201275970ScyThe operation failed or the command syntax was not valid. 1202275970Scy.It 66 " (EX_NOINPUT)" 1203275970ScyA specified configuration file could not be loaded. 1204275970Scy.It 70 " (EX_SOFTWARE)" 1205275970Scylibopts had an internal operational error. Please report 1206275970Scyit to autogen\-users@lists.sourceforge.net. Thank you. 1207275970Scy.El 1208275970Scy.Sh "AUTHORS" 1209280849ScyThe University of Delaware and Network Time Foundation 1210275970Scy.Sh "COPYRIGHT" 1211316722SdelphijCopyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. 1212275970ScyThis program is released under the terms of the NTP license, <http://ntp.org/license>. 1213275970Scy.Sh BUGS 1214330567SgordonIt can take quite a while to generate some cryptographic values. 1215275970Scy.Pp 1216275970ScyPlease report bugs to http://bugs.ntp.org . 1217275970Scy.Pp 1218275970ScyPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 1219275970Scy.Sh NOTES 1220275970ScyPortions of this document came from FreeBSD. 1221275970Scy.Pp 1222275970ScyThis manual page was \fIAutoGen\fP\-erated from the \fBntp\-keygen\fP 1223275970Scyoption definitions. 1224