1ntp_auth(5) File Formats Manual ntp_auth(5)
2
6 ntp_auth - Authentication Options
7
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 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 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 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 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 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
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 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 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 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 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
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 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 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
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 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 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 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
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 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 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 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 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 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 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 The compatible cryptotypes for clients and servers are listed in the
232 following table.
233 ┌──────────────────┬─────────┬──────────┬─────────┬──────────┬─────────┐
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
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 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 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
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 The BLUE TH macabre uses configuration commands
292 crypto pw qqsv ident blue peer mort autokey broadcast address autokey
294 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 ntp-keygen -p qqsv -T -G -i blue ntp-keygen -p qqsv -e >ntp‐
300 key_gqpar_blue
301 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 The RED TH mort uses configuration commands
307 crypto pw xxx ident red peer macabre autokey broadcast address autokey
309 where xxx is the password for mort files. It generates RED files using
311 the commands
312 ntp-keygen -p xxx -T -I -i red ntp-keygen -p xxx -e >ntpkey_iffpar_red
314 The GREEN TH howland uses configuration commands
316 crypto pw yyy ident green broadcastclient
318 where yyy is the password for howland files. It generates GREEN files
320 using the commands
321 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 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 A client of GREEN, for example YELLOW, uses the configuration commands
331 crypto pw abc ident green server howland autokey
333 where abc is the password for its files. It generates files using the
335 command
336 ntp-keygen -p abc
338 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 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
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 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 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 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 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 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 pw password
405 Specifies the password to decrypt files previously
406 encrypted by the ntp-keygen program with the -p option.
407 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 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 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 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 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 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
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 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 101 bad field format or length
475 The packet has invalid version, length or format.
476 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 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 104 bad or missing public key
488 The public key is missing, has incorrect format or is an unsup‐
489 ported type.
490 105 unsupported digest type
492 The server requires an unsupported digest/signature scheme.
493 106 unsupported identity type
495 The client or server has requested an identity scheme the other
496 does not support.
497 107 bad signature length
499 The signature length does not match the current public key.
500 108 signature not verified
502 The message fails the signature check. It could be bogus or
503 signed by a different private key.
504 109 certificate not verified
506 The certificate is invalid or signed with the wrong key.
507 110 host certificate expired
509 The old server certificate has expired.
510 111 bad or missing cookie
512 The cookie is missing, corrupted or bogus.
513 112 bad or missing leapseconds table
515 The leapseconds table is missing, corrupted or bogus.
516 113 bad or missing certificate
518 The certificate is missing, corrupted or bogus.
519 114 bad or missing group key
521 The identity key is missing, corrupt or bogus.
522 115 protocol error
524 The protocol state machine has wedged due to unexpected
525 restart.
526
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
537 ntp.conf(5), ntpd(8)
538 HTML documentation in ntp-doc package.
540 This file was automatically generated from HTML source.
542 ntp_auth(5)