1ntp_auth(5)                   File Formats Manual                  ntp_auth(5)
2
3
4

NAME

6       ntp_auth - Authentication Options
7
8

INTRODUCTION

10       This page describes the various cryptographic authentication provisions
11       in NTPv4. Details about the  configuration  commands  and  options  are
12       given  on  the  Configuration Options page. Details about the automatic
13       server discovery schemes are described on the Automatic Server  Discov‐
14       ery  Schemes  page.  Additional information is available in the papers,
15       reports, memoranda and  briefings  cited  on  the   NTP  Project  page.
16       Authentication support allows the NTP client to verify that servers are
17       in fact known and trusted and not intruders intending  accidentally  or
18       intentionally to masquerade as a legitimate server.
19
20        The  NTPv3  specification RFC-1305 defines a scheme properly described
21       as symmetric key cryptography. It uses  the  Data  Encryption  Standard
22       (DES)  algorithm  operating in cipher-block chaining (CBC) mode. Subse‐
23       quently, this scheme was replaced by the RSA  Message  Digest  5  (MD5)
24       algorithm  commonly  called keyed-MD5. Either algorithm computes a mes‐
25       sage digest or one-way hash which can be used to verify the client  has
26       the  same  key and key identifier as the server. If the OpenSSL crypto‐
27       graphic library is installed, support is available for  all  algorithms
28       included  in the library. Note however, if conformance to FIPS 140-2 is
29       required, only a limited subset of these algorithms is available.
30
31       NTPv4 includes the NTPv3 scheme and optionally a new  scheme  based  on
32       public  key cryptography and called Autokey. Public key cryptography is
33       generally considered more secure than symmetric key cryptography, since
34       the  security is based on private and public values which are generated
35       by each participant and where the  private  value  is  never  revealed.
36       Autokey  uses  X.509 public certificates, which can be produced by com‐
37       mercial services, utility programs in the OpenSSL software  library  or
38       the ntp-keygen utility program in the NTP software distribution.
39
40       While the algorithms for MD5 symmetric key cryptography are included in
41       the NTPv4 software distribution, modern algorithms  for  symmetric  key
42       and public key cryptograpny requires the OpenSSL software library to be
43       installed before building the NTP distribution. This library is  avail‐
44       able  from http://www.openssl.org and can be installed using the proce‐
45       dures outlined in the Building and Installing  the  Distribution  page.
46       Once  installed,  the configure and build process automatically detects
47       the library and links the library routines required.
48
49       Note that according to US law, NTP binaries including  OpenSSL  library
50       components,  including  the  OpenSSL library itself, cannot be exported
51       outside the US without license from  the  US  Department  of  Commerce.
52       Builders  outside  the  US  are  advised  to obtain the OpenSSL library
53       directly from OpenSSL, which is outside the US, and build  outside  the
54       US.
55
56       Authentication  is configured separately for each association using the
57       key or autokey option of the server configuration command, as described
58       in the Server Options page, and the options described on this page. The
59       ntp-keygen page describes the files required for the various  authenti‐
60       cation  schemes.  Further  details  are  in  the  briefings, papers and
61       reports at the NTP project page linked from www.ntp.org.
62
63

SYMMETRIC KEY CRYPTOGRAPHY

