Time

The machine's clock is kept by timed, and timed is the only process on the machine permitted to set it.

That is not a figure of speech. Setting the clock needs SeSystemtimePrivilege, which is granted to timed's service identity and to nothing else, so "what on this machine can change the time" has a one-line answer that an administrator can check.

Why this is worth caring about #

A wrong clock does not look like a wrong clock. It looks like:

• certificates that are expired, or not yet valid, and TLS that fails for reasons that make no sense;
• Kerberos tickets refused across a domain, because Kerberos treats a clock skew as evidence of a replay;
• logs from two machines that cannot be put in order, which is exactly when you most need them to be.

So time is not a convenience. It is something several other things quietly depend on, and an attacker who can move it has more than a wrong clock.

Sources are not trusted individually #

timed polls several servers and does not believe any of them. Each one reports not a time but an interval it promises the true time lies within, and timed looks for the largest set of intervals that overlap. A server outside that overlap is a falseticker and is discarded, however confident it sounded.

The consequence is worth stating, because it is what makes the scheme work: a server that claims great accuracy and is wrong excludes itself. Its interval is narrow, so it cannot reach the agreement. Overclaiming is the one lie the arrangement punishes automatically.

With three independent sources this survives one liar. With two that disagree there is no way to tell which is right, and timed reports itself unsynchronised rather than guessing — which is why the shipped default is three operators and why you should configure at least three of your own.

Every source is authenticated #

By default timed will not use a source that cannot prove who it is. That is NTS (RFC 8915): a TLS handshake on port 4460 establishes a pair of keys, and every NTP packet afterwards carries a tag computed with them. Forging a reply requires the key.

The certificate is validated against the machine's trust store, over trustd's socket — so a certificate authority you distrust is distrusted here too, immediately, without timed needing to be restarted.

On a network that blocks port 4460 the honest outcome is a machine that says it is unsynchronised. AllowUnauthenticated exists for networks where that is not acceptable; see configuring sources for what you give up.

The default sources #

A machine that has been told nothing uses four names in our own zone:

0.time.peios.org    →  time.cloudflare.com
1.time.peios.org    →  nts.netnod.se
2.time.peios.org    →  ptbtime1.ptb.de
3.time.peios.org    →  ptbtime2.ptb.de

Three independent operators in three jurisdictions — a commercial network, a Swedish national infrastructure operator, and Germany's national metrology institute. Independence is what makes the votes worth counting: three servers run by one operator would agree with each other about anything.

The indirection through time.peios.org is deliberate. If an operator withdraws its service, that is a DNS change rather than a new image for every machine.

Two circles, and how they are broken #

Both are worth knowing about, because both look like bugs when you meet them.

NTS needs TLS; TLS needs a clock. A machine whose battery has died boots reading 1970, and every certificate it holds is "not yet valid", so it cannot complete the handshake that would tell it the real time. timed breaks this by refusing to let the clock sit below its own build timestamp — every certificate in the shipped trust store was valid at that moment, by construction. The clock is wrong, but it is wrong in a way that TLS tolerates, and the first poll fixes it. clock status reports the floor so that "my clock is being clamped" is visible rather than mysterious.

A fresh handshake needs a clock too. So the cookies from the last one are kept under /var/state/timed, and a reboot usually needs no handshake at all.

Steering, not jumping #

Once the time is known, timed slews the clock: it changes the rate slightly so the error is absorbed over the next few minutes. A great deal of software quietly assumes the clock only goes forwards, and stepping it backwards breaks timers, file timestamps and anything measuring a duration.

The clock is stepped in exactly two situations:

• at startup, once, however large the correction — this is what lets a machine with a dead battery start correctly;
• after fifteen minutes of consistent disagreement, when the offset is too large to slew away. Fifteen minutes because a congested network or a server having a moment looks exactly like a genuine step until time passes, and stepping the clock on a transient is worse than being slow to correct a real one.

An offset larger than a thousand seconds appearing after the machine was synchronised is refused outright and logged loudly. A machine that far out has a problem a time client should not paper over.

