= Authentication Support
include::include-html.ad[]

[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.adoc[]
include::includes/authopt.adoc[]

== Table of Contents

* link:#auth[Introduction]
* link:#mac[MAC authentication]
* link:#nts[Network Time Security]
* link:#windows[Microsoft Windows Authentication]
* link:#autokey[Autokey]

'''''

== Introduction

Authentication support allows the NTP client to verify that the server
is in fact known and trusted and not an intruder accidentally
or intentionally masquerading as that server.  It does nothing
to verify or guarantee correct time, nor does it even conceal
timestamp information from anyone who can watch the traffic.

There are three forms of authentication: MAC, NTS, and MS-SNTP.  This
section describes all three. Each is configured separately for each
association by options to the server command.

Note: MAC authentication is going to be replaced by NTS.  MAC
authentication may be removed in a future release of NTPsec.

An "Autokey" mode using an early form of public-key cryptography
formerly existed but has been removed.

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

[[mac]]
=== MAC authentication

MAC authentication uses symmetric-key cryptography via message
digests. It computes a one-way hash, which verifies that the server
has the correct private key and key identifier.

Beware: both commonly supported message digest formats, MD5 and SHA-1,
have been either entirely or partly cracked, and should not be
considered strong security.

MAC authentication is is configured using the +key+ subcommand on the
+server+ configuration commands. The authentication options described
below specify the locations of the key files and which symmetric keys
are trusted.

Authentication is always enabled, although ineffective if not configured
as described below. If an 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
by an intruder, it will fail one or more of these checks and be
discarded.  Authentication doesn't prevent replays.

NTP allows use of any one of possibly 65,535 keys, each distinguished by a
32-bit key identifier, to authenticate an association. Both server and
client must agree on the key and key identifier in order to
authenticate NTP packets. Keys and related information are specified
in a key file. More info in {ntpkeysman}. It 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 +trustedkey+ 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]]
=== MAC Operation

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.

Some examples may help to reduce confusion.

Client Alice has no key file. Server Bob has a symmetric key file.
Alice sends an unauthenticated message to Bob. Bob therefore replies
also with an unauthenticated message.

Client Carol does have a copy of Bob's symmetric key file. Carol selects
key ID 4, and sends a message to Bob. Bob verifies the message with his
key ID 4. If the key matches and the message verifies, Bob replies to
Carol with a message authenticated with his key ID 4. If verification fails,
Bob sends Carol a crypto-NAK, which tells her that something is broken.
She can see the evidence using the {ntpqman} program.

It should be clear from the above that Bob can support both unauthenticated
Alice and authenticated Carol alike. Unauthenticated messages will
receive unauthenticated replies. Authenticated messages will receive
authenticated replies, assuming the authentication method and credentials
are valid and compatible.

Bob also can act just like Alice and Carol in his own choice of connections
to other servers; he can run multiple configured associations with multiple
different servers (or the same server, although that might not be useful).

[[keys]]
=== MAC Key Management

Shared keys used for authentication are incorporated
into the keys files generated by the {ntpkeygenman} utility
program.

[[algorithms]]
=== MAC Algorithms

The NTP standards include symmetric (private-key) authentication using
any message digest algorithm supported by the OpenSSL package.
NTPsec will truncate digests longer than 20 bytes.
This algorithm computes a message digest or one-way hash
which can be used to verify that the client has the same message digest as
the server.

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]]
=== MAC Data Formats

The NTPv4 specification (RFC 5905) allows any one of possibly 65,535
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-1. While, +ntpd+'s digest mode could use any digest
supported by libcrypto from the OpenSSL project, in practice MD5 and
SHA-1 are the only supported types. This is very unlikely to change
before MAC authentication is obsolesced by NTS.

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 the key concatenated with
the NTP packet header fields and the key ID.  On transmit, the message
digest is computed and inserted into the MAC.  On receive, the message
digest is computed and compared with the MAC.  The packet is only
accepted if the two MACs are identical. If the client finds a
discrepancy, then it ignores the packet but raises the alarm. If this
happens at the server, the server returns a special message called a
crypto-NAK. Since the loopback test protects the crypto-NAK, 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.  See {ntpkeysman} for details.

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

Figure 1 shows a typical keys file. 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.
Any line can be edited to change any field or new lines can
be added. 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.

[[nts]]
== Network Time Security

Network Time security (NTS) uses the TLS public-key encryption
infrastructure to secure and authenticate associations.

This section is a placeholder for complete documentation on NTS. The
NTS implementation is work in progress conforming to a draft RFC not
yet (December 2019) accepted.  For configuration examples, see the
link:NTS-QuickStart.html[NTS Quick Start Guide].

NTPsec's future direction is to fully support NTS and eventually
remove older, insecure authentication methods.

[[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 requires the
+--enable-mssntp+ option to +waf configure+.  At run time, it is enabled
using the +mssntp+ flag of the +restrict+ command described on the
link:accopt.html#restrict[Access Control Options] page. *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.*

[[autokey]]
== Autokey

Old versions of NTP supported Autokey, which used an early form of
public-key cryptography for authentication. It is described in RFC 5906.

Unfortunately, autokey was buggy and a source of vulnerabilities; it
has been removed. NTS is intended to replace it. It is mentioned here
only for historical completeness.


'''''

include::includes/footer.adoc[]
