1ntp-keygen(8)                    User Commands                   ntp-keygen(8)
2
3
4

NAME

6       ntp-keygen - Create a NTP host key
7

SYNOPSIS

9       ntp-keygen [-flags] [-flag [value]] [--option-name[[=| ]value]]
10
11       All arguments must be options.
12
13

DESCRIPTION

15       This  program  generates  cryptographic  data  files  used by the NTPv4
16       authentication and identification schemes.   It  can  generate  message
17       digest  keys  used  in  symmetric  key cryptography and, if the OpenSSL
18       software library has been installed, it can generate host keys, signing
19       keys,  certificates,  and  identity keys and parameters used in Autokey
20       public key cryptography.  These files are used for  cookie  encryption,
21       digital  signature,  and  challenge/response  identification algorithms
22       compatible with the Internet standard security infrastructure.
23
24       The message digest symmetric keys file is generated in a format compat‐
25       ible  with  NTPv3.   All other files are in PEM-encoded printable ASCII
26       format, so they can be embedded as MIME attachments in email  to  other
27       sites   and   certificate  authorities.   By  default,  files  are  not
28       encrypted.
29
30       When used to generate message digest symmetric keys, the  program  pro‐
31       duces a file containing ten pseudo-random printable ASCII strings suit‐
32       able for the MD5 message digest algorithm included in the distribution.
33       If the OpenSSL library is installed, it produces an additional ten hex-
34       encoded random bit strings suitable for SHA1, AES-128-CMAC,  and  other
35       message digest algorithms.  The message digest symmetric keys file must
36       be distributed and stored using secure means beyond the  scope  of  NTP
37       itself.   Besides  the  keys  used for ordinary NTP associations, addi‐
38       tional keys can be defined as passwords for the  ntpq(8)  and  ntpdc(8)
39       utility programs.
40
41       The  remaining generated files are compatible with other OpenSSL appli‐
42       cations and other Public Key Infrastructure (PKI) resources.   Certifi‐
43       cates  generated  by  this  program are compatible with extant industry
44       practice, although some users might find the interpretation  of  X509v3
45       extension  fields  somewhat  liberal.   However,  the identity keys are
46       probably not compatible with anything other than Autokey.
47
48       Some files used by this program are encrypted using a private password.
49       The -p option specifies the read password for local encrypted files and
50       the -q option the write password for encrypted  files  sent  to  remote
51       sites.  If no password is specified, the host name returned by the Unix
52       hostname(1) command, normally the DNS name of the host, is used as  the
53       the  default  read  password,  for convenience.  The ntp-keygen program
54       prompts for the password if it reads an encrypted file and the password
55       is missing or incorrect.  If an encrypted file is read successfully and
56       no write password is specified, the read password is used as the  write
57       password by default.
58
59       The pw option of the crypto ntpd(8) configuration command specifies the
60       read password for previously encrypted local files.   This  must  match
61       the  local  read  password used by this program.  If not specified, the
62       host name is used.  Thus, if files are generated by this program  with‐
63       out  an  explicit  password,  they  can be read back by ntpd(8) without
64       specifying an explicit password but only on  the  same  host.   If  the
65       write password used for encryption is specified as the host name, these
66       files can be read by that host with no explicit password.
67
68       Normally, encrypted files for each host are generated by that host  and
69       used  only  by  that  host, although exceptions exist as noted later on
70       this page.  The symmetric keys file, normally called ntp.keys, is  usu‐
71       ally installed in /etc.  Other files and links are usually installed in
72       /usr/local/etc, which is normally in a shared filesystem in NFS-mounted
73       networks  and cannot be changed by shared clients.  In these cases, NFS
74       clients can specify the files in another directory such as  /etc  using
75       the keysdir ntpd(8) configuration file command.
76
77       This  program  directs  commentary  and  error messages to the standard
78       error stream stderr and remote files to the standard output stream std‐
79       out  where  they  can  be  piped to other applications or redirected to
80       files.  The names used for generated files and links all begin with the
81       string   ntpkey*  and  include  the  file  type,  generating  host  and
82       filestamp, as described in the Cryptographic Data Files section below.
83
84   Running the Program
85       The safest way to run the ntp-keygen program is logged in  directly  as
86       root.   The recommended procedure is change to the keys directory, usu‐
87       ally /usr/local/etc, then run the program.
88
89       To test and gain experience with Autokey concepts, log in as  root  and
90       change to the keys directory, usually /usr/local/etc.  When run for the
91       first time, or if all files with names beginning with ntpkey* have been
92       removed,  use  the  ntp-keygen  command without arguments to generate a
93       default RSA host key and matching RSA-MD5 certificate file with expira‐
94       tion date one year hence, which is all that is necessary in many cases.
95       The program also generates soft links from the  generic  names  to  the
96       respective  files.   If run again without options, the program uses the
97       existing keys and parameters and generates a new certificate file  with
98       new expiration date one year hence, and soft link.
99
100       The host key is used to encrypt the cookie when required and so must be
101       RSA type.  By default, the host key  is  also  the  sign  key  used  to
102       encrypt signatures.  When necessary, a different sign key can be speci‐
103       fied and this can be either RSA or DSA type.  By default,  the  message
104       digest  type  is  MD5, but any combination of sign key type and message
105       digest type supported by the OpenSSL library can be specified,  includ‐
106       ing  those  using the AES128CMAC, MD2, MD5, MDC2, SHA, SHA1 and RIPE160
107       message digest algorithms.  However, the scheme specified in  the  cer‐
108       tificate  must be compatible with the sign key.  Certificates using any
109       digest algorithm are compatible with RSA sign keys; however,  only  SHA
110       and SHA1 certificates are compatible with DSA sign keys.
111
112       Private/public  key  files  and  certificates are compatible with other
113       OpenSSL applications and very likely other libraries as well.  Certifi‐
114       cates  or  certificate  requests derived from them should be compatible
115       with extant industry practice,  although  some  users  might  find  the
116       interpretation  of  X509v3 extension fields somewhat liberal.  However,
117       the identification parameter  files,  although  encoded  as  the  other
118       files, are probably not compatible with anything other than Autokey.
119
120       Running the program as other than root and using the Unix su(1) command
121       to assume root may not work properly,  since  by  default  the  OpenSSL
122       library looks for the random seed file .rnd in the user home directory.
123       However, there should be only one .rnd, most conveniently in  the  root
124       directory, so it is convenient to define the RANDFILE environment vari‐
125       able used by the OpenSSL library as the path to .rnd.
126
127       Installing the keys as root might not work in NFS-mounted  shared  file
128       systems,  as  NFS  clients  may not be able to write to the shared keys
129       directory, even as root.  In this case, NFS  clients  can  specify  the
130       files  in another directory such as /etc using the keysdir ntpd(8) con‐
131       figuration file command.  There is no need for one client to  read  the
132       keys  and  certificates  of other clients or servers, as these data are
133       obtained automatically by the Autokey protocol.
134
135       Ordinarily, cryptographic files are generated by  the  host  that  uses
136       them,  but  it  is  possible for a trusted agent (TA) to generate these
137       files for other hosts; however, in such cases files  should  always  be
138       encrypted.   The  subject name and trusted name default to the hostname
139       of the host generating the files, but can be changed  by  command  line
140       options.  It is convenient to designate the owner name and trusted name
141       as the subject and issuer fields,  respectively,  of  the  certificate.
142       The  owner name is also used for the host and sign key files, while the
143       trusted name is used for the identity files.
144
145       All  files  are  installed   by   default   in   the   keys   directory
146       /usr/local/etc, which is normally in a shared filesystem in NFS-mounted
147       networks.  The actual location of the keys directory and each file  can
148       be  overridden  by configuration commands, but this is not recommended.
149       Normally, the files for each host are generated by that host  and  used
150       only  by  that  host,  although exceptions exist as noted later on this
151       page.
152
153       Normally, files containing private values, including the host key, sign
154       key  and identification parameters, are permitted root read/write-only;
155       while others containing public values  are  permitted  world  readable.
156       Alternatively,  files  containing  private  values can be encrypted and
157       these files permitted world readable, which simplifies  maintenance  in
158       shared  file  systems.  Since uniqueness is insured by the hostname and
159       filestamp file name extensions, the files for an NTP server and  depen‐
160       dent clients can all be installed in the same shared directory.
161
162       The  recommended  practice  is  to  keep  the file name extensions when
163       installing a file and to install a soft link  from  the  generic  names
164       specified  elsewhere  on this page to the generated files.  This allows
165       new file generations to be activated simply by changing the link.  If a
166       link  is  present,  ntpd(8)  follows it to the file name to extract the
167       filestamp.  If a link is not present, ntpd(8)  extracts  the  filestamp
168       from  the file itself.  This allows clients to verify that the file and
169       generation times are always current.  The ntp-keygen program  uses  the
170       same  filestamp  extension for all files generated at one time, so each
171       generation is distinct and can  be  readily  recognized  in  monitoring
172       data.
173
174       Run  the  command on as many hosts as necessary.  Designate one of them
175       as the trusted host (TH) using ntp-keygen with the -T option  and  con‐
176       figure  it to synchronize from reliable Internet servers.  Then config‐
177       ure the other hosts to synchronize to the TH directly or indirectly.  A
178       certificate  trail  is created when Autokey asks the immediately ascen‐
179       dant host towards the TH to sign its certificate, which  is  then  pro‐
180       vided  to  the immediately descendant host on request.  All group hosts
181       should have acyclic certificate trails ending on the TH.
182
183       The host key is used to encrypt the cookie when required and so must be
184       RSA  type.   By  default,  the  host  key  is also the sign key used to
185       encrypt signatures.  A different sign key can be assigned using the  -S
186       option  and this can be either RSA or DSA type.  By default, the signa‐
187       ture message digest type is MD5, but any combination of sign  key  type
188       and  message digest type supported by the OpenSSL library can be speci‐
189       fied using the -c option.
190
191       The rules say cryptographic media should be  generated  with  proventic
192       filestamps,  which means the host should already be synchronized before
193       this program is run.  This of course creates a chicken-and-egg  problem
194       when  the  host  is  started for the first time.  Accordingly, the host
195       time should be set by some other means, such as eyeball-and-wristwatch,
196       at  least  so that the certificate lifetime is within the current year.
197       After that and when the host is synchronized to a proventic source, the
198       certificate should be re-generated.
199
200       Additional information on trusted groups and identity schemes is on the
201       Autokey Public-Key Authentication page.
202
203       File names begin with the prefix ntpkey_ and end with the suffix _host‐
204       name.  filestamp,  where hostname is the owner name, usually the string
205       returned by the Unix hostname(1) command, and filestamp is the NTP sec‐
206       onds when the file was generated, in decimal digits.  This both guaran‐
207       tees uniqueness and simplifies maintenance procedures, since all  files
208       can  be  quickly removed by a rm ntpkey* command or all files generated
209       at a specific time can be removed by a rm *filestamp command.  To  fur‐
210       ther reduce the risk of misconfiguration, the first two lines of a file
211       contain the file name and generation date and time as comments.
212
213   Trusted Hosts and Groups
214       Each cryptographic configuration  involves  selection  of  a  signature
215       scheme  and identification scheme, called a cryptotype, as explained in
216       the Authentication Options section of ntp.conf(5).  The default crypto‐
217       type  uses  RSA  encryption,  MD5 message digest and TC identification.
218       First, configure a NTP subnet including one or more low-stratum trusted
219       hosts  from  which  all  other hosts derive synchronization directly or
220       indirectly.  Trusted hosts have trusted certificates; all  other  hosts
221       have  nontrusted  certificates.   These  hosts  will  automatically and
222       dynamically build authoritative  certificate  trails  to  one  or  more
223       trusted  hosts.   A  trusted  group  is the set of all hosts that have,
224       directly or indirectly, a certificate trail ending at a  trusted  host.
225       The  trail  is  defined by static configuration file entries or dynamic
226       means described on the Automatic NTP Configuration Options  section  of
227       ntp.conf(5).
228
229       On  each trusted host as root, change to the keys directory.  To insure
230       a fresh fileset, remove all ntpkey files.  Then run  ntp-keygen  -T  to
231       generate  keys  and  a  trusted certificate.  On all other hosts do the
232       same, but leave off the -T flag to generate keys  and  nontrusted  cer‐
233       tificates.   When complete, start the NTP daemons beginning at the low‐
234       est stratum and working up the tree.  It may take some time for Autokey
235       to  instantiate  the certificate trails throughout the subnet, but set‐
236       ting up the environment is completely automatic.
237
238       If it is necessary to use a different sign key or different digest/sig‐
239       nature scheme than the default, run ntp-keygen with the -S type option,
240       where type is either RSA or DSA.  The most frequent need to do this  is
241       when  a  DSA-signed  certificate  is used.  If it is necessary to use a
242       different certificate scheme than the default, run ntp-keygen with  the
243       -c  scheme  option and selected scheme as needed.  If ntp-keygen is run
244       again without these options, it generates a new certificate  using  the
245       same scheme and sign key, and soft link.
246
247       After setting up the environment it is advisable to update certificates
248       from time to time, if only to extend the validity interval.  Simply run
249       ntp-keygen  with  the same flags as before to generate new certificates
250       using existing keys, and soft links.  However, if the host or sign  key
251       is changed, ntpd(8) should be restarted.  When ntpd(8) is restarted, it
252       loads any new files and restarts the protocol.  Other  dependent  hosts
253       will  continue  as  usual until signatures are refreshed, at which time
254       the protocol is restarted.
255
256   Identity Schemes
257       As mentioned on the Autonomous  Authentication  page,  the  default  TC
258       identity  scheme  is  vulnerable to a middleman attack.  However, there
259       are more secure identity schemes available, including PC, IFF,  GQ  and
260       MV  schemes  described  below.  These schemes are based on a TA, one or
261       more trusted hosts and some number of nontrusted hosts.  Trusted  hosts
262       prove  identity  using  values  provided by the TA, while the remaining
263       hosts prove identity using values provided by a trusted host  and  cer‐
264       tificate  trails  that end on that host.  The name of a trusted host is
265       also the name of its sugroup and also the subject and  issuer  name  on
266       its  trusted  certificate.  The TA is not necessarily a trusted host in
267       this sense, but often is.
268
269       In some schemes there are separate keys for  servers  and  clients.   A
270       server  can  also be a client of another server, but a client can never
271       be a server for another client.  In general,  trusted  hosts  and  non‐
272       trusted  hosts  that  operate  as both server and client have parameter
273       files that contain both server and client  keys.   Hosts  that  operate
274       only as clients have key files that contain only client keys.
275
276       The  PC scheme supports only one trusted host in the group.  On trusted
277       host alice run ntp-keygen -P -p password to generate the host key  file
278       ntpkey_  RSA  key_alice. filestamp and trusted private certificate file
279       ntpkey_ RSA-MD5 _ cert_alice. filestamp, and  soft  links.   Copy  both
280       files  to all group hosts; they replace the files which would be gener‐
281       ated in other schemes.  On each host bob install a soft link  from  the
282       generic  name  ntpkey_host_bob  to the host key file and soft link ntp‐
283       key_cert_bob to the private certificate file.  Note the  generic  links
284       are  on  bob,  but  point to files generated by trusted host alice.  In
285       this scheme it is not possible to refresh either the keys  or  certifi‐
286       cates  without copying them to all other hosts in the group, and recre‐
287       ating the soft links.
288
289       For the IFF scheme proceed as in the TC scheme  to  generate  keys  and
290       certificates  for  all  group hosts, then for every trusted host in the
291       group, generate the IFF parameter file.  On trusted host alice run ntp-
292       keygen  -T  -I  -p  password  to produce her parameter file ntpkey_IFF‐
293       par_alice.filestamp, which includes both server and client keys.   Copy
294       this  file  to all group hosts that operate as both servers and clients
295       and install a soft link from the generic ntpkey_iff_alice to this file.
296       If  there  are no hosts restricted to operate only as clients, there is
297       nothing further to do.  As the IFF scheme is independent  of  keys  and
298       certificates, these files can be refreshed as needed.
299
300       If  a  rogue  client  has  the parameter file, it could masquerade as a
301       legitimate server and present a middleman threat.   To  eliminate  this
302       threat,  the  client  keys can be extracted from the parameter file and
303       distributed to all restricted clients.  After generating the  parameter
304       file, on alice run ntp-keygen -e and pipe the output to a file or email
305       program.  Copy or email this file to all restricted clients.  On  these
306       clients  install  a soft link from the generic ntpkey_iff_alice to this
307       file.  To further protect the integrity of the keys, each file  can  be
308       encrypted with a secret password.
309
310       For the GQ scheme proceed as in the TC scheme to generate keys and cer‐
311       tificates for all group hosts, then  for  every  trusted  host  in  the
312       group, generate the IFF parameter file.  On trusted host alice run ntp-
313       keygen  -T  -G  -p  password  to  produce  her  parameter   file   ntp‐
314       key_GQpar_alice.filestamp,  which includes both server and client keys.
315       Copy this file to all group hosts and install  a  soft  link  from  the
316       generic  ntpkey_gq_alice  to  this file.  In addition, on each host bob
317       install a soft link from generic ntpkey_gq_bob to this file.  As the GQ
318       scheme updates the GQ parameters file and certificate at the same time,
319       keys and certificates can be regenerated as needed.
320
321       For the MV scheme, proceed as in the TC scheme  to  generate  keys  and
322       certificates for all group hosts.  For illustration assume trish is the
323       TA, alice one of several trusted hosts and bob one of her clients.   On
324       TA  trish  run  ntp-keygen  -V  n -p password, where n is the number of
325       revokable keys  (typically  5)  to  produce  the  parameter  file  ntp‐
326       keys_MVpar_trish.filestamp and client key files ntpkeys_MVkeyd _ trish.
327       filestamp where d is the key number (0 < d < n).   Copy  the  parameter
328       file  to alice and install a soft link from the generic ntpkey_mv_alice
329       to this file.  Copy one of the client key files to alice for later dis‐
330       tribution  to  her  clients.   It does not matter which client key file
331       goes to alice, since they all work the  same  way.   Alice  copies  the
332       client  key  file  to all of her clients.  On client bob install a soft
333       link from generic ntpkey_mvkey_bob to the client key file.  As  the  MV
334       scheme  is  independent  of  keys  and certificates, these files can be
335       refreshed as needed.
336
337   Command Line Options
338       -b --imbits= modulus
339              Set the number of bits in the identity  modulus  for  generating
340              identity  keys to modulus bits.  The number of bits in the iden‐
341              tity modulus defaults to 256, but can be set to values from  256
342              to 2048 (32 to 256 octets).  Use the larger moduli with caution,
343              as  this  can  consume  considerable  computing  resources   and
344              increases the size of authenticated packets.
345
346       -c --certificate= scheme
347              Select  certificate  signature encryption/message digest scheme.
348              The scheme can be one of the following: RSA-MD2,  RSA-MD5,  RSA-
349              MDC2,  RSA-SHA,  RSA-SHA1,  RSA-RIPEMD160, DSA-SHA, or DSA-SHA1.
350              Note that RSA schemes must be used with an RSA sign key and  DSA
351              schemes  must  be used with a DSA sign key.  The default without
352              this option is RSA-MD5.  If compatibility  with  FIPS  140-2  is
353              required, either the DSA-SHA or DSA-SHA1 scheme must be used.
354
355       -C --cipher= cipher
356              Select  the  OpenSSL cipher to encrypt the files containing pri‐
357              vate keys.  The default without this option is three-key  triple
358              DES  in CBC mode, des-ede3-cbc.  The openssl -h command provided
359              with OpenSSL displays available ciphers.
360
361       -d --debug-level
362              Increase debugging verbosity level.  This  option  displays  the
363              cryptographic data produced in eye-friendly billboards.
364
365       -D --set-debug-level= level
366              Set  the debugging verbosity to level.  This option displays the
367              cryptographic data produced in eye-friendly billboards.
368
369       -e --id-key
370              Write the IFF or GQ public parameters from the IFFkey  or  GQkey
371              client keys file previously specified as unencrypted data to the
372              standard output stream stdout.  This is intended  for  automatic
373              key distribution by email.
374
375       -G --gq-params
376              Generate  a  new  encrypted  GQ  parameters and key file for the
377              Guillou-Quisquater (GQ) identity scheme.  This option  is  mutu‐
378              ally exclusive with the -I and -V options.
379
380       -H --host-key
381              Generate a new encrypted RSA public/private host key file.
382
383       -I --iffkey
384              Generate  a  new  encrypted  IFF  key file for the Schnorr (IFF)
385              identity scheme.  This option is mutually exclusive with the  -G
386              and Fl V options.
387
388       -i --ident= group
389              Set  the  optional Autokey group name to group.  This is used in
390              the identity scheme parameter file names  of  IFF,  GQ,  and  MV
391              client  parameters files.  In that role, the default is the host
392              name if no group is provided.   The  group  name,  if  specified
393              using -i or -s following an ‘@@’ character, is also used in cer‐
394              tificate subject and issuer names in the form host @@ group  and
395              should  match  the  group  specified  via crypto ident or server
396              ident in the ntpd configuration file.
397
398       -l --lifetime= days
399              Set the  lifetime  for  certificate  expiration  to  days.   The
400              default lifetime is one year (365 days).
401
402       -m --modulus= bits
403              Set the number of bits in the prime modulus for generating files
404              to bits.  The modulus defaults to 512, but can be set  from  256
405              to 2048 (32 to 256 octets).  Use the larger moduli with caution,
406              as  this  can  consume  considerable  computing  resources   and
407              increases the size of authenticated packets.
408
409       -M --md5key
410              Generate  a  new symmetric keys file containing 10 MD5 keys, and
411              if OpenSSL is available, 10 SHA keys.  An MD5 key is a string of
412              20  random  printable  ASCII  characters,  while  a SHA key is a
413              string of 40 random hex digits.  The file can be edited using  a
414              text  editor to change the key type or key content.  This option
415              is mutually exclusive with all other options.
416
417       -p --password= passwd
418              Set the password for reading  and  writing  encrypted  files  to
419              passwd.   These  include  the host, sign and identify key files.
420              By default, the password is the  string  returned  by  the  Unix
421              hostname command.
422
423       -P --pvt-cert
424              Generate  a  new  private  certificate  used  by the PC identity
425              scheme.  By default, the program generates public  certificates.
426              Note:  the PC identity scheme is not recommended for new instal‐
427              lations.
428
429       -q --export-passwd= passwd
430              Set the password for writing encrypted IFF, GQ and  MV  identity
431              files  redirected  to  stdout to passwd.  In effect, these files
432              are decrypted with the -p password, then encrypted with  the  -q
433              password.   By  default,  the password is the string returned by
434              the Unix hostname command.
435
436       -s --subject-key= [host] [@@ group]
437              Specify the Autokey host name, where host is the  optional  host
438              name  and  group is the optional group name.  The host name, and
439              if provided, group name are used in host @@ group form  as  cer‐
440              tificate  subject  and  issuer.   Specifying  -s  -@@  group  is
441              allowed, and results in leaving the host name unchanged, as with
442              -i  group.  The group name, or if no group is provided, the host
443              name are also used in the file names of IFF, GQ, and MV identity
444              scheme  client  parameter  files.  If host is not specified, the
445              default host name is the string returned by  the  Unix  hostname
446              command.
447
448       -S --sign-key= [RSA | DSA]
449              Generate  a  new  encrypted  public/private sign key file of the
450              specified type.  By default, the sign key is the  host  key  and
451              has  the  same  type.   If  compatibility  with  FIPS  140-2  is
452              required, the sign key type must be DSA.
453
454       -T --trusted-cert
455              Generate a trusted certificate.  By default, the program  gener‐
456              ates a non-trusted certificate.
457
458       -V --mv-params nkeys
459              Generate  nkeys encrypted server keys and parameters for the Mu-
460              Varadharajan (MV) identity  scheme.   This  option  is  mutually
461              exclusive  with  the  -I and -G options.  Note: support for this
462              option should be considered a work in progress.
463
464   Random Seed File
465       All cryptographically sound key generation schemes must have  means  to
466       randomize  the entropy seed used to initialize the internal pseudo-ran‐
467       dom number generator used by the library routines.  The OpenSSL library
468       uses  a designated random seed file for this purpose.  The file must be
469       available when starting the NTP daemon and ntp-keygen  program.   If  a
470       site  supports OpenSSL or its companion OpenSSH, it is very likely that
471       means to do this are already available.
472
473       It is important to understand that entropy must  be  evolved  for  each
474       generation,  for  otherwise  the  random  number sequence would be pre‐
475       dictable.  Various means dependent on external  events,  such  as  key‐
476       stroke intervals, can be used to do this and some systems have built-in
477       entropy sources.  Suitable means are described in the OpenSSL  software
478       documentation, but are outside the scope of this page.
479
480       The  entropy  seed  used by the OpenSSL library is contained in a file,
481       usually called .rnd, which must be available when starting the NTP dae‐
482       mon  or the ntp-keygen program.  The NTP daemon will first look for the
483       file using the path specified by the randfile subcommand of the  crypto
484       configuration  command.  If not specified in this way, or when starting
485       the ntp-keygen program, the OpenSSL library  will  look  for  the  file
486       using  the  path  specified by the RANDFILE environment variable in the
487       user home directory, whether root or some other user.  If the  RANDFILE
488       environment variable is not present, the library will look for the .rnd
489       file in the user home directory.  Since both the ntp-keygen program and
490       ntpd(8)  daemon must run as root, the logical place to put this file is
491       in /.rnd or /root/.rnd.  If the file is  not  available  or  cannot  be
492       written, the daemon exits with a message to the system log and the pro‐
493       gram exits with a suitable error message.
494
495   Cryptographic Data Files
496       All file formats begin with two nonencrypted  lines.   The  first  line
497       contains   the  file  name,  including  the  generated  host  name  and
498       filestamp, in the format ntpkey_key _ name. filestamp, where key is the
499       key  or parameter type, name is the host or group name and filestamp is
500       the filestamp (NTP seconds) when the file was created.  By  convention,
501       key  names  in  generated  file names include both upper and lower case
502       characters, while key names in generated link names include only  lower
503       case  characters.   The  filestamp is not used in generated link names.
504       The second line contains the datestamp in conventional Unix  date  for‐
505       mat.   Lines  beginning with ‘#’ are considered comments and ignored by
506       the ntp-keygen program and ntpd(8) daemon.
507
508       The remainder of the file contains cryptographic  data,  encoded  first
509       using  ASN.1 rules, then encrypted if necessary, and finally written in
510       PEM-encoded printable ASCII text, preceded and followed by MIME content
511       identifier lines.
512
513       The  format  of  the symmetric keys file, ordinarily named ntp.keys, is
514       somewhat different than the other files in  the  interest  of  backward
515       compatibility.   Ordinarily, the file is generated by this program, but
516       it can be constructed and edited using an ordinary text editor.
517           # ntpkey_MD5key_bk.ntp.org.3595864945
518           # Thu Dec 12 19:22:25 2013
519           1  MD5 L";Nw<`.I<f4U0)247"i  # MD5 key
520           2  MD5 &>l0%XXK9O'51VwV<xq~  # MD5 key
521           3  MD5 lb4zLW~d^!K:]RsD'qb6  # MD5 key
522           4  MD5 Yue:tL[+vR)M`n~bY,'?  # MD5 key
523           5  MD5 B;fx'Kgr/&4ZTbL6=RxA  # MD5 key
524           6  MD5 4eYwa`o}3i@@@@V@@..R9!l  # MD5 key
525           7  MD5 `A.([h+;wTQ|xfi%Sn_!  # MD5 key
526           8  MD5 45:V,r4]l6y^JH6"Sh?F  # MD5 key
527           9  MD5 3-5vcn*6l29DS?Xdsg)*  # MD5 key
528           10 MD5 2late4Me              # MD5 key
529           11 SHA1 a27872d3030a9025b8446c751b4551a7629af65c  # SHA1 key
530           12 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74  # SHA1 key
531           13 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9  # SHA1 key
532           14 SHA  a5332809c8878dd3a5b918819108a111509aeceb  # SHA  key
533           15 MD2  2fe16c88c760ff2f16d4267e36c1aa6c926e6964  # MD2  key
534           16 MD4  b2691811dc19cfc0e2f9bcacd74213f29812183d  # MD4  key
535           17 MD5  e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c  # MD5  key
536           18 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc  # MDC2 key
537           19 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2  # RIPEMD160 key
538           20 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878  # AES128CMAC key
539           Figure 1. Typical Symmetric Key File
540
541       Figure 1 shows a typical symmetric keys  file  used  by  the  reference
542       implementation.  Following the header the keys are entered one per line
543       in the format
544           keyno type key
545       where keyno is a positive integer in the range 1-65535; type is the key
546       type  for  the  message  digest  algorithm, which in the absence of the
547       OpenSSL library must be MD5 to designate the MD5 message  digest  algo‐
548       rithm;  if  the  OpenSSL  library is installed, the key type can be any
549       message digest algorithm supported by that library; however, if compat‐
550       ibility with FIPS 140-2 is required, the key type must be either SHA or
551       SHA1; key is the key itself, which is a printable ASCII string 20 char‐
552       acters  or  less in length: each character is chosen from the 93 print‐
553       able characters in the range 0x21 through 0x7e (  ‘’!   through  ‘~’  )
554       excluding  space and the ‘#’ character, and terminated by whitespace or
555       a ‘#’ character.  An OpenSSL key consists of a hex-encoded ASCII string
556       of 40 characters, which is truncated as necessary.
557
558       Note  that  the  keys  used  by  the  ntpq(8) and ntpdc(8) programs are
559       checked against passwords requested by  the  programs  and  entered  by
560       hand,  so  it  is  generally appropriate to specify these keys in human
561       readable ASCII format.
562
563       The  ntp-keygen  program  generates  a   symmetric   keys   file   ntp‐
564       key_MD5key_hostname. filestamp.  Since the file contains private shared
565       keys, it should be visible only to root and distributed by secure means
566       to other subnet hosts.  The NTP daemon loads the file ntp.keys, so ntp-
567       keygen installs a soft link from this name to the generated file.  Sub‐
568       sequently,  similar soft links must be installed by manual or automated
569       means on the other subnet hosts.  While this file is not used with  the
570       Autokey  Version  2  protocol, it is needed to authenticate some remote
571       configuration commands used by the ntpq(8) and ntpdc(8) utilities.
572

OPTIONS

574       -b imbits, --imbits=imbits
575              identity modulus bits.  This option takes an integer  number  as
576              its argument.  The value of imbits is constrained to being:
577                  in the range  256 through 2048
578
579              The number of bits in the identity modulus.  The default is 256.
580
581       -c scheme, --certificate=scheme
582              certificate scheme.
583
584              scheme is one of RSA-MD2, RSA-MD5, RSA-MDC2, RSA-SHA, RSA-SHA1,
585              RSA-RIPEMD160, DSA-SHA, or DSA-SHA1.
586
587              Select the certificate signature encryption/message digest
588              scheme.  Note that RSA schemes must be used with a RSA sign key
589              and DSA schemes must be used with a DSA sign key.  The default
590              without this option is RSA-MD5.
591
592       -C cipher, --cipher=cipher
593              privatekey cipher.
594
595              Select the cipher which is used to encrypt the files containing
596              private keys.  The default is three-key triple DES in CBC mode,
597              equivalent to "-C des-ede3-cbc".  The openssl tool lists ciphers
598              available in "openssl -h" output.
599
600       -d, --debug-level
601              Increase debug verbosity level.  This option may appear an
602              unlimited number of times.
603
604
605       -D number, --set-debug-level=number
606              Set the debug verbosity level.  This option may appear an unlim‐
607              ited number of times.  This option takes an integer number as
608              its argument.
609
610
611       -e, --id-key
612              Write IFF or GQ identity keys.
613
614              Write the public parameters from the IFF or GQ client keys to
615              the standard output.  This is intended for automatic key distri‐
616              bution by email.
617
618       -G, --gq-params
619              Generate GQ parameters and keys.
620
621              Generate parameters and keys for the GQ identification scheme,
622              obsoleting any that may exist.
623
624       -H, --host-key
625              generate RSA host key.
626
627              Generate new host keys, obsoleting any that may exist.
628
629       -I, --iffkey
630              generate IFF parameters.
631
632              Generate parameters for the IFF identification scheme, obsolet‐
633              ing any that may exist.
634
635       -i group, --ident=group
636              set Autokey group name.
637
638              Set the optional Autokey group name to name.  This is used in
639              the file name of IFF, GQ, and MV client parameters files.  In
640              that role, the default is the host name if this option is not
641              provided.  The group name, if specified using -i/--ident or
642              using -s/--subject-name following an '@@' character, is also a
643              part of the self-signed host certificate subject and issuer
644              names in the form host@@group and should match the ntpd configu‐
645              ration file.
646
647       -l lifetime, --lifetime=lifetime
648              set certificate lifetime.  This option takes an integer number
649              as its argument.
650
651              Set the certificate expiration to lifetime days from now.
652
653       -m modulus, --modulus=modulus
654              prime modulus.  This option takes an integer number as its argu‐
655              ment.  The value of modulus is constrained to being:
656                  in the range  256 through 2048
657
658              The number of bits in the prime modulus.  The default is 512.
659
660       -M, --md5key
661              generate symmetric keys.
662
663              Generate symmetric keys, obsoleting any that may exist.
664
665       -P, --pvt-cert
666              generate PC private certificate.
667
668              Generate a private certificate.  By default, the program gener‐
669              ates public certificates.
670
671       -p passwd, --password=passwd
672              local private password.
673
674              Local files containing private data are encrypted with the DES-
675              CBC algorithm and the specified password.  The same password
676              must be specified to the local ntpd via the "crypto pw password"
677              configuration command.  The default password is the local host‐
678              name.
679
680       -q passwd, --export-passwd=passwd
681              export IFF or GQ group keys with password.
682
683              Export IFF or GQ identity group keys to the standard output,
684              encrypted with the DES-CBC algorithm and the specified password.
685              The same password must be specified to the remote ntpd via the
686              "crypto pw password" configuration command.  See also the option
687              --id-key (-e) for unencrypted exports.
688
689       -s host@group, --subject-name=host@group
690              set host and optionally group name.
691
692              Set the Autokey host name, and optionally, group name specified
693              following an '@@' character.  The host name is used in the file
694              name of generated host and signing certificates, without the
695              group name.  The host name, and if provided, group name are used
696              in host@@group form for the host certificate subject and issuer
697              fields.  Specifying '-s @@group' is allowed, and results in
698              leaving the host name unchanged while appending @@group to the
699              subject and issuer fields, as with -i group.  The group name, or
700              if not provided, the host name are also used in the file names
701              of IFF, GQ, and MV client parameter files.
702
703       -S sign, --sign-key=sign
704              generate sign key (RSA or DSA).
705
706              Generate a new sign key of the designated type, obsoleting any
707              that may exist.  By default, the program uses the host key as
708              the sign key.
709
710       -T, --trusted-cert
711              trusted certificate (TC scheme).
712
713              Generate a trusted certificate.  By default, the program gener‐
714              ates a non-trusted certificate.
715
716       -V num, --mv-params=num
717              generate <num> MV parameters.  This option takes an integer num‐
718              ber as its argument.
719
720              Generate parameters and keys for the Mu-Varadharajan (MV) iden‐
721              tification scheme.
722
723       -v num, --mv-keys=num
724              update <num> MV keys.  This option takes an integer number as
725              its argument.
726
727              This option has not been fully documented.
728
729       -?, --help
730              Display usage information and exit.
731
732       -!, --more-help
733              Pass the extended usage information through a pager.
734
735       -> [cfgfile], --save-opts [=cfgfile]
736              Save the option state to cfgfile.  The default is the last con‐
737              figuration file listed in the OPTION PRESETS section, below.
738              The command will exit after updating the config file.
739
740       -< cfgfile, --load-opts=cfgfile, --no-load-opts
741              Load options from cfgfile.  The no-load-opts form will disable
742              the loading of earlier config/rc/ini files.  --no-load-opts is
743              handled early, out of order.
744
745       --version [{v|c|n}]
746              Output version of program and exit.  The default mode is `v', a
747              simple version.  The `c' mode will print copyright information
748              and `n' will print the full copyright notice.
749