Learning the crystal #

The clock is a crystal running at the wrong rate — consistently wrong, by some tens of parts per million. timed learns that rate and writes it to /var/state/timed/drift, so the next boot starts already correcting for it and is within milliseconds after one poll rather than after twenty.

It is also what holds the clock right when the network goes away: a machine that knows its crystal is 12 ppm fast stays within a second for about a day on its own.

What timed does not do #

It is not a time server. It listens on no network port and initiates every conversation it takes part in. Serving time to other machines will be a separate, unprivileged package — the client holds the dangerous privilege, and a server is exposed to the whole network and needs no privilege at all. Keeping them apart is the point.

It does not touch the hardware clock directly. Once timed reports the clock as synchronised, the kernel writes it back to the RTC every eleven minutes on its own.

Everything about where a machine gets its time is under Machine\System\Time. There is no configuration file, and clock writes nothing — reg is how it is changed, so the key's own security descriptor is the only gate.

Naming your own servers #

$ reg set Machine/System/Time Servers multi:'dc01.corp.example' \
                                            'dc02.corp.example' \
                                            'ntp3.corp.example'
$ clock reload

Each entry is a host, optionally host:port, optionally followed by option words:

prefer breaks ties and nothing more. A preferred source that disagrees with the majority is still discarded — a preference is a statement about which server to lean on, not a licence to be wrong.

A misspelled option is an error and the entry is ignored with a warning in the log, rather than silently doing nothing. clock sources will show the entry missing.

Precedence is first match, not merge #

Servers  →  the domain  →  DHCP, if enabled  →  the shipped fallback set

The first of those that names anything is the whole list. Setting Servers does not add to the fallback set, it replaces it — a machine told exactly which servers to use should not also be quietly talking to somebody else's.

To go back to the shipped default, delete the value:

$ reg del Machine/System/Time Servers
$ clock reload

Turning authentication off #

AllowUnauthenticated is 0 by default: a source must prove who it is or it is not used.

$ reg set Machine/System/Time AllowUnauthenticated dword:1
$ reg set Machine/System/Time Servers multi:'ntp.lan unauthenticated'
$ clock reload

Both are needed. The per-source word says which sources are plain, and the machine-wide value says whether that is permitted at all — so setting AllowUnauthenticated back to 0 really does turn everything off, rather than leaving per-source exceptions behind.

What you give up is worth being clear about. Without NTS, the only thing standing between you and a forged reply is that the server must echo the exact 64 bits timed put in its request — a random number, so an attacker who cannot see the request cannot guess it. An attacker who can see it can forge freely and move your clock wherever they like.

The reason to think twice is that a wrong clock is not a self-contained problem: certificate validity, Kerberos, and the ordering of your logs all rest on it.

Reasonable uses: an isolated network with its own stratum-1 appliance; a lab; a machine behind a firewall that blocks port 4460 where you control the path anyway.

DHCP time servers #

UseFromDHCP is 0 by default, as on Windows.

$ reg set Machine/System/Time UseFromDHCP dword:1

They are used only when Servers is absent, and only without authentication. Off by default because on a network you do not control the DHCP server's idea of the time is the attacker's idea of the time — and turning this on is a statement that you trust every network this machine will ever join. That is a reasonable statement for a machine that only ever attaches to one you run.

Poll intervals #

MinPoll   default 6    64 seconds
MaxPoll   default 10   about 17 minutes

Both are powers of two seconds, and both are clamped to the range 4 to 17. timed lengthens the interval towards MaxPoll while the clock is being held steadily and shortens it when the offset starts moving.

There is rarely a reason to change either. Lowering MinPoll makes recovery from a disturbance faster and costs the servers more traffic; a long interval measures the crystal's rate better than a short one measures its phase, and it is the rate estimate that holds the clock right between polls anyway.

The floor of 4 is not negotiable. A configuration error must not be able to turn a machine into a nuisance at somebody else's public server.