65       The original RFC-1305 specification allows any one of  possibly  65,534
66       keys  (excluding  zero),  each  distinguished  by  a  32-bit key ID, to
67       authenticate an association. The  servers  and  clients  involved  must
68       agree  on  the key, key ID and key type to authenticate NTP packets. If
69       an NTP packet includes a message authentication code (MAC),  consisting
70       of  a  key  ID  and  message  digest, it is accepted only if the key ID
71       matches a trusted key and the message digest is verified with this key.
72       Note that for historic reasons the message digest algorithm is not con‐
73       sistent with RFC-1828. The digest is computed directly  from  the  con‐
74       catenation  of  the key string followed by the packet contents with the
75       exception of the MAC itself.
76
77       Keys and related information are specified  in  a  keys  file,  usually
78       called  ntp.keys,  which  must  be  distributed and stored using secure
79       means beyond the scope of the NTP protocol  itself.  Besides  the  keys
80       used  for  ordinary  NTP  associations,  additional keys can be used as
81       passwords for the ntpq and  ntpdc  utility  programs.  Ordinarily,  the
82       ntp.keys  file  is  generated  by the ntp-keygen program, but it can be
83       constructed and edited using an ordinary text editor. The program  gen‐
84       erates pseudo-random keys, one key for each line. Each line consists of
85       three fields, the key identifier as a decimal number from  1  to  65534
86       inclusive,  a key type chosen from the keywords of the digest option of
87       the crypto command, and a 20-character  printable  ASCII  string  or  a
88       40-character hex string as the key itself.
89
90       When ntpd is first started, it reads the key file specified by the keys
91       command and installs the keys in the  key  cache.  However,  individual
92       keys must be activated with the trustedkey configuration command before
93       use. This allows, for instance, the installation  of  possibly  several
94       batches  of  keys  and  then activating a key remotely using ntpdc. The
95       requestkey command selects the key ID used  as  the  password  for  the
96       ntpdc  utility, while the controlkey command selects the key ID used as
97       the password for the ntpq utility.
98
99       By default, the message digest algorithm is MD5  selected  by  the  key
100       type  M in the keys file. However, if the OpenSSL library is installed,
101       any message digest algorithm supported by that library can be used. The
102       key  type  is selected as the algorithm name given in the OpenSSL docu‐
103       mentation. The key type is associated with the key and can be different
104       for  different keys. The server and client must share the same key, key
105       ID and key type and both must be trusted. Note that if  conformance  to
106       FIPS  140-2  is  required, the message digest algorithm must conform to
107       the Secure Hash Standard (SHS), which requires an  algorithm  from  the
108       Secure  Hash  Algorithm (SHA) family, and the digital signature encryp‐
109       tion algorithm, if used, must conform to the Digital Signature Standard
110       (DSS), which requires the Digital Signature Algorithm (DSA).
111
112       In addition to the above means, ntpd now supports Microsoft Windows MS-
113       SNTP authentication using Active Directory services. This  support  was
114       contributed  by  the  Samba  Team  and  is  still in development. It is
115       enabled using the mssntp flag of the restrict command described on  the
116       Access Control Options page. Note: Potential users should be aware that
117       these services involve a TCP connection to another process  that  could
118       potentially  block,  denying  services  to other users. Therefore, this
119       flag should be used only for a dedicated server with no  clients  other
120       than MS-SNTP.
121
122

PUBLIC KEY CRYPTOGRAPHY

124       NTPv4  supports the Autokey security protocol, which is based on public
125       key cryptography. The Autokey  Version  2  protocol  described  on  the
126       Autokey  Protocol  page  verifies  packet  integrity  using MD5 message
127       digests and verifies the source using digital  signatures  and  any  of
128       several  digest/signature  schemes. Optional identity schemes described
129       on the Autokey Identity Schemes page are based on  cryptographic  chal‐
130       lenge/response exchanges. These schemes provide strong security against
131       replay with or without message modification, spoofing,  masquerade  and
132       most  forms of clogging attacks. These schemes are described along with
133       an executive summary, current status, briefing slides and reading  list
134       on the Autonomous Authentication page.
135
136       Autokey  authenticates individual packets using cookies bound to the IP
137       source and destination  addresses.  The  cookies  must  have  the  same
138       addresses at both the server and client. For this reason operation with
139       network address translation schemes is not possible. This reflects  the
140       intended  robust  security  model  where  government  and corporate NTP
141       servers are operated outside firewall perimeters.
142
143       There are three timeouts associated with the Autokey  scheme.  The  key
144       list  timeout,  which  defaults  to about 1.1 h, specifies the interval
145       between generating new key lists. The revoke timeout, which defaults to
146       about  36 h, specifies the interval between generating new private val‐
147       ues. The restart timeout, with default about 5 d, specifies the  inter‐
148       val between protocol restarts to refresh public values. In general, the
149       behavior when these timeouts expire is not affected by the issues  dis‐
150       cussed on this page.
151
152

NTP SECURE GROUPS

