1ntp_auth(5) File Formats Manual ntp_auth(5)
2
6 ntp_auth - Authentication Options
7
10 Authentication support allows the NTP client to verify that the server
11 is in fact known and trusted and not an intruder intending accidentally
12 or on purpose to masquerade as that server. The NTPv3 specification
13 RFC-1305 defines a scheme which provides cryptographic authentication
14 of received NTP packets. Originally, this was done using the Data
15 Encryption Standard (DES) algorithm operating in Cipher Block Chaining
16 (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by
17 the RSA Message Digest 5 (MD5) algorithm using a private key, commonly
18 called keyed-MD5. Either algorithm computes a message digest, or one-
19 way hash, which can be used to verify the server has the correct pri‐
20 vate key and key identifier.
21 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
23 cryptography, and, in addition, provides a new Autokey scheme based on
24 public key cryptography. Public key cryptography is generally consid‐
25 ered more secure than symmetric key cryptography, since the security is
26 based on a private value which is generated by each host and never
27 revealed. With the exception of the group key described later, all key
28 distribution and management functions involve only public values, which
29 considerably simplifies key distribution and storage. Public key man‐
30 agement is based on X.509 certificates, which can be provided by com‐
31 mercial services or produced by utility programs in the OpenSSL soft‐
32 ware library or the NTPv4 distribution.
33 While the algorithms for symmetric key cryptography are included in the
35 NTPv4 distribution, public key cryptography requires the OpenSSL soft‐
36 ware library to be installed before building the NTP distribution. This
37 library is available from http://www.openssl.org and can be installed
38 using the procedures outlined in the Building and Installing the Dis‐
39 tribution page. Once installed, the configure and build process auto‐
40 matically detects the library and links the library routines required.
41 Authentication is configured separately for each association using the
43 key or autokey subcommand on the peer, server, broadcast and manycast‐
44 client configuration commands as described in the Configuration Options
45 page. The authentication options described below specify the locations
46 of the key files, if other than default, which symmetric keys are
47 trusted and the interval between various operations, if other than
48 default.
49 Authentication is always enabled, although ineffective if not config‐
51 ured as described below. If a NTP packet arrives including a message
52 authentication code (MAC), it is accepted only if it passes all crypto‐
53 graphic checks. The checks require correct key ID, key value and mes‐
54 sage digest. If the packet has been modified in any way or replayed by
55 an intruder, it will fail one or more of these checks and be discarded.
56 Furthermore, the Autokey scheme requires a preliminary protocol
57 exchange to obtain the server certificate, verify its credentials and
58 initialize the protocol
59 The auth flag controls whether new associations or remote configuration
61 commands require cryptographic authentication. This flag can be set or
62 reset by the enable and disable commands and also by remote configura‐
63 tion commands sent by a ntpdc program running on another machine. If
64 this flag is enabled, which is the default case, new broadcast/manycast
65 client and symmetric passive associations and remote configuration com‐
66 mands must be cryptographically authenticated using either symmetric
67 key or public key cryptography. If this flag is disabled, these opera‐
68 tions are effective even if not cryptographic authenticated. It should
69 be understood that operating with the auth flag disabled invites a sig‐
70 nificant vulnerability where a rogue hacker can masquerade as a
71 truechimer and seriously disrupt system timekeeping. It is important to
72 note that this flag has no purpose other than to allow or disallow a
73 new association in response to new broadcast and symmetric active mes‐
74 sages and remote configuration commands and, in particular, the flag
75 has no effect on the authentication process itself.
76 The security model and protocol schemes for both symmetric key and pub‐
78 lic key cryptography are summarized below; further details are in the
79 briefings, papers and reports at the NTP project page linked from
80 www.ntp.org.
81
84 The original RFC-1305 specification allows any one of possibly 65,534
85 keys, each distinguished by a 32-bit key identifier, to authenticate an
86 association. The servers and clients involved must agree on the key and
87 key identifier to authenticate NTP packets. Keys and related informa‐
88 tion are specified in a key file, usually called ntp.keys, which must
89 be distributed and stored using secure means beyond the scope of the
90 NTP protocol itself. Besides the keys used for ordinary NTP associa‐
91 tions, additional keys can be used as passwords for the ntpq and ntpdc
92 utility programs. Ordinarily, the ntp.keys file is generated by the
93 ntp-keygen program. When ntpd is first started, it reads the key file
94 specified in the keys configuration command and installs the keys in
95 the key cache. However, individual keys must be activated with the
96 trustedkey command before use. This allows, for instance, the installa‐
97 tion of possibly several batches of keys and then activating or deacti‐
98 vating each batch remotely using ntpdc. This also provides a revocation
99 capability that can be used if a key becomes compromised. The
100 requestkey command selects the key used as the password for the ntpdc
101 utility, while the controlkey command selects the key used as the pass‐
102 word for the ntpq utility.
103
106 NTPv4 supports the original NTPv3 symmetric key scheme described in
107 RFC-1305 and in addition the Autokey protocol, which is based on public
108 key cryptography. The Autokey Version 2 protocol described on the
109 Autokey Protocol page verifies packet integrity using MD5 message
110 digests and verifies the source with digital signatures and any of sev‐
111 eral digest/signature schemes. Optional identity schemes described on
112 the Identity Schemes page and based on cryptographic challenge/response
113 algorithms are also available. Using these schemes provides strong
114 security against replay with or without modification, spoofing, mas‐
115 querade and most forms of clogging attacks.
116 The Autokey protocol has several modes of operation corresponding to
118 the various NTP modes supported. Most modes use a special cookie which
119 can be computed independently by the client and server, but encrypted
120 in transmission. All modes use in addition a variant of the S-KEY
121 scheme, in which a pseudo-random key list is generated and used in
122 reverse order. These schemes are described along with an executive sum‐
123 mary, current status, briefing slides and reading list on the Autono‐
124 mous Authentication page.
125 The specific cryptographic environment used by Autokey servers and
127 clients is determined by a set of files and soft links generated by the
128 ntp-keygen program. This includes a required host key file, required
129 host certificate file and optional sign key file, leapsecond file and
130 identity scheme files. The digest/signature scheme is specified in the
131 X.509 certificate along with the matching sign key. There are several
132 schemes available in the OpenSSL software library, each identified by a
133 specific string such as md5WithRSAEncryption, which stands for the MD5
134 message digest with RSA encryption scheme. The current NTP distribution
135 supports all the schemes in the OpenSSL library, including those based
136 on RSA and DSA digital signatures.
137 NTP secure groups can be used to define cryptographic compartments and
139 security hierarchies. It is important that every host in the group be
140 able to construct a certificate trail to one or more trusted hosts in
141 the same group. Each group host runs the Autokey protocol to obtain the
142 certificates for all hosts along the trail to one or more trusted
143 hosts. This requires the configuration file in all hosts to be engi‐
144 neered so that, even under anticipated failure conditions, the NTP sub‐
145 net will form such that every group host can find a trail to at least
146 one trusted host.
147
150 It is important to note that Autokey does not use DNS to resolve
151 addresses, since DNS can't be completely trusted until the name servers
152 have synchronized clocks. The cryptographic name used by Autokey to
153 bind the host identity credentials and cryptographic values must be
154 independent of interface, network and any other naming convention. The
155 name appears in the host certificate in either or both the subject and
156 issuer fields, so protection against DNS compromise is essential.
157 By convention, the name of an Autokey host is the name returned by the
159 Unix gethostname() system call or equivalent in other systems. By the
160 system design model, there are no provisions to allow alternate names
161 or aliases. However, this is not to say that DNS aliases, different
162 names for each interface, etc., are constrained in any way.
163 It is also important to note that Autokey verifies authenticity using
165 the host name, network address and public keys, all of which are bound
166 together by the protocol specifically to deflect masquerade attacks.
167 For this reason Autokey includes the source and destinatino IP
168 addresses in message digest computations and so the same addresses must
169 be available at both the server and client. For this reason operation
170 with network address translation schemes is not possible. This reflects
171 the intended robust security model where government and corporate NTP
172 servers are operated outside firewall perimeters.
173
176 Autokey has an intimidating number of options, most of which are not
177 necessary in typical scenarios. The simplest configuration consists of
178 a subnet with one or more servers at the same low stratum acting as
179 trusted hosts and with dependent clients at higher strata and sharing a
180 single secure group and identity scheme. Each trusted host generates a
181 host key, trusted certificate and group key. Each client generates a
182 host key, normal certificate and installs the group key of each trusted
183 host using secure means and renames it as the name of the trusted host.
184 For example, trusted host Alice generates keys using
186 ntp-keygen -H -T -I -p xyz
188 where H specifies a new host key, T the trusted certificate, I the IFF
190 identity scheme and p the password used to encrypt the private key
191 files. The group key file is ntpkey_IFFpar_alice.filestamp, where
192 filestamp represents the NTP time in seconds when the file was gener‐
193 ated.
194 Host Bob generate keys using
196 ntp-keygen -H -p abc
198 where abc is different for each group host. The trusted host generates
200 a password-protected group key using
201 ntp-keygen -q xyz -p abc -e >temp
203 where xyz is the trusted host password, abc is the password supplied by
205 the client and temp is a temporary file. This file is transmitted to
206 Bob using secure means and renamed to the fully qualified host name for
207 Alice preceded by the string ntpkey_iff_.
208
211 A specific combination of authentication scheme (none, symmetric key,
212 public key) and identity scheme is called a cryptotype, although not
213 all combinations are compatible. There may be management configurations
214 where the clients, servers and peers may not all support the same cryp‐
215 totypes. A secure NTPv4 subnet can be configured in many ways while
216 keeping in mind the principles explained above and in this section.
217 Note however that some cryptotype combinations may successfully inter‐
218 operate with each other, but may not represent good security practice.
219 The cryptotype of an association is determined at the time of mobiliza‐
221 tion, either at configuration time or some time later when a message of
222 appropriate cryptotype arrives. When mobilized by a server or peer con‐
223 figuration command and no key or autokey subcommands are present, the
224 association is not authenticated; if the key subcommand is present, the
225 association is authenticated using the symmetric key ID specified; if
226 the autokey subcommand is present, the association is authenticated
227 using Autokey.
228
231 The cryptographic values used by the Autokey protocol are incorporated
232 as a set of files generated by the ntp-keygen utility program, includ‐
233 ing symmetric key, host key and public certificate files, as well as
234 sign key, identity parameters and leapseconds files. Alternatively,
235 host and sign keys and certificate files can be generated by the
236 OpenSSL utilities and certificates can be imported from public certifi‐
237 cate authorities. Note that symmetric keys are necessary for the ntpq
238 and ntpdc utility programs. The remaining files are necessary only for
239 the Autokey protocol.
240 Certificates imported from OpenSSL or public certificate authorities
242 have certian limitations. The certificate should be in ASN.1 syntax,
243 X.509 Version 3 format and encoded in PEM, which is the same format
244 used by OpenSSL. The overall length of the certificate encoded in ASN.1
245 must not exceed 1024 bytes. The subject distinguished name field (CN)
246 is the fully qualified name of the host on which it is used; the
247 remaining subject fields are ignored. The certificate extension fields
248 must not contain either a subject key identifier or a issuer key iden‐
249 tifier field; however, an extended key usage field for a trusted host
250 must contain the value trustRoot;. Other extension fields are ignored.
251
254 autokey [logsec]
255 Specifies the interval between regenerations of the session key
256 list used with the Autokey protocol. Note that the size of the
257 key list for each association depends on this interval and the
258 current poll interval. The default value is 12 (4096 s or about
259 1.1 hours). For poll intervals above the specified interval, a
260 session key list with a single entry will be regenerated for
261 every message sent.
262 controlkey key
264 Specifies the key identifier to use with the ntpq utility,
265 which uses the standard protocol defined in RFC-1305. The key
266 argument is the key identifier for a trusted key, where the
267 value can be in the range 1 to 65,534, inclusive.
268 crypto [cert file] [leap file] [randfile file] [host file] [sign file]
270 [ident scheme] [iffpar file] [gqpar file] [mvpar file] [pw password]
271 This command requires the OpenSSL library. It activates public
272 key cryptography, selects the message digest and signature
273 encryption scheme and loads the required private and public
274 values described above. If one or more files are left unspeci‐
275 fied, the default names are used as described above. Unless the
276 complete path and name of the file are specified, the location
277 of a file is relative to the keys directory specified in the
278 keysdir command or default /usr/local/etc. Following are the
279 subcommands:
280 cert file
282 Specifies the location of the required host public cer‐
283 tificate file. This overrides the link ntp‐
284 key_cert_hostname in the keys directory.
285 gqpar file
287 Specifies the location of the client GQ parameters
288 file. This overrides the link ntpkey_gq_hostname in the
289 keys directory.
290 host file
292 Specifies the location of the required host key file.
293 This overrides the link ntpkey_key_hostname in the keys
294 directory.
295 ident scheme
297 Requests the server identity scheme, which can be IFF,
298 GQ or MV. This is used when the host will not be a
299 server for a dependent client.
300 iffpar file
302 Specifies the location of the optional IFF parameters
303 file.This overrides the link ntpkey_iff_hostname in the
304 keys directory.
305 leap file
307 Specifies the location of the client leapsecond file.
308 This overrides the link ntpkey_leap in the keys direc‐
309 tory.
310 mv Requests the MV server identity scheme.
312 mvpar file
314 Specifies the location of the client MV parameters
315 file. This overrides the link ntpkey_mv_hostname in the
316 keys directory.
317 pw password
319 Specifies the password to decrypt files containing pri‐
320 vate keys and identity parameters. This is required
321 only if these files have been encrypted.
322 randfile file
324 Specifies the location of the random seed file used by
325 the OpenSSL library. The defaults are described in the
326 main text above.
327 sign file
329 Specifies the location of the optional sign key file.
330 This overrides the link ntpkey_sign_hostname in the
331 keys directory. If this file is not found, the host key
332 is also the sign key.
333 keys keyfile
336 Specifies the complete path and location of the MD5 key file
337 containing the keys and key identifiers used by ntpd, ntpq and
338 ntpdc when operating with symmetric key cryptography. This is
339 the same operation as the -k command line option.
340 keysdir path
342 This command specifies the default directory path for crypto‐
343 graphic keys, parameters and certificates. The default is
344 /usr/local/etc/.
345 requestkey key
347 Specifies the key identifier to use with the ntpdc utility pro‐
348 gram, which uses a proprietary protocol specific to this imple‐
349 mentation of ntpd. The key argument is a key identifier for the
350 trusted key, where the value can be in the range 1 to 65,534,
351 inclusive.
352 revoke [logsec]
354 Specifies the interval between re-randomization of certain
355 cryptographic values used by the Autokey scheme, as a power of
356 2 in seconds. These values need to be updated frequently in
357 order to deflect brute-force attacks on the algorithms of the
358 scheme; however, updating some values is a relatively expensive
359 operation. The default interval is 16 (65,536 s or about 18
360 hours). For poll intervals above the specified interval, the
361 values will be updated for every message sent.
362 trustedkey key [...]
364 Specifies the key identifiers which are trusted for the pur‐
365 poses of authenticating peers with symmetric key cryptography,
366 as well as keys used by the ntpq and ntpdc programs. The
367 authentication procedures require that both the local and
368 remote servers share the same key and key identifier for this
369 purpose, although different keys can be used with different
370 servers. The key arguments are 32-bit unsigned integers with
371 values from 1 to 65,534.
372
375 Errors can occur due to mismatched configurations, unexpected restarts,
376 expired certificates and unfriendly people. In most cases the protocol
377 state machine recovers automatically by retransmission, timeout and
378 restart, where necessary. Some errors are due to mismatched keys,
379 digest schemes or identity schemes and must be corrected by installing
380 the correct media and/or correcting the configuration file. One of the
381 most common errors is expired certificates, which must be regenerated
382 and signed at least once per year using the ntp-keygen program.
383 The following error codes are reported via the NTP control and monitor‐
385 ing protocol trap mechanism.
386 101 (bad field format or length)
389 The packet has invalid version, length or format.
390 102 (bad timestamp)
392 The packet timestamp is the same or older than the most recent
393 received. This could be due to a replay or a server clock time
394 step.
395 103 (bad filestamp)
397 The packet filestamp is the same or older than the most recent
398 received. This could be due to a replay or a key file genera‐
399 tion error.
400 104 (bad or missing public key)
402 The public key is missing, has incorrect format or is an unsup‐
403 ported type.
404 105 (unsupported digest type)
406 The server requires an unsupported digest/signature scheme.
407 106 (unsupported identity type)
409 The client or server has requested an identity scheme the other
410 does not support.
411 107 (bad signature length)
413 The signature length does not match the current public key.
414 108 (signature not verified)
416 The message fails the signature check. It could be bogus or
417 signed by a different private key.
418 109 (certificate not verified)
420 The certificate is invalid or signed with the wrong key.
421 110 (host certificate expired)
423 The old server certificate has expired.
424 111 (bad or missing cookie)
426 The cookie is missing, corrupted or bogus.
427 112 (bad or missing leapseconds table)
429 The leapseconds table is missing, corrupted or bogus.
430 113 (bad or missing certificate)
432 The certificate is missing, corrupted or bogus.
433 114 (bad or missing group key)
435 The identity key is missing, corrupt or bogus.
436 115 (protocol error)
438 The protocol state machine has wedged due to unexpected restart
439 116 (server certificate expired)
441 The old server certificate has expired.
442
445 See the ntp-keygen page.
446
449 The NIST provides a file documenting the epoch for all historic occa‐
450 sions of leap second insertion since 1972. The leapsecond table shows
451 each epoch of insertion along with the offset of International Atomic
452 Time (TAI) with respect to Coordinated Universal Time (UTC), as dissem‐
453 inated by NTP. The table can be obtained directly from NIST national
454 time servers using ftp as the ASCII file pub/leap-seconds.
455 While not strictly a security function, the Autokey protocol provides
457 means to securely retrieve the leapsecond table from a server or peer.
458 Servers load the leapsecond table directly from the file specified in
459 the crypto command, with default ntpkey_leap, while clients can obtain
460 the table indirectly from the servers using the Autokey protocol. Once
461 loaded, the table can be provided on request to other clients and
462 servers.
463
466 ntp.conf(5), ntpd(8)
467 Primary source of documentation: /usr/share/doc/ntp-*
469 This file was automatically generated from HTML source.
471 ntp_auth(5)