authopt.html revision 132451
1132451Sroberto<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2132451Sroberto 3132451Sroberto<html> 4132451Sroberto 5132451Sroberto <head> 6132451Sroberto <meta name="generator" content="HTML Tidy, see www.w3.org"> 7132451Sroberto <title>Authentication Options</title> 8132451Sroberto <link href="scripts/style.css" type="text/css" rel="stylesheet"> 9132451Sroberto </head> 10132451Sroberto 11132451Sroberto <body> 12132451Sroberto <h3>Authentication Options</h3> 13132451Sroberto <img src="pic/alice44.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> 14132451Sroberto <p>Our resident cryptographer; now you see him, now you don't.</p> 15132451Sroberto <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="99">03:05 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="270">Monday, October 13, 2003</csobj></p> 16132451Sroberto <br clear="left"> 17132451Sroberto <h4>Related Links</h4> 18132451Sroberto <script type="text/javascript" language="javascript" src="scripts/links9.txt"></script> 19132451Sroberto <h4>Table of Contents</h4> 20132451Sroberto <ul> 21132451Sroberto <li class="inline"><a href="#auth">Authentication Support</a> 22132451Sroberto <li class="inline"><a href="#symm">Symmetric Key Cryptography</a> 23132451Sroberto <li class="inline"><a href="#pub">Public Key Cryptography</a> 24132451Sroberto <li class="inline"><a href="#auto">Autokey Dances</a> 25132451Sroberto <li class="inline"><a href="#inter">Operation</a> 26132451Sroberto <li class="inline"><a href="#key">Key Management</a> 27132451Sroberto <li class="inline"><a href="#cmd">Authentication Commands</a> 28132451Sroberto <li class="inline"><a href="#err">Error Codes</a> 29132451Sroberto <li class="inline"><a href="#file">Files</a> 30132451Sroberto </ul> 31132451Sroberto <hr> 32132451Sroberto <h4 id="auth">Authentication Support</h4> 33132451Sroberto <p>Authentication support allows the NTP client to verify that the server is in fact known and trusted and not an intruder intending accidentally or on purpose to masquerade as that server. The NTPv3 specification RFC-1305 defines a scheme which provides cryptographic authentication of received NTP packets. Originally, this was done using the Data Encryption Standard (DES) algorithm operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by the RSA Message Digest 5 (MD5) algorithm using a private key, commonly called keyed-MD5. Either algorithm computes a message digest, or one-way hash, which can be used to verify the server has the correct private key and key identifier.</p> 34132451Sroberto <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key cryptography and, in addition, provides a new Autokey scheme based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on a private value which is generated by each server and never revealed. With Autokey all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, which can be provided by commercial services or produced by utility programs in the OpenSSL software library or the NTPv4 distribution.</p> 35132451Sroberto <p>While the algorithms for symmetric key cryptography are included in the NTPv4 distribution, public key cryptography requires the OpenSSL software library to be installed before building the NTP distribution. Directions for doing that are on the <a href="build.html">Building and Installing the Distribution</a> page.</p> 36132451Sroberto <p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> subcommand on the <tt>peer</tt>, <tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> configuration commands as described in the <a href="confopt.html">Configuration Options</a> page. The authentication options described below specify the locations of the key files, if other than default, which symmetric keys are trusted and the interval between various operations, if other than default.</p> 37132451Sroberto <p>Authentication is always enabled, although ineffective if not configured as described below. If a NTP packet arrives including a message authentication code (MAC), it is accepted only if it passes all cryptographic checks. The checks require correct key ID, key value and message digest. If the packet has been modified in any way or replayed by an intruder, it will fail one or more of these checks and be discarded. Furthermore, the Autokey scheme requires a preliminary protocol exchange to obtain the server certificate, verify its credentials and initialize the protocol</p> 38132451Sroberto <p>The <tt>auth</tt> flag controls whether new associations or remote configuration commands require cryptographic authentication. This flag can be set or reset by the <tt>enable</tt> and <tt>disable</tt> commands and also by remote configuration commands sent by a <tt>ntpdc</tt> program running on another machine. If this flag is enabled, which is the default case, new broadcast/manycast client and symmetric passive associations and remote configuration commands must be cryptographically authenticated using either symmetric key or public key cryptography. If this flag is disabled, these operations are effective even if not cryptographic authenticated. It should be understood that operating with the <tt>auth</tt> flag disabled invites a significant vulnerability where a rogue hacker can masquerade as a falseticker and seriously disrupt system timekeeping. It is important to note that this flag has no purpose other than to allow or disallow a new association in response to new broadcast and symmetric active messages and remote configuration commands and, in particular, the flag has no effect on the authentication process itself.</p> 39132451Sroberto <p>An attractive alternative where multicast support is available is manycast mode, in which clients periodically troll for servers as described in the <a href="manyopt.html">Automatic NTP Configuration Options</a> page. Either symmetric key or public key cryptographic authentication can be used in this mode. The principle advantage of manycast mode is that potential servers need not be configured in advance, since the client finds them during regular operation, and the configuration files for all clients can be identical.</p> 40132451Sroberto <p>The security model and protocol schemes for both symmetric key and public key cryptography are summarized below; 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> 41132451Sroberto <h4 id="symm">Symmetric Key Cryptography</h4> 42132451Sroberto The original RFC-1305 specification allows any one of possibly 65,534 keys, each distinguished by a 32-bit key identifier, to authenticate an association. The servers and clients involved must agree on the key and key identifier to authenticate NTP packets. Keys and related information are specified in a key file, usually called <tt>ntp.keys</tt>, which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, 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 programs. 43132451Sroberto <p>When <tt>ntpd</tt> is first started, it reads the key file specified in the <tt>keys</tt> configuration command and installs the keys in the key cache. However, individual keys must be activated with the <tt>trusted</tt> command before use. This allows, for instance, the installation of possibly several batches of keys and then activating or deactivating each batch remotely using <tt>ntpdc</tt>. This also provides a revocation capability that can be used if a key becomes compromised. The <tt>requestkey</tt> command selects the key used as the password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt> command selects the key used as the password for the <tt>ntpq</tt> utility.</p> 44132451Sroberto <h4 id="pub">Public Key Cryptography</h4> 45132451Sroberto <p>NTPv4 supports the original NTPv3 symmetric key scheme described in RFC-1305 and in addition the Autokey protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source with 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">Identity Schemes</a> page and based on cryptographic challenge/response algorithms are also available. Using all of these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks.</p> 46132451Sroberto <p>The cryptographic means necessary for all Autokey operations is provided by the OpenSSL software library. This library is available from <a href="http://www.openssl.org">http://www.openssl.org</a> and can be installed using the procedures outlined in the <a href="build.html">Building and Installing the Distribution</a> page. Once installed, the configure and build process automatically detects the library and links the library routines required.</p> 47132451Sroberto <p>The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. Most modes use a special cookie which can be computed independently by the client and server, but encrypted in transmission. All modes use in addition a variant of the S-KEY scheme, in which a pseudo-random key list is generated and used in reverse order. 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> 48132451Sroberto <p>The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program. . This includes a required host key file, required certificate file and optional sign key file, leapsecond file and identity scheme files. The digest/signature scheme is specified in the X.509 certificate along with the matching sign key. There are several schemes available in the OpenSSL software library, each identified by a specific string such as <tt>md5WithRSAEncryption</tt>, which stands for the MD5 message digest with RSA encryption scheme. The current NTP distribution supports all the schemes in the OpenSSL library, including those based on RSA and DSA digital signatures.</p> 49132451Sroberto <p>NTP secure groups can be used to define cryptographic compartments and security hierarchies. It is important that every host in the group be able to construct a certificate trail to one or more trusted hosts in the same group. Each group host runs the Autokey protocol to obtain the certificates for all hosts along the trail to one or more trusted hosts. This requires the configuration file in all hosts to be engineered so that, even under anticipated failure conditions, the NTP subnet will form such that every group host can find a trail to at least one trusted host.</p> 50132451Sroberto <h4>Naming and Addressing</h4> 51132451Sroberto <p>It is important to note that Autokey does not use DNS to resolve addresses, since DNS can't be completely trusted until the name servers have synchronized clocks. The cryptographic name used by Autokey to bind the host identity credentials and cryptographic values must be independent of interface, network and any other naming convention. The name appears in the host certificate in either or both the subject and issuer fields, so protection against DNS compromise is essential.</p> 52132451Sroberto <p>By convention, the name of an Autokey host is the name returned by the Unix <tt>gethostname()</tt> system call or equivalent in other systems. By the system design model, there are no provisions to allow alternate names or aliases. However, this is not to say that DNS aliases, different names for each interface, etc., are constrained in any way.</p> 53132451Sroberto <p>It is also important to note that Autokey verifies authenticity using the host name, network address and public keys, all of which are bound together by the protocol specifically to deflect masquerade attacks. For this reason Autokey includes the source and destinatino IP addresses in message digest computations and so the same addresses must be available 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> 54132451Sroberto <h4>Operation</h4> 55132451Sroberto <p>A specific combination of authentication scheme (none, symmetric key, public key) and identity scheme is called a cryptotype, although not all combinations are compatible. There may be management configurations where the clients, servers and peers may not all support the same cryptotypes. A secure NTPv4 subnet can be configured in many ways while keeping in mind the principles explained above and in this section. Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice.</p> 56132451Sroberto <p>The cryptotype of an association is determined at the time of mobilization, either at configuration time or some time later when a message of appropriate cryptotype arrives. When mobilized by a <tt>server</tt> or <tt>peer</tt> configuration command and no <tt>key</tt> or <tt>autokey</tt> subcommands are present, the association is not authenticated; if the <tt>key</tt> subcommand is present, the association is authenticated using the symmetric key ID specified; if the <tt>autokey</tt> subcommand is present, the association is authenticated using Autokey.</p> 57132451Sroberto <p>When multiple identity schemes are supported in the Autokey protocol, the first message exchange determines which one is used. The client request message contains bits corresponding to which schemes it has available. The server response message contains bits corresponding to which schemes it has available. Both server and client match the received bits with their own and select a common scheme.</p> 58132451Sroberto <p>Following the principle that time is a public value, a server responds to any client packet that matches its cryptotype capabilities. Thus, a server receiving an unauthenticated packet will respond with an unauthenticated packet, while the same server receiving a packet of a cryptotype it supports will respond with packets of that cryptotype. However, unconfigured broadcast or manycast client associations or symmetric passive associations will not be mobilized unless the server supports a cryptotype compatible with the first packet received. By default, unauthenticated associations will not be mobilized unless overridden in a decidedly dangerous way.</p> 59132451Sroberto <p>Some examples may help to reduce confusion. Client Alice has no specific cryptotype selected. Server Bob has both a symmetric key file and minimal Autokey files. Alice's unauthenticated messages arrive at Bob, who replies with unauthenticated messages. Cathy has a copy of Bob's symmetric key file and has selected key ID 4 in messages to Bob. Bob verifies the message with his key ID 4. If it's the same key and the message is verified, Bob sends Cathy a reply authenticated with that key. If verification fails, Bob sends Cathy a thing called a crypto-NAK, which tells her something broke. She can see the evidence using the <tt>ntpq</tt> program.</p> 60132451Sroberto <p>Denise has rolled her own host key and certificate. She also uses one of the identity schemes as Bob. She sends the first Autokey message to Bob and they both dance the protocol authentication and identity steps. If all comes out okay, Denise and Bob continue as described above.</p> 61132451Sroberto <p>It should be clear from the above that Bob can support all the girls at the same time, as long as he has compatible authentication and identity credentials. Now, Bob can act just like the girls in his own choice of servers; he can run multiple configured associations with multiple different servers (or the same server, although that might not be useful). But, wise security policy might preclude some cryptotype combinations; for instance, running an identity scheme with one server and no authentication with another might not be wise.</p> 62132451Sroberto <h4 id="key">Key Management</h4> 63132451Sroberto <p>The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program, including symmetric key, host key and public certificate files, as well as sign key, identity parameters and leapseconds files. Alternatively, host and sign keys and certificate files can be generated by the OpenSSL utilities and certificates can be imported from public certificate authorities. Note that symmetric keys are necessary for the <tt>ntpq</tt> and <tt>ntpdc</tt> utility programs. The remaining files are necessary only for the Autokey protocol.</p> 64132451Sroberto <p>Certificates imported from OpenSSL or public certificate authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format used by OpenSSL. The overall length of the certificate encoded in ASN.1 must not exceed 1024 bytes. The subject distinguished name field (<tt>CN</tt>) is the fully qualified name of the host on which it is used; the remaining subject fields are ignored. The certificate extension fields must not contain either a subject key identifier or a issuer key identifier field; however, an extended key usage field for a trusted host must contain the value <tt>trustRoot</tt>;. Other extension fields are ignored.</p> 65132451Sroberto <h4 id="cmd">Authentication Commands</h4> 66132451Sroberto <dl> 67132451Sroberto <dt><tt>autokey [<i>logsec</i>]</tt> 68132451Sroberto <dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. 69132451Sroberto <dt><tt>controlkey <i>key</i></tt> 70132451Sroberto <dd>Specifies the key identifier 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 identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive. 71132451Sroberto <dt><tt>crypto [cert <i>file</i>] [leap <i>file</i>] [randfile <i>file</i>] [host <i>file</i>] [sign <i>file</i>] [gq <i>file</i>] [gqpar <i>file</i>] [iffpar <i>file</i>] [mvpar <i>file</i>] [pw <i>password</i>]</tt> 72132451Sroberto <dd>This command requires the OpenSSL library. It activates public key cryptography, selects the message digest and signature encryption scheme and loads the required private and public values described above. If one or more files are left unspecified, the default names are used as described above. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the <tt>keysdir</tt> command or default <tt>/usr/local/etc</tt>. Following are the subcommands: <dl> 73132451Sroberto <dt><tt>cert <i>file</i></tt> 74132451Sroberto <dd>Specifies the location of the required host public certificate file. This overrides the link <tt>ntpkey_cert_<i>hostname</i></tt> in the keys directory. 75132451Sroberto <dt><tt>gqpar <i>file</i></tt> 76132451Sroberto <dd>Specifies the location of the optional GQ parameters file. This overrides the link <tt>ntpkey_gq_<i>hostname</i></tt> in the keys directory. 77132451Sroberto <dt><tt>host <i>file</i></tt> 78132451Sroberto <dd>Specifies the location of the required host key file. This overrides the link <tt>ntpkey_key_<i>hostname</i></tt> in the keys directory. 79132451Sroberto <dt><tt>iffpar <i>file</i></tt> 80132451Sroberto <dd>Specifies the location of the optional IFF parameters file.This overrides the link <tt>ntpkey_iff_<i>hostname</i></tt> in the keys directory. 81132451Sroberto <dt><tt>leap <i>file</i></tt> 82132451Sroberto <dd>Specifies the location of the optional leapsecond file. This overrides the link <tt>ntpkey_leap</tt> in the keys directory. 83132451Sroberto <dt><tt>mvpar <i>file</i></tt> 84132451Sroberto <dd>Specifies the location of the optional MV parameters file. This overrides the link <tt>ntpkey_mv_<i>hostname</i></tt> in the keys directory. 85132451Sroberto <dt><tt>pw <i>password</i></tt> 86132451Sroberto <dd>Specifies the password to decrypt files containing private keys and identity parameters. This is required only if these files have been encrypted. 87132451Sroberto <dt><tt>randfile <i>file</i></tt> 88132451Sroberto <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above. 89132451Sroberto <dt><tt>sign <i>file</i></tt> 90132451Sroberto <dd>Specifies the location of the optional sign key file. This overrides the link <tt>ntpkey_sign_<i>hostname</i></tt> in the keys directory. If this file is not found, the host key is also the sign key. 91132451Sroberto </dl> 92132451Sroberto <dt><tt>keys <i>keyfile</i></tt> 93132451Sroberto <dd>Specifies the complete path and location of the MD5 key file containing the keys and key identifiers 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. 94132451Sroberto <dt><tt>keysdir <i>path</i></tt> 95132451Sroberto <dd>This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is <tt>/usr/local/etc/</tt>. 96132451Sroberto <dt><tt>requestkey <i>key</i></tt> 97132451Sroberto <dd>Specifies the key identifier to use with the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program, which uses a proprietary protocol specific to this implementation of <tt>ntpd</tt>. The <tt><i>key</i></tt> argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive. 98132451Sroberto <dt><tt>revoke [<i>logsec</i>]</tt> 99132451Sroberto <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 of the scheme; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent. 100132451Sroberto <dt><tt>trustedkey <i>key</i> [...]</tt> 101132451Sroberto <dd>Specifies the key identifiers 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 identifier for this purpose, although different keys can be used with different servers. The <tt><i>key</i></tt> arguments are 32-bit unsigned integers with values from 1 to 65,534. 102132451Sroberto </dl> 103132451Sroberto <h4 id="err">Error Codes</h4> 104132451Sroberto <p>The following error codes are reported via the NTP control and monitoring protocol trap mechanism.</p> 105132451Sroberto <dl> 106132451Sroberto <dt>101 (bad field format or length) 107132451Sroberto <dd>The packet has invalid version, length or format. 108132451Sroberto <dt>102 (bad timestamp) 109132451Sroberto <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. 110132451Sroberto <dt>103 (bad filestamp) 111132451Sroberto <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. 112132451Sroberto <dt>104 (bad or missing public key) 113132451Sroberto <dd>The public key is missing, has incorrect format or is an unsupported type. 114132451Sroberto <dt>105 (unsupported digest type) 115132451Sroberto <dd>The server requires an unsupported digest/signature scheme. 116132451Sroberto <dt>106 (mismatched digest types) 117132451Sroberto <dd>Not used. 118132451Sroberto <dt>107 (bad signature length) 119132451Sroberto <dd>The signature length does not match the current public key. 120132451Sroberto <dt>108 (signature not verified) 121132451Sroberto <dd>The message fails the signature check. It could be bogus or signed by a different private key. 122132451Sroberto <dt>109 (certificate not verified) 123132451Sroberto <dd>The certificate is invalid or signed with the wrong key. 124132451Sroberto <dt>110 (certificate not verified) 125132451Sroberto <dd>The certificate is not yet valid or has expired or the signature could not be verified. 126132451Sroberto <dt>111 (bad or missing cookie) 127132451Sroberto <dd>The cookie is missing, corrupted or bogus. 128132451Sroberto <dt>112 (bad or missing leapseconds table) 129132451Sroberto <dd>The leapseconds table is missing, corrupted or bogus. 130132451Sroberto <dt>113 (bad or missing certificate) 131132451Sroberto <dd>The certificate is missing, corrupted or bogus. 132132451Sroberto <dt>114 (bad or missing identity) 133132451Sroberto <dd>The identity key is missing, corrupt or bogus. 134132451Sroberto </dl> 135132451Sroberto <h4 id="file">Files</h4> 136132451Sroberto <p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page.</p> 137132451Sroberto <h4 id="leap">Leapseconds Table</h4> 138132451Sroberto <p>The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers using <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</p> 139132451Sroberto <p>While not strictly a security function, the Autokey protocol provides means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the <tt>crypto</tt> command, with default <tt>ntpkey_leap</tt>, while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.</p> 140132451Sroberto <hr> 141132451Sroberto <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 142132451Sroberto </body> 143132451Sroberto 144132451Sroberto</html>