154       NTP  secure  groups  are  used to define cryptographic compartments and
155       security hierarchies. All hosts belonging to a secure  group  have  the
156       same  group  name but different host names. The string specified in the
157       host option of the crypto command is the name of the host and the  name
158       used in the host key, sign key and certificate files. The string speci‐
159       fied in the ident option of the crypto command is the group name of all
160       group  hosts  and  the name used in the identity files. The file naming
161       conventions are described on the ntp-keygen page.
162
163       Each group includes one or more trusted hosts (THs)  operating  at  the
164       root,  or  lowest  stratum  in the group. The group name is used in the
165       subject and issuer fields of the TH self-signed trusted certificate for
166       these  hosts. The host name is used in the subject and issuer fields of
167       the self-signed certificates for all other hosts.
168
169       All group hosts are configured to provide an unbroken  path,  called  a
170       certificate  trail, from each host, possibly via intermediate hosts and
171       ending at a TH. When a host starts up,  it  recursively  retrieves  the
172       certificates  along  the  trail in order to verify group membership and
173       avoid masquerade and middleman attacks.
174
175       Secure groups can be configured as hierarchies where a TH of one  group
176       can  be a client of one or more other groups operating at a lower stra‐
177       tum. A certificate trail consist of a chain  of  hosts  starting  at  a
178       client,  leading through secondary servers of progressively lower stra‐
179       tum and ending at a TH. In one scenario, groups RED and  GREEN  can  be
180       cryptographically distinct, but both be clients of group BLUE operating
181       at a lower stratum. In another scenario, group CYAN can be a client  of
182       multiple  groups YELLOW and MAGENTA, both operating at a lower stratum.
183       There are many other scenarios, but all must be configured  to  include
184       only acyclic certificate trails.
185
186

IDENTITY SCHEMES AND CRYPTOTYPES

188       All  configurations include a public/private host key pair and matching
189       certificate. Absent an identity scheme, this is a  Trusted  Certificate
190       (TC) scheme. There are three identity schemes, IFF, GQ and MV described
191       on the Identity Schemes page. With these schemes  all  servers  in  the
192       group  have  encrypted  server identity keys, while clients have nonen‐
193       crypted client  identity  parameters.  The  client  parameters  can  be
194       obtained from a trusted agent (TA), usually one of the THs of the lower
195       stratum group. Further  information  on  identity  schemes  is  on  the
196       Autokey Identity Schemes page.
197
198       A specific combination of authentication and identity schemes is called
199       a cryptotype, which applies to clients and servers separately. A  group
200       can  be configured using more than one cryptotype combination, although
201       not all combinations are interoperable. Note however that some  crypto‐
202       type combinations may successfully intemperate with each other, but may
203       not represent good security practice. The server and client cryptotypes
204       are defined by the the following codes.
205
206
207       NONE    A client or server is type NONE if authentication is not avail‐
208               able or not configured. Packets exchanged  between  client  and
209               server have no MAC.
210
211       AUTH    A  client or server is type AUTH if the key option is specified
212               with the server configuration command and the client and server
213               keys  are  compatible.  Packets  exchanged  between clients and
214               servers have a MAC.
215
216       PC      A client or server is type PC if the autokey option  is  speci‐
217               fied  with the server configuration command and compatible host
218               key  and  private  certificate  files  are   present.   Packets
219               exchanged between clients and servers have a MAC.
220
221       TC      A  client  or server is type TC if the autokey option is speci‐
222               fied with the server configuration command and compatible  host
223               key and public certificate files are present. Packets exchanged
224               between clients and servers have a MAC.
225
226       IDENT   A client or server is type IDENT if the autokey option is spec‐
227               ified with the server configuration command and compatible host
228               key, public certificate and identity scheme files are  present.
229               Packets exchanged between clients and servers have a MAC.
230
231       The  compatible  cryptotypes  for clients and servers are listed in the
232       following table.
233
234
235       ┌──────────────────┬─────────┬──────────┬─────────┬──────────┬─────────┐
236       │ Client/Server    │  NONE   │  AUTH    │   PC    │   TC     │  IDENT  │
237       ├──────────────────┼─────────┼──────────┼─────────┼──────────┼─────────┤
238       │     NONE         │  yes    │  yes*    │  yes*   │  yes*    │  yes*   │
239       ├──────────────────┼─────────┼──────────┼─────────┼──────────┼─────────┤
240       │     AUTH         │   no    │  yes     │   no    │   no     │   no    │
241       ├──────────────────┼─────────┼──────────┼─────────┼──────────┼─────────┤
242       │      PC          │   no    │   no     │  yes    │   no     │   no    │
243       ├──────────────────┼─────────┼──────────┼─────────┼──────────┼─────────┤
244       │      TC          │   no    │   no     │   no    │  yes     │   yes   │
245       ├──────────────────┼─────────┼──────────┼─────────┼──────────┼─────────┤
246       │     IDENT        │   no    │   no     │   no    │   no     │   yes   │
247       └──────────────────┴─────────┴──────────┴─────────┴──────────┴─────────┘
248       * These combinations are not valid if the restriction list includes the
249       notrust option.
250
251