OPTION PRESETS

751       Any option that is not marked as not presettable may be preset by load‐
752       ing values from configuration ("RC" or ".INI") file(s) and values from
753       environment variables named:
754         NTP_KEYGEN_<option-name> or NTP_KEYGEN
755       The environmental presets take precedence (are  processed  later  than)
756       the  configuration  files.   The homerc files are "$HOME", and ".".  If
757       any of these are directories, then the  file  .ntprc  is  searched  for
758       within those directories.
759

USAGE

ENVIRONMENT

762       See OPTION PRESETS for configuration environment variables.
763

FILES

765       See OPTION PRESETS for configuration files.
766

EXIT STATUS

768       One of the following exit values will be returned:
769
770       0  (EXIT_SUCCESS)
771              Successful program execution.
772
773       1  (EXIT_FAILURE)
774              The operation failed or the command syntax was not valid.
775
776       66  (EX_NOINPUT)
777              A specified configuration file could not be loaded.
778
779       70  (EX_SOFTWARE)
780              libopts  had an internal operational error.  Please report it to
781              autogen-users@lists.sourceforge.net.  Thank you.
782

AUTHORS

784       The University of Delaware and Network Time Foundation
785
787       Copyright (C) 1992-2017 The University of  Delaware  and  Network  Time
788       Foundation  all  rights  reserved.   This program is released under the
789       terms of the NTP license, <http://ntp.org/license>.
790

BUGS

792       It can take quite a while to generate some cryptographic values.
793
794       Please report bugs to http://bugs.ntp.org .
795
796       Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
797

NOTES

799       Portions of this document came from FreeBSD.
800
801       This manual page was AutoGen-erated from the ntp-keygen option  defini‐
802       tions.
803
804
805
806ntp (4.2.8p13)                    20 Feb 2019                    ntp-keygen(8)
Impressum