1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 3<html> 4 5<head> 6<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> 7<meta name="generator" content="HTML Tidy, see www.w3.org"> 8<title>Authentication Options</title> 9<link href="scripts/style.css" type="text/css" rel="stylesheet"> 10<style type="text/css"> 11<!-- 12.style1 { color: #FF0000; 13 font-weight: bold; 14} 15--> 16</style> 17</head> 18 19<body> 20<h3>Authentication Options</h3> 21<img src="pic/alice44.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> 22 23<p>Our resident cryptographer; now you see him, now you don't.</p> 24 25<p>Last update: 26 <!-- #BeginDate format:En2m -->13-Nov-2009 0:37<!-- #EndDate --> 27UTC</p> 28<br clear="left"> 29 30<h4>Related Links</h4> 31 32<script type="text/javascript" language="javascript" src="scripts/command.txt"></script> 33<script type="text/javascript" language="javascript" src="scripts/authopt.txt"></script> 34 35<h4>Table of Contents</h4> 36 37<ul> 38<li class="inline"><a href="#auth">Introduction</a></li> 39<li class="inline"><a href="#symm">Symmetric Key Cryptography</a></li> 40<li class="inline"><a href="#pub">Public Key Cryptography</a></li> 41<li class="inline"><a href="#group">NTP Secure Groups</a></li> 42<li class="inline"><a href="#ident">Identity Schemes and Cryptotypes</a></li> 43<li class="inline"><a href="#cfg">Configuration</a></li> 44<li class="inline"><a href="#exam">Examples</a></li> 45<li class="inline"><a href="#cmd">Authentication Commands</a></li> 46<li class="inline"><a href="#err">Error Codes</a></li> 47<li class="inline"><a href="#file">Files</a></li> 48</ul> 49 50<hr> 51 52<h4 id="auth">Introduction</h4> 53 54<p>This page describes the various cryptographic authentication provisions in 55 NTPv4. Details about the configuration commands and options are given on 56 the <a href="confopt.html">Configuration 57 Options</a> page. Details about the automatic server discovery schemes are described 58 on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page. Additional 59 information is available in the papers, reports, memoranda and briefings 60 cited on the <a href="http://www.eecis.udel.edu/~mills/ntp.html"> NTP Project</a> page. 61 Authentication support allows the NTP client to verify that servers are in 62 fact known and trusted and not intruders intending accidentally or intentionally 63 to masquerade as a legitimate server.</p> 64 65<p> The NTPv3 specification RFC-1305 defines a scheme properly described as 66 symmetric key cryptography. It uses the Data Encryption Standard (DES) 67 algorithm operating in cipher-block chaining (CBC) mode. Subsequently, this 68 scheme was replaced by the RSA Message Digest 5 (MD5) algorithm commonly 69 called keyed-MD5. Either algorithm computes a message digest or one-way hash 70 which can be used to verify the client has the same key and key identifier 71 as the server. If the OpenSSL cryptographic library is installed, support 72 is available for all algorithms included in the library. Note however, if 73 conformance to FIPS 140-2 is required, only a limited subset of these algorithms 74 is available.</p> 75 76<p>NTPv4 includes the NTPv3 scheme 77 and optionally a new scheme based on public key cryptography and called 78 Autokey. Public key cryptography is generally considered more secure than 79 symmetric key cryptography, since the security is based on private and public 80 values which are generated by each participant and where the private value 81 is never revealed. Autokey uses X.509 public certificates, which can be produced 82 by commercial services, utility programs in the OpenSSL software library 83 or the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility 84 program in the NTP software distribution.</p> 85 86<p>While the algorithms for MD5 symmetric key cryptography are included in the 87 NTPv4 software distribution, modern algorithms for symmetric key and public 88 key cryptograpny requires the OpenSSL software library 89 to be installed before building the NTP distribution. This library is available 90 from <a href="http://www.openssl.org">http://www.openssl.org</a> and 91 can be installed using the procedures outlined in the <a href="build.html">Building 92 and Installing the Distribution</a> page. Once installed, the configure and 93 build process automatically detects the library and links the library routines 94 required.</p> 95 96<p>Note that according to US law, NTP binaries including OpenSSL library components, 97 including the OpenSSL library itself, cannot be exported outside the 98 US without license from the US Department of Commerce. Builders outside the 99 US are advised to obtain the OpenSSL library directly from OpenSSL, which 100 is outside the US, and build outside the US.</p> 101 102<p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> option of the <tt>server</tt> configuration command, as described in the <a href="confopt.html">Server Options</a> page, and the options described on this page. The <a href="keygen.html">ntp-keygen</a> page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from <a href="http://www.ntp.org">www.ntp.org</a>.</p> 103 104<h4 id="symm">Symmetric Key Cryptography</h4> 105 106<p>The original RFC-1305 specification allows any one of possibly 65,534 keys 107 (excluding zero), each distinguished by a 32-bit key ID, to authenticate 108 an association. The servers and clients involved must agree on the key, key 109 ID and key type to authenticate NTP packets. If an NTP packet includes a 110 message authentication code (MAC), consisting of a key ID and message digest, 111 it is accepted only if the key ID matches a trusted key and the message digest 112 is verified with this key. Note that for historic reasons the message digest 113 algorithm is not consistent with RFC-1828. The digest is computed directly 114 from the concatenation of the key string followed by the packet contents 115 with the exception of the MAC itself.</p> 116 117<p>Keys and related information are specified in a keys file, usually called <tt>ntp.keys</tt>, 118 which must be distributed and stored using secure means beyond the scope 119 of the NTP protocol itself. Besides the keys used for ordinary NTP associations, 120 additional keys can be used as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility 121 programs. Ordinarily, the <tt>ntp.keys</tt> file is generated by the <tt><a href="keygen.html">ntp-keygen</a></tt> program, 122 but it can be constructed and edited using an ordinary text editor. The 123 program generates pseudo-random keys, one key for each line. Each line consists 124 of three fields, the key identifier as a decimal number from 1 to 65534 inclusive, 125 a key type chosen from the keywords of the <tt>digest</tt> option of the <tt>crypto</tt> command, 126 and a 20-character printable ASCII string or a 40-character hex string as 127 the key itself.</p> 128 129<p>When <tt>ntpd</tt> is first started, it reads the key file specified by the <tt>keys</tt> command and installs the keys in the key cache. However, individual keys must be activated with the <tt>trustedkey</tt> configuration command before use. This allows, for instance, the installation of possibly several batches of keys and then activating a key remotely using <tt>ntpdc</tt>. The <tt>requestkey</tt> command selects the key ID used as the password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt> command selects the key ID used as the password for the <tt>ntpq</tt> utility.</p> 130<p>By default, the message digest algorithm is MD5 selected by the key type 131 <tt>M</tt> in the keys file. However, if the OpenSSL library is installed, 132 any message digest algorithm supported by that library can be used. The key 133 type is selected as the algorithm name given in the OpenSSL documentation. 134 The key type is associated with the key and can be different for different 135 keys. The server and client 136 must share the same key, key ID and key type and both must be trusted. Note 137 that if conformance to FIPS 140-2 is required, the message digest algorithm 138 must conform to the Secure Hash Standard (SHS), which requires an algorithm 139 from the Secure Hash Algorithm (SHA) family, and the digital signature encryption 140 algorithm, if used, must conform to the Digital Signature Standard (DSS), 141 which requires the Digital Signature Algorithm (DSA).</p> 142<p>In addition to the above means, <tt>ntpd</tt> now supports 143 Microsoft Windows MS-SNTP authentication using Active Directory services. 144 This support was contributed by the Samba Team and is still in development. 145 It is enabled using the <tt>mssntp</tt> flag 146 of the <tt>restrict</tt> command described on 147 the <a href="authopt.html">Access Control Options</a> page. <span class="style1">Note: 148 Potential users should be aware that these services involve a TCP connection 149 to another process that could potentially block, denying services to other 150 users. Therefore, this flag should be used only for a dedicated server with 151 no clients other than MS-SNTP.</span></p> 152<h4 id="pub">Public Key Cryptography</h4> 153 154<p>NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/~mills/autokey.html">Autonomous Authentication</a> page.</p> 155 156<p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p> 157 158<p>There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 h, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.</p> 159 160<h4 id="group">NTP Secure Groups</h4> 161 162<p>NTP secure groups are used to define cryptographic compartments and security 163 hierarchies. All hosts belonging to a secure group have the same group name 164 but different host names. The string specified in the <tt>host</tt> option of 165 the <tt>crypto</tt> command is the name of the host and the name used in the 166 host key, sign key and certificate files. The string specified in the <tt>ident</tt> option 167 of the <tt>crypto</tt> command is the group name of all group hosts and the 168 name used in the identity files. The file naming conventions are described on 169 the <a href="keygen.html">ntp-keygen</a> page.</p> 170 171<p>Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH self-signed trusted certificate for these hosts. The host name is used in the subject and issuer fields of the self-signed certificates for all other hosts.</p> 172 173<p>All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts and ending at a TH. When a host starts up, it recursively retrieves the certificates along the trail in order to verify group membership and avoid masquerade and middleman attacks.</p> 174 175<p>Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. A certificate trail consist of a chain of hosts starting at a client, leading through secondary servers of progressively lower stratum and ending at a TH. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.</p> 176 177<h4 id="ident">Identity Schemes and Cryptotypes</h4> 178 179<p>All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page.</p> 180 181<p>A specific combination of authentication and identity schemes is called a 182 cryptotype, which applies to clients and servers separately. A group can be 183 configured using more than one cryptotype combination, although not all combinations 184 are interoperable. Note however that some cryptotype combinations may successfully 185 intemperate with each other, but may not represent good security practice. The 186 server and client cryptotypes are defined by the the following codes.</p> 187 188<dl> 189<dt>NONE</dt> 190<dd>A client or server is type NONE if authentication is not available or not configured. Packets exchanged between client and server have no MAC.</dd> 191 192<dt>AUTH</dt> 193<dd>A client or server is type AUTH if the <tt>key</tt> option is specified with the <tt>server</tt> configuration command and the client and server keys are compatible. Packets exchanged between clients and servers have a MAC.</dd> 194 195<dt>PC</dt> 196<dd>A client or server is type PC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and private certificate files are present. Packets exchanged between clients and servers have a MAC.</dd> 197 198<dt>TC</dt> 199<dd>A client or server is type TC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and public certificate files are present. Packets exchanged between clients and servers have a MAC.</dd> 200 201<dt>IDENT</dt> 202 <dd>A client or server is type IDENT if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key, public certificate and identity scheme files are present. Packets exchanged between clients and servers have a MAC.</dd> 203 204</dl> 205 206<p>The compatible cryptotypes for clients and servers are listed in the following table.</p> 207 208<table width="100%" border="1" cellpadding="4"> 209 210<tr> 211<td rowspan="2" align="center">Client</td> 212<td colspan="5" align="center">Server</td> 213</tr> 214 215<tr> 216<td align="center">NONE</td> 217<td align="center">AUTH</td> 218<td align="center">PC</td> 219<td align="center">TC</td> 220<td align="center">IDENT</td> 221</tr> 222 223<tr> 224<td align="center">NONE</td> 225<td align="center">yes</td> 226<td align="center">yes*</td> 227<td align="center">yes*</td> 228<td align="center">yes*</td> 229<td align="center">yes*</td> 230</tr> 231 232<tr> 233<td align="center">AUTH</td> 234<td align="center">no</td> 235<td align="center">yes</td> 236<td align="center">no</td> 237<td align="center">no</td> 238<td align="center">no</td> 239</tr> 240 241<tr> 242<td align="center">PC</td> 243<td align="center">no</td> 244<td align="center">no</td> 245<td align="center">yes</td> 246<td align="center">no</td> 247<td align="center">no</td> 248</tr> 249 250<tr> 251<td align="center">TC</td> 252<td align="center">no</td> 253<td align="center">no</td> 254<td align="center">no</td> 255<td align="center">yes</td> 256<td align="center">yes</td> 257</tr> 258 259<tr> 260<td align="center">IDENT</td> 261<td align="center">no</td> 262<td align="center">no</td> 263<td align="center">no</td> 264<td align="center">no</td> 265<td align="center">yes</td> 266</tr> 267 268</table> 269 270<p>* These combinations are not valid if the restriction list includes the <tt>notrust</tt> option.</p> 271 272<h4 id="cfg">Configuration</h4> 273 274<p>Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of a TH where the host name of the TH is also the name of the group. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the <tt>ntp-keygen -T</tt> command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the <tt>crypto</tt> configuration command with no options. Configuration with passwords is described in the <a href="keygen.html">ntp-keygen</a> page. All group hosts are configured as an acyclic tree with root the TH.</p> 275 276<p>When an identity scheme is included, for example IFF, the TH generates host 277 key, trusted certificate and private server identity key files using the <tt>ntp-keygen 278 -T -I -i <i>group</i></tt> command, where <tt><i>group</i></tt> is the group 279 name. The remaining group hosts use the same command as above. All hosts 280 use the <tt>crypto ident group<i></i></tt> configuration command.</p> 281 282<p>Hosts with no dependent clients can retrieve client parameter files from an 283 archive or web page. The <tt>ntp-keygen</tt> can export these data using the <tt>-e</tt> option. 284 Hosts with dependent clients other than the TH must retrieve copies of the server 285 key files using secure means. The <tt>ntp-keygen</tt> can export these data 286 using the <tt>-q</tt> option. In either case the data are installed as a file 287 and then renamed using the name given as the first line in the file, but without 288 the filestamp.</p> 289 290<h4 id="exam">Examples</h4> 291 292<div align="center"> 293<img src="pic/group.gif" alt="gif"> 294</div> 295 296<p>Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. As shown ion the figure, RED TH mort and BLUE TH macabre run NTP symmetric mode with each other for monitoring or backup. For the purpose of illustration, assume both THs are primary servers. GREEN is typical of a large university providing certified time to the campus community. GREEN TH howland is a broadcast client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys. YELLOW is a client of GREEN and for purposes of illustration a TH for YELLOW.</p> 297 298<p>The BLUE TH macabre uses configuration commands</p> 299 300<p><tt>crypto pw qqsv ident blue</tt><br> 301<tt>peer mort autokey</tt><br> 302<tt>broadcast <i>address</i> autokey</tt></p> 303 304<p>where <tt>qqsv</tt> is the password for macabre files and <i>address</i> is the broadcast address for the local LAN. It generates BLUE files using the commands</p> 305 306<p><tt>ntp-keygen -p qqsv -T -G -i blue</tt><br> 307<tt>ntp-keygen -p qqsv -e >ntpkey_gqpar_blue</tt></p> 308 309<p>The first line generates the host, trusted certificate and private GQ server keys file. The second generates the public GQ client parameters file, which can have any nonconflicting mnemonic name.</p> 310 311<p>The RED TH mort uses configuration commands</p> 312 313<p><tt>crypto pw xxx ident red</tt><br> 314<tt>peer macabre autokey</tt><br> 315<tt>broadcast <i>address</i> autokey</tt></p> 316 317<p>where <tt>xxx</tt> is the password for mort files. It generates RED files using the commands</p> 318 319<p><tt>ntp-keygen -p xxx -T -I -i red</tt><br> 320<tt>ntp-keygen -p xxx -e >ntpkey_iffpar_red</tt></p> 321 322<p> The GREEN TH howland uses configuration commands</p> 323 324<p><tt>crypto pw yyy ident green</tt><br> 325<tt>broadcastclient</tt></p> 326 327<p>where <tt>yyy</tt> is the password for howland files. It generates GREEN files using the commands</p> 328 329<p><tt>ntp-keygen -p yyy -T -G -i green</tt><br> 330<tt>ntp-keygen -p yyy -e >ntpkey_gqpar_green</tt><br> 331<tt>ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green</tt></p> 332 333<p>The first two lines serve the same purpose as the preceding examples. The 334 third line generates a copy of the private GREEN server file for use on another 335 server in the same group, say YELLOW, but encrypted with the <tt>zzz</tt> password.</p> 336 337<p>A client of GREEN, for example YELLOW, uses the configuration commands</p> 338 339<p><tt>crypto pw abc ident green</tt><br> 340<tt>server howland autokey</tt></p> 341 342<p>where <tt>abc</tt> is the password for its files. It generates files using the command</p> 343 344<p><tt>ntp-keygen -p abc</tt></p> 345 346<p>The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server keys file from the TH of that group, but it is encrypted and so must be sent using secure means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.</p> 347 348<p>Note that if servers of different groups, in this case RED and BLUE, share the same broadcast media, each server must have client files for all groups other than its own, while each client must have client files for all groups. Note also that this scenario is for illustration only and probably would not be wise for practical use, as if one of the TH reference clocks fails, the certificate trail becomes cyclic. In such cases the symmetric path between RED and BLUE, each in a different group, would not be a good idea.</p> 349 350<h4 id="cmd">Authentication Commands</h4> 351 352<dl> 353 354<dt id=automax><tt>automax [<i>logsec</i>]</tt></dt> 355<dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.</dd> 356 357<dt id="controlkey"><tt>controlkey <i>key</i></tt></dt> 358<dd>Specifies the key ID to use with the <a href="ntpq.html"><tt>ntpq</tt></a> utility, which uses the standard protocol defined in RFC-1305. The <tt><i>key</i></tt> argument is the key ID for a trusted key, where the value can be in the range 1 to 65,534, inclusive.</dd> 359 360<dt id="crypto"><tt>crypto [randfile <i>file</i>] [host <i>name</i>] [ident <i>name</i>] [pw <i>password</i>]</tt></dt> 361<dd>This command requires the OpenSSL library. It activates public key cryptography 362 and loads the required host key and public certificate. If one or more files 363 are left unspecified, the default names are used as described below. Unless 364 the complete path and name of the file are specified, the location of a file 365 is relative to the keys directory specified in the <tt>keysdir</tt> configuration 366 command or default <tt>/usr/local/etc</tt>. Following are the options.</dd> 367 368<dd><dl> 369 370<dt><tt>digest</tt> <tt>MD2</tt> | <tt>MD4</tt> | <tt>MD5</tt> | <tt>MDC2</tt> | <tt>RIPEMD160</tt> | <tt>SHA</tt> | <tt>SHA1</tt></dt> 371<dd>Specify the message digest algorithm, with default MD5. If the OpenSSL library 372 is installed, <tt><i>name</i></tt> can be be any message digest algorithm supported 373 by the library not exceeding 160 bits in length. However, all Autokey 374 participants in an Autokey subnet must use the same algorithm. Note that 375 the Autokey message digest algorithm is separate and distinct form the symmetric 376 key message digest algorithms. Note: If compliance with FIPS 140-2 is required, 377 the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>.</dd> 378 379<dt><tt>host <i>name</i></tt></dt> 380<dd>Specifies the string used when constructing the names for the host, sign 381 and certificate files generated by the <tt>ntp-keygen</tt> program with the <tt>-s <i>name</i></tt> option.</dd> 382 383<dt><tt>ident <i>name</i></tt></dt> 384<dd>Specifies the string used in constructing the identity files generated by the <tt>ntp-keygen</tt> program with the <tt>-i <i>name</i></tt> option.</dd> 385 386<dt><tt>pw <i>password</i></tt></dt> 387<dd>Specifies the password to decrypt files previously encrypted by the <tt>ntp-keygen</tt> program with the <tt>-p</tt> option.</dd> 388 389<dt><tt>randfile <i>file</i></tt></dt> 390<dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the <tt>ntp-keygen</tt> page.</dd> 391 392</dl></dd> 393 394<dt id="keys"><tt>keys <i>keyfile</i></tt></dt> 395<dd>Specifies the complete path to the MD5 key file containing the keys and key IDs used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt> when operating with symmetric key cryptography. This is the same operation as the <tt>-k </tt>command line option. Note that the directory path for Autokey media is specified by the <tt>keysdir</tt> command.</dd> 396 397<dt id="keysdir"><tt>keysdir <i>path</i></tt>K</dt> 398<dd>This command specifies the default directory path for Autokey cryptographic keys, parameters and certificates. The default is <tt>/usr/local/etc/</tt>. Note that the path for the symmetric keys file is specified by the <tt>keys</tt> command.</dd> 399 400<dt id="requestkey"><tt>requestkey <i>key</i></tt></dt> 401<dd>Specifies the key ID to use with the <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utility programs, which uses a proprietary protocol specific to this implementation of <tt>ntpd</tt>. The <tt><i>key</i></tt> argument is a key ID for the trusted key, where the value can be in the range 1 to 65,534, inclusive.</dd> 402 403<dt id="revoke"><tt>revoke [<i>logsec</i>]</tt></dt> 404<dd>Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 17 (about 36 h). For poll intervals above the specified interval, the values will be updated for every message sent.</dd> 405 406<dt id="trustedkey"><tt>trustedkey <i>key</i> [...]</tt></dt> 407<dd>Specifies the key ID(s) which are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. The authentication procedures require that both the local and remote servers share the same key and key ID for this purpose, although different keys can be used with different servers.</dd> 408</dl> 409 410<h4 id="err">Error Codes</h4> 411 412<p>Errors can occur due to mismatched configurations, unexpected protocol restarts, expired certificates and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errors is expired certificates, which must be regenerated and signed at least once per year using the <a href="keygen.html"><tt>ntp-keygen</tt> - generate public and private keys</a> program.</p> 413 414<p>The following error codes are reported via the NTP control and monitoring protocol trap mechanism and to the <tt>cryptostats</tt> monitoring file if configured.</p> 415 416<dl> 417 418<dt>101 bad field format or length</dt> 419<dd>The packet has invalid version, length or format.</dd> 420 421<dt>102 bad timestamp</dt> 422<dd>The packet timestamp is the same or older than the most recent received. This could be due to a replay or a server clock time step.</dd> 423 424<dt>103 bad filestamp</dt> 425<dd>The packet filestamp is the same or older than the most recent received. This could be due to a replay or a key file generation error.</dd> 426 427<dt>104 bad or missing public key</dt> 428<dd>The public key is missing, has incorrect format or is an unsupported type.</dd> 429 430<dt>105 unsupported digest type</dt> 431<dd>The server requires an unsupported digest/signature scheme.</dd> 432 433<dt>106 unsupported identity type</dt> 434<dd>The client or server has requested an identity scheme the other does not support.</dd> 435 436<dt>107 bad signature length</dt> 437<dd>The signature length does not match the current public key.</dd> 438 439<dt>108 signature not verified</dt> 440<dd>The message fails the signature check. It could be bogus or signed by a different private key.</dd> 441 442<dt>109 certificate not verified</dt> 443<dd>The certificate is invalid or signed with the wrong key.</dd> 444 445<dt>110 host certificate expired</dt> 446<dd>The old server certificate has expired.</dd> 447 448<dt>111 bad or missing cookie</dt> 449<dd>The cookie is missing, corrupted or bogus.</dd> 450 451<dt>112 bad or missing leapseconds table</dt> 452<dd>The leapseconds table is missing, corrupted or bogus.</dd> 453 454<dt>113 bad or missing certificate</dt> 455<dd>The certificate is missing, corrupted or bogus.</dd> 456 457<dt>114 bad or missing group key</dt> 458<dd>The identity key is missing, corrupt or bogus.</dd> 459 460<dt>115 protocol error</dt> 461<dd>The protocol state machine has wedged due to unexpected restart.</dd> 462 463</dl> 464 465<h4 id="file">Files</h4> 466 467<p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page. Note that provisions to load leap second values from the NIST files have been removed. These provisions are now available whether or not the OpenSSL library is available. However, the functions that can download these values from servers remains available.</p> 468 469<hr> 470 471<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 472 473</body> 474 475</html>