Doing it from a domain #

Every value here is an ordinary registry write, so distributing time policy to a fleet is an ordinary policy push. There is no separate mechanism and nothing timed-specific to learn.

When something is wrong #

$ clock sources
  source                   state        auth   str reach     offset     delay     last
* 0.time.peios.org         system-peer  nts      3   377   -1.204ms   14.2ms       31s
+ 1.time.peios.org         candidate    nts      2   377   -0.918ms   22.7ms       44s
x 2.time.peios.org         falseticker  nts      2   377   +4.102s    18.1ms       12s
  3.time.peios.org         unreachable  nts     16     0       +0ns       0ns         -
    NTS-KE failed: connecting to 192.0.2.9:4460: Connection refused

• falseticker — this server disagrees with the others. It is the one to go and look at, and the single most useful thing a time client can tell you.
• unreachable — no reply for eight polls. The note says why.
• reach is the last eight polls in octal: 377 is eight for eight, and anything else says how recently one was missed.

clock reads over timed's socket and prints. It writes nothing — time policy is registry configuration, and reg is how a registry value is set, so there is no second permission model to keep in step with the first. The one verb that acts is reload.

It is called clock and not time because time is a shell keyword: time status would run status and report how long it took.

Verbs #

status is the default, so bare clock is clock status.

Status #

$ clock status
generation   118
state        synchronised
following    1.time.peios.org (stratum 3)
offset       -412.0us
frequency    -12.750 ppm
jitter       +180.3us
accuracy     within 31.4ms
  root delay      28.2ms
  root dispersion 4.10ms
sources      4 configured, 3 contributing
updates      118 (last 22s ago)
stepped      +2.1d in total since start
floor        1788142329 (the build timestamp; the clock is never set below it)

state is the field to read first:

accuracy is the honest bound: how wrong this machine's time might be, with every uncertainty between here and the reference clock added up. It is the number a Kerberos deployment cares about, and the number to check before blaming a clock skew on something else.

frequency is what the crystal is doing, in parts per million, and it is persistent — it is written to /var/state/timed/drift and read back at the next boot. Tens of ppm is an ordinary machine. Approaching ±500 means the hardware is at the edge of what the discipline can correct.

stepped is non-zero after a boot on a machine whose clock was wrong, which is normal. It growing later is not, and means something is repeatedly moving the clock.

floor is the build timestamp. If the machine's clock reads exactly this, nothing has told it the real time yet and it is sitting on the floor so that TLS can work — see the overview.

Sources #

$ clock sources
  source                   state        auth   str reach     offset     delay     last
* 1.time.peios.org         system-peer  nts      2   377   -0.918ms   22.7ms       44s
+ 0.time.peios.org         candidate    nts      3   377   -1.204ms   14.2ms       31s
- 3.time.peios.org         outlier      nts      2   377   +8.221ms   61.0ms       58s
x 2.time.peios.org         falseticker  nts      2   377   +4.102s    18.1ms       12s

* system peer  + candidate  - outlier  x falseticker  ? unusable

auth is nts or none. none means anyone on the path can forge that source's replies.

reach is the last eight polls as an octal bitmask, newest in the low bit — the classic NTP display. 377 is eight for eight; 376 means the poll before last was missed; 0 means nothing for eight polls, at which point the source's stored measurements are discarded rather than left to vote with stale numbers.

last is how long ago the source answered. It exceeding the poll interval by much is the first sign of trouble.

A source that is not contributing prints a note underneath saying why.

Exit statuses #

The separation of 2 from 1 is what lets a script tell "this machine has no time sources" from "I could not find out".

When reload is refused #

$ clock reload
clock: not permitted

reload needs the control right on timed's control object. Reading does not: what time the machine thinks it is, and how well it knows, is not a secret, and a program deciding whether the clock is trustworthy enough to validate a certificate should not need a privilege to find out.

The descriptor is Machine\System\Time ControlSecurity; by default SYSTEM and Administrators may control, and everybody may query.