= Authentication Support =

[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
|image:pic/alice44.gif[]|
{millshome}pictures.html[from 'Alice's Adventures in Wonderland', Lewis Carroll]

Our resident cryptographer; now you see him, now you don't.

|==============================

== Related Links ==

include::includes/hand.txt[]
include::includes/authopt.txt[]

== Table of Contents ==

* link:#auth[Introduction]
* link:#symm[Symmetric Key Cryptography]
* link:#operation[Operation]
* link:#keys[Key Management]
* link:#algorithms[Algorithms]
* link:#formats[Data Formats]
//* link:#windows[Microsoft Windows Authentication]
* link:#pub[Public Key Cryptography]

'''''

== Introduction ==

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.  NTP performs
authentication via 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.

A detailed discussion of the NTP multi-layer security model and
vulnerability analysis is in the white paper
{millshome}security.html[NTP Security Analysis].

Authentication is configured separately for each association using the +key+
subcommand on the +peer+, +server+, and +broadcast+
configuration commands. 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.

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.

The security model and protocol schemes for symmetric key
are summarized below.

[[symm]]
=== Symmetric-Key Cryptography ===

NTP 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 _ntp.keys_, 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 {ntpqman} utility
program.

When {ntpdman} is first started, it reads the key file specified
in the keys configuration command and installs the keys in the key cache.
However, individual keys must be activated with the trusted command before
use. This allows, for instance, the installation of possibly several
batches of keys and then activating or deactivating each batch remotely
using {ntpqman}. This also provides a revocation capability
that can be used if a key becomes compromised. The controlkey command
selects the key used as the password for the {ntpqman} utility.

[[operation]]
== Operation ==

A specific combination of authentication scheme (none, symmetric 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 NTP 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.

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 +server+
or +peer+ configuration command and no +key+ subcommands
are present, the association is not authenticated; if the +key+
subcommand is present, the association is authenticated using the
symmetric key ID specified.

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.

Some examples may help to reduce confusion. Client Alice has no specific
cryptotype selected. Server Bob has a symmetric key file.
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
{ntpqman} program.

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.

[[keys]]
== Key Management ==

The cryptographic values used for authentication are incorporated
as a set of files generated by the {ntpkeygenman} utility
program, including symmetric key and leapseconds files.

[[algorithms]]
== Algorithms ==

The NTP standards include symmetric (private-key) authentication using
the RSA Message Digest 5 (MD5) algorithm, commonly called
keyed-MD5. This algorithm computes a message digest or one-way hash
which can be used to verify the client has the same message digest as
the server. The MD5 message digest algorithm is included in the
distribution, so without further cryptographic support, the
distribution can be freely exported.

If the OpenSSL cryptographic library is installed prior to building the
distribution, all message digest algorithms included in the library may
be used, including SHA and SHA1. However, if conformance to FIPS 140-2
is required, only a limited subset of these algorithms can be used. This
library is available from http://www.openssl.org and can be installed
using the procedures outlined in the link:build.html[Building and
Installing the Distribution] page. Once installed, the configure and
build process automatically detects the library and links the library
routines required.

Note that according to US law, NTP binaries including OpenSSL library
components, including the OpenSSL library itself, cannot be exported
outside the US without license from the US Department of Commerce.
(However, these restrictions have been considerably relaxed since 1996.)
Builders outside the US are advised to obtain the OpenSSL library
directly from OpenSSL, which is outside the US, and build outside the
US.

Authentication is configured separately for each association using the
+key+ option of the +server+ configuration command, as
described in the link:confopt.html[Server Options] page. The
link:ntpkeygen.html[ntpkeygen] page describes the files required for the
various authentication schemes.

By default, the client sends non-authenticated packets and the server
responds with non-authenticated packets. If the client sends
authenticated packets, the server responds with authenticated packets if
correct, or a crypto-NAK packet if not. The +notrust +flag, described on the
link:authopt.html[Access Control Options] page, can be used to disable
access to all but correctly authenticated clients.

[[formats]]
== Data Formats ==

The NTPv4 specification (RFC 5905) allows any one of possibly 65,534
message digest keys (excluding zero), each distinguished by a 32-bit key
ID, to authenticate an association. The servers and clients involved
must agree on the key ID, key type and key to authenticate NTP packets.

The message digest is a cryptographic hash computed by an algorithm such
as MD5 or SHA. When authentication is specified, a message
authentication code (MAC) is appended to the NTP packet header. The MAC
consists of a 32-bit key identifier (key ID) followed by a 128- or
160-bit message digest. The algorithm computes the digest as the hash of
a 128- or 160- bit message digest key concatenated with the NTP packet
header fields with the exception of the MAC. On transmit, the message
digest is computed and inserted in the MAC. On receive, the message
digest is computed and compared with the MAC. The packet is accepted
only if the two MACs are identical. If a discrepancy is found by the
client, the client ignores the packet, but raises an alarm. If this
happens at the server, the server returns a special message called a
_crypto-NAK_. Since the crypto-NAK is protected by the loopback test, an
intruder cannot disrupt the protocol by sending a bogus crypto-NAK.

Keys and related information are specified in a keys file, 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 +ntpq+
utility program. Ordinarily, the +ntp.keys+ file is generated by the
+ntpkeygen+ program, but it can be constructed and edited using an
ordinary text editor.

Each line of the keys file consists of three fields: a key ID in the
range 1 to 65,534, inclusive, a key type, and a message digest key
consisting of a printable ASCII string less than 40 characters, or a
40-character hex digit string. If the OpenSSL library is installed, the
key type can be any message digest algorithm supported by the library.
If the OpenSSL library is not installed, the only permitted key type is
MD5.

.Figure 1. Typical Symmetric Key File
image:pic/sx5.gif["Typical Symmetric Key File",align="center"]


Figure 1 shows a typical keys file used by the reference implementation
when the OpenSSL library is installed. In this figure, for key IDs in he
range 1-10, the key is interpreted as a printable ASCII string. For key
IDs in the range 11-20, the key is a 40-character hex digit string. The
key is truncated or zero-filled internally to either 128 or 160 bits,
depending on the key type. The line can be edited later or new lines can
be added to change any field. The key can be change to a password, such
as +2late4Me+ for key ID 10. Note that two or more keys files can be
combined in any order as long as the key IDs are distinct.

When +ntpd+ is started, it reads the keys file specified by the +keys+
command and installs the keys in the key cache. However, individual keys
must be activated with the +trustedkey+ configuration command before
use. This allows, for instance, the installation of possibly several
batches of keys and then activating a key remotely using +ntpq+.
The +controlkey+ command selects the key ID used as the password
for the +ntpq+ utility.

[[windows]]
== Microsoft Windows Authentication ==

In addition to the above means, +ntpd+ supports Microsoft Windows
MS-SNTP authentication using Active Directory services. This support was
contributed by the Samba Team and is still in development. It is enabled
using the +mssntp+ flag of the +restrict+ command described on the
link:accopt.html#restrict[Access Control Options] page. [red]#Note: Potential
users should be aware that these services involve a TCP connection to
another process that could potentially block, denying services to other
users. Therefore, this flag should be used only for a dedicated server
with no clients other than MS-SNTP.

'''''

include::includes/footer.txt[]