CONFIGURATION

253       Autokey  has  an  intimidating number of configuration options, most of
254       which are not necessary in typical  scenarios.  The  simplest  scenario
255       consists  of a TH where the host name of the TH is also the name of the
256       group. For the simplest identity scheme TC, the TH generates  host  key
257       and  trusted  certificate  files using the ntp-keygen -T command, while
258       the remaining group hosts use the same command with no options to  gen‐
259       erate  the  host  key  and  public certificate files. All hosts use the
260       crypto configuration command with no options. Configuration with  pass‐
261       words  is described in the ntp-keygen page. All group hosts are config‐
262       ured as an acyclic tree with root the TH.
263
264       When an identity scheme is included, for example IFF, the TH  generates
265       host  key,  trusted  certificate  and private server identity key files
266       using the ntp-keygen -T -I -i group command, where group is  the  group
267       name.  The  remaining  group  hosts  use the same command as above. All
268       hosts use the crypto ident group configuration command.
269
270       Hosts with no dependent clients can  retrieve  client  parameter  files
271       from an archive or web page. The ntp-keygen can export these data using
272       the -e option. Hosts with dependent clients  other  than  the  TH  must
273       retrieve  copies  of  the server key files using secure means. The ntp-
274       keygen can export these data using the -q option. In  either  case  the
275       data  are  installed as a file and then renamed using the name given as
276       the first line in the file, but without the filestamp.
277
278

EXAMPLES

280       Consider a scenario involving three secure groups RED, GREEN and  BLUE.
281       RED  and  BLUE are typical of national laboratories providing certified
282       time to the Internet at large. As shown ion the figure, RED TH mort and
283       BLUE  TH  macabre run NTP symmetric mode with each other for monitoring
284       or backup. For the purpose of illustration, assume both THs are primary
285       servers.  GREEN  is  typical  of a large university providing certified
286       time to the campus community. GREEN TH howland is a broadcast client of
287       both  RED  and BLUE. BLUE uses the IFF scheme, while both RED and GREEN
288       use the GQ scheme, but with different keys. YELLOW is a client of GREEN
289       and for purposes of illustration a TH for YELLOW.
290
291       The BLUE TH macabre uses configuration commands
292
293       crypto pw qqsv ident blue peer mort autokey broadcast address autokey
294
295       where  qqsv is the password for macabre files and address is the broad‐
296       cast address for the local LAN. It generates BLUE files using the  com‐
297       mands
298
299       ntp-keygen  -p  qqsv  -T  -G  -i  blue  ntp-keygen  -p  qqsv  -e  >ntp‐
300       key_gqpar_blue
301
302       The first line generates the host, trusted certificate and  private  GQ
303       server  keys file. The second generates the public GQ client parameters
304       file, which can have any nonconflicting mnemonic name.
305
306       The RED TH mort uses configuration commands
307
308       crypto pw xxx ident red peer macabre autokey broadcast address autokey
309
310       where xxx is the password for mort files. It generates RED files  using
311       the commands
312
313       ntp-keygen -p xxx -T -I -i red ntp-keygen -p xxx -e >ntpkey_iffpar_red
314
315        The GREEN TH howland uses configuration commands
316
317       crypto pw yyy ident green broadcastclient
318
319       where  yyy  is the password for howland files. It generates GREEN files
320       using the commands
321
322       ntp-keygen  -p  yyy  -T  -G  -i  green  ntp-keygen  -p  yyy  -e   >ntp‐
323       key_gqpar_green ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green
324
325       The  first  two lines serve the same purpose as the preceding examples.
326       The third line generates a copy of the private GREEN  server  file  for
327       use on another server in the same group, say YELLOW, but encrypted with
328       the zzz password.
329
330       A client of GREEN, for example YELLOW, uses the configuration commands
331
332       crypto pw abc ident green server howland autokey
333
334       where abc is the password for its files. It generates files  using  the
335       command
336
337       ntp-keygen -p abc
338
339       The  client  retrieves the client file for that group from a public ar‐
340       chive or web page using nonsecure means. In addition, each server in  a
341       group retrieves the private server keys file from the TH of that group,
342       but it is encrypted and so must be sent using secure means.  The  files
343       are installed in the keys directory with name taken from the first line
344       in the file, but without the filestamp.
345
346       Note that if servers of different groups, in this case  RED  and  BLUE,
347       share  the same broadcast media, each server must have client files for
348       all groups other than its own, while each client must have client files
349       for  all  groups. Note also that this scenario is for illustration only
350       and probably would not be wise for practical use, as if one of  the  TH
351       reference  clocks  fails, the certificate trail becomes cyclic. In such
352       cases the symmetric path between RED and  BLUE,  each  in  a  different
353       group, would not be a good idea.
354
355

AUTHENTICATION COMMANDS

357       automax [logsec]
358               Specifies the interval between regenerations of the session key
359               list used with the Autokey protocol, as a power of  2  in  sec‐
360               onds.  Note  that the size of the key list for each association
361               depends on this interval and the  current  poll  interval.  The
362               default  interval is 12 (about 1.1 h). For poll intervals above
363               the specified interval, a session key list with a single  entry
364               will be regenerated for every message sent.
365
366       controlkey keyid
367               Specifies  the  key ID to use with the ntpq utility, which uses
368               the standard protocol defined in RFC-1305. The  keyid  argument
369               is  the key ID for a trusted key, where the value can be in the
370               range 1 to 65534, inclusive.
371
372       crypto [randfile file] [host name] [ident name] [pw password]
373               This command requires the OpenSSL library. It activates  public
374               key  cryptography  and  loads  the required host key and public
375               certificate. If one or more files  are  left  unspecified,  the
376               default  names are used as described below. Unless the complete
377               path and name of the file are specified, the location of a file
378               is relative to the keys directory specified in the keysdir con‐
379               figuration command or default  /etc/ntp/crypto.  Following  are
380               the options.
381
382
383               digest MD2 | MD4 | MD5 | MDC2 | RIPEMD160 | SHA | SHA1
384                       Specify the message digest algorithm, with default MD5.
385                       If the OpenSSL library is installed, name can be be any
386                       message  digest  algorithm supported by the library not
387                       exceeding 160 bits in length. However, all Autokey par‐
388                       ticipants  in an Autokey subnet must use the same algo‐
389                       rithm. Note that the Autokey message  digest  algorithm
390                       is separate and distinct form the symmetric key message
391                       digest algorithms. Note: If compliance with FIPS  140-2
392                       is required, the algorithm must be ether SHA or SHA1.
393
394               host name
395                       Specifies  the  string used when constructing the names
396                       for the host, sign and certificate files  generated  by
397                       the ntp-keygen program with the -s name option.
398
399               ident name
400                       Specifies  the string used in constructing the identity
401                       files generated by the ntp-keygen program with  the  -i
402                       name option.
403
404               pw password
405                       Specifies  the  password  to  decrypt  files previously
406                       encrypted by the ntp-keygen program with the -p option.
407
408               randfile file
409                       Specifies the location of the random seed file used  by
410                       the  OpenSSL library. The defaults are described on the
411                       ntp-keygen page.
412
413
414       keys keyfile
415               Specifies the complete path to the MD5 key file containing  the
416               keys  and  key  IDs used by ntpd, ntpq and ntpdc when operating
417               with symmetric key cryptography. This is the same operation  as
418               the  -k  command  line option. Note that the directory path for
419               Autokey media is specified by the keysdir command.
420
421       keysdir pathK
422               This command specifies the default directory path  for  Autokey
423               cryptographic keys, parameters and certificates. The default is
424               /etc/ntp/crypto. Note that the path for the symmetric keys file
425               is specified by the keys command.
426
427       requestkey keyid
428               Specifies  the  key  ID  to use with the ntpdc utility program,
429               which uses a proprietary protocol specific to this  implementa‐
430               tion of ntpd. The keyid argument is a key ID for a trusted key,
431               in the range 1 to 65534, inclusive.
432
433       revoke [logsec]
434               Specifies the  interval  between  re-randomization  of  certain
435               cryptographic  values used by the Autokey scheme, as a power of
436               2 in seconds. These values need to  be  updated  frequently  in
437               order  to  deflect  brute-force attacks on the algorithms; how‐
438               ever, updating some values is a relatively expensive operation.
439               The  default  interval  is  17 (about 36 h). For poll intervals
440               above the specified interval, the values will  be  updated  for
441               every message sent.
442
443       trustedkey [keyid | (lowid ... highid)] [...]
444               Specifies  the  key ID(s) which are trusted for the purposes of
445               authenticating peers with symmetric key cryptography.  Key  IDs
446               used  to  authenticate ntpq and ntpdc operations must be listed
447               here  and  additionally  be  enabled  with  controlkey   and/or
448               requestkey.  The  authentication  procedure  for  time transfer
449               require that both the local and remote NTP servers  employ  the
450               same  key  ID  and  secret for this purpose, although different
451               keys IDs may be used with different servers. Ranges of  trusted
452               key  IDs may be specified: "trustedkey (1 ... 19) 1000 (100 ...
453               199)" enables the lowest 120 key IDs which start with the digit
454               1. The spaces surrounding the ellipsis are required when speci‐
455               fying a range.
456
457

ERROR CODES

459       Errors can occur due to mismatched configurations, unexpected  protocol
460       restarts, expired certificates and unfriendly people. In most cases the
461       protocol state machine recovers automatically by retransmission,  time‐
462       out  and  restart,  where  necessary. Some errors are due to mismatched
463       keys, digest schemes or identity  schemes  and  must  be  corrected  by
464       installing  the correct media and/or correcting the configuration file.
465       One of the most common errors is expired certificates,  which  must  be
466       regenerated  and  signed  at least once per year using the ntp-keygen -
467       generate public and private keys program.
468
469       The following error codes are reported via the NTP control and monitor‐
470       ing  protocol  trap mechanism and to the cryptostats monitoring file if
471       configured.
472
473
474       101 bad field format or length
475               The packet has invalid version, length or format.
476
477       102 bad timestamp
478               The packet timestamp is the same or older than the most  recent
479               received.  This could be due to a replay or a server clock time
480               step.
481
482       103 bad filestamp
483               The packet filestamp is the same or older than the most  recent
484               received.  This  could be due to a replay or a key file genera‐
485               tion error.
486
487       104 bad or missing public key
488               The public key is missing, has incorrect format or is an unsup‐
489               ported type.
490
491       105 unsupported digest type
492               The server requires an unsupported digest/signature scheme.
493
494       106 unsupported identity type
495               The client or server has requested an identity scheme the other
496               does not support.
497
498       107 bad signature length
499               The signature length does not match the current public key.
500
501       108 signature not verified
502               The message fails the signature check. It  could  be  bogus  or
503               signed by a different private key.
504
505       109 certificate not verified
506               The certificate is invalid or signed with the wrong key.
507
508       110 host certificate expired
509               The old server certificate has expired.
510
511       111 bad or missing cookie
512               The cookie is missing, corrupted or bogus.
513
514       112 bad or missing leapseconds table
515               The leapseconds table is missing, corrupted or bogus.
516
517       113 bad or missing certificate
518               The certificate is missing, corrupted or bogus.
519
520       114 bad or missing group key
521               The identity key is missing, corrupt or bogus.
522
523       115 protocol error
524               The  protocol  state  machine  has  wedged  due  to  unexpected
525               restart.
526
527

FILES

529       See the ntp-keygen page. Note that provisions to load leap second  val‐
530       ues  from  the  NIST  files have been removed. These provisions are now
531       available whether or not the OpenSSL library is available. However, the
532       functions  that  can  download these values from servers remains avail‐
533       able.
534
535

SEE ALSO

537       ntp.conf(5), ntpd(8)
538
539       The official HTML documentation.
540
541       This file was automatically generated from HTML source.
542
543
544
545
546                                                                   ntp_auth(5)
Impressum