Copyright © 2019 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
This specification defines an API that provides the time origin, and current time in sub-millisecond resolution, such that it is not subject to system clock skew or adjustments.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
High Resolution Time Level 2 replaces the first version of High Resolution Time and includes:
performance.timeOrigin
attribute
that
provides
the
global
time
of
the
zero
time
of
time
origin
;
Performance
interface,
previously
specified
in
[
PERFORMANCE-TIMELINE
],
is
now
moved
to
this
specification
and
now
includes
support
for
the
Performance.now
method
in
Web
Workers
[
WORKERS
];
This document was published by the Web Performance Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 March 2019 W3C Process Document .
This section is non-normative.
The
ECMAScript
Language
specification
[
ECMA-262
]
defines
the
Date
object
as
a
time
value
representing
time
in
milliseconds
since
01
January,
1970
UTC.
For
most
purposes,
this
definition
of
time
is
sufficient
as
these
values
represent
time
to
millisecond
precision
for
any
instant
that
is
within
approximately
285,616
years
from
01
January,
1970
UTC.
The
DOMTimeStamp
is
defined
similarly
[
WEBIDL
].
In practice, these definitions of time are subject to both clock skew and adjustment of the system clock. The value of time may not always be monotonically increasing and subsequent values may either decrease or remain the same.
For
example,
the
following
script
may
record
a
positive
number,
negative
number,
or
zero
for
computed
duration
:
var mark_start = Date.now();
doTask(); // Some task
var
duration
=
Date
.now()
-
mark_start;
For certain tasks this definition of time may not be sufficient as it does not allow for sub-millisecond resolution and is subject to system clock skew. For example,
Worker
or
SharedWorker
workers
to
drive
animation,
audio,
etc.,
in
a
renderer
context),
or
to
create
a
unified
view
of
the
event
timeline.
This
specification
does
not
propose
changing
the
behavior
of
This
section
is
non-normative.
A
developer
may
wish
to
construct
a
timeline
of
their
entire
application,
including
events
from
Date.now()
[
ECMA-262
]
as
it
is
genuinely
useful
in
determining
the
current
value
of
the
calendar
time
and
has
a
long
history
of
usage.
The
DOMHighResTimeStamp
type,
performance.now
method,
and
performance.timeOrigin
attributes
of
the
Performance
interface
resolve
above
issues
by
providing
monotonically
increasing
time
values
with
sub-millisecond
resolution.
1.1
Examples
Worker
or
SharedWorker
,
which
have
different
time
origin
's.
To
display
such
events
on
the
same
timeline,
the
application
can
translate
the
DOMHighResTimeStamp
's
with
the
help
of
the
performance.timeOrigin
attribute.
// ---- worker.js -----------------------------
// Shared worker script
onconnect = function(e) {
var port = e.ports[0];
port.onmessage = function(e) {
// Time execution in worker
var task_start = performance.now();
result = runSomeWorkerTask();
var task_end = performance.now();
}
// Send results and epoch-relative timestamps to another context
port.postMessage({
'task': 'Some worker task',
'start_time': task_start + performance.timeOrigin,
'end_time': task_end + performance.timeOrigin,
'result': result
});
}
// ---- application.js ------------------------
// Timing tasks in the document
var task_start = performance.now();
runSomeApplicationTask();
var task_end = performance.now();
// developer provided method to upload runtime performance data
reportEventToAnalytics({
'task': 'Some document task',
'start_time': task_start,
'duration': task_end - task_start
});
// Translating worker timestamps into document's time origin
var worker = new SharedWorker('worker.js');
worker.port.onmessage = function (event) {
var msg = event.data;
// translate epoch-relative timestamps into document's time origin
msg.start_time = msg.start_time - performance.timeOrigin;
msg.end_time = msg.end_time - performance.timeOrigin;
reportEventToAnalytics(msg);
}
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST and SHOULD in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
The time origin is the time value from which time is measured:
Window
object,
the
time
origin
MUST
be
equal
to:
Window
object's
newest
Document
object
.
WorkerGlobalScope
object,
the
time
origin
MUST
be
equal
to
the
official
moment
of
creation
of
the
worker.
The time origin timestamp is the high resolution time value at which time origin is zero. To obtain the time origin timestamp given a global object ( global ):
DOMHighResTimeStamp
representing
the
high
resolution
time
at
which
the
global
monotonic
clock
is
zero.
DOMHighResTimeStamp
representing
the
high
resolution
time
value
of
the
global
monotonic
clock
at
global
's
time
origin
.
The
time
origin
timestamp
and
the
value
returned
by
Date.now()
executed
at
"zero
time"
can
differ
because
the
former
is
recorded
with
respect
to
a
global
monotonic
clock
that
is
not
subject
to
system
and
user
clock
adjustments,
clock
skew,
and
so
on—see
§
7.
Monotonic
Clock
.
The current high resolution time is the high resolution time from the time origin to the present time (typically called "now").
DOMHighResTimeStamp
Type
The
DOMHighResTimeStamp
type
is
used
to
store
a
time
value
in
milliseconds,
measured
relative
from
the
time
origin
,
global
monotonic
clock
,
or
a
time
value
that
represents
a
duration
between
two
DOMHighResTimeStamp
's.
typedef
double
DOMHighResTimeStamp
;
A
DOMHighResTimeStamp
SHOULD
represent
a
time
in
milliseconds
accurate
enough
to
allow
measurement
while
preventing
timing
attack
-
see
§
8.1
Clock
resolution
for
additional
considerations.
If
the
User
Agent
is
unable
to
provide
a
time
value
accurate
to
5
microseconds
due
to
hardware
or
software
constraints,
the
User
Agent
can
represent
a
DOMHighResTimeStamp
as
a
time
in
milliseconds accurate to a millisecond.
Performance interface[Exposed=(Window,Worker)]
interface Performance : EventTarget {
DOMHighResTimeStamp now ();
readonly attribute DOMHighResTimeStamp timeOrigin;
[Default] object toJSON();
};
The
now()
method
MUST
return
the
current
high
resolution
time
.
The
timeOrigin
attribute
MUST
return
a
DOMHighResTimeStamp
representing
the
high
resolution
time
of
the
time
origin
timestamp
for
the
relevant
global
object
of
the
Performance
object.
When
toJSON
is
called,
run
[
WEBIDL
]'s
default
toJSON
operation
.
performance
attribute
The
performance
attribute
on
the
WindowOrWorkerGlobalScope
allows
access
to
performance
related
attributes
and
methods
from
the
global object.
partial interface mixin WindowOrWorkerGlobalScope {
[Replaceable] readonly attribute Performance performance;
};
The
time
values
returned
when
calling
the
method
on
performance.now()
Performance
objects
with
the
same
time
origin
MUST
use
the
same
monotonic
clock
that
is
monotonically
increasing
and
not
subject
to
system
clock
adjustments
or
system
clock
skew.
The
difference
between
any
two
chronologically
recorded
time
values
returned
from
the
method
MUST
never
be
negative
if
the
two
time
values
have
the
same
time
origin
.
performance.now()
The
time
values
returned
when
getting
MUST
use
the
same
global
monotonic
clock
that
is
shared
by
time
origin
's,
is
monotonically
increasing
and
not
subject
to
system
clock
adjustments
or
system
clock
skew,
and
whose
reference
point
is
the
[
ECMA-262
]
time
definition
-
see
§
8.
Privacy
and
Security
.
performance.timeOrigin
The
user
agent
can
reset
its
global
monotonic
clock
across
browser
restarts,
or
whenever
starting
an
isolated
browsing
session—e.g.
incognito
or
similar
browsing
mode.
As
a
result,
developers
should
not
use
global
timestamps
as
absolute
time
that
holds
its
monotonic
properties
across
all
past,
present,
and
future
contexts;
in
practice,
the
monotonic
properties
only
apply
for
contexts
that
can
reach
other
by
exchanging
messages
via
one
of
the
provided
messaging
mechanisms
-
e.g.
postMessage
,
BroadcastChannel
,
etc.
In certain scenarios (e.g. when a tab is backgrounded), the user agent may choose to throttle timers and periodic callbacks run in that context or even freeze them entirely. Any such throttling should not affect the resolution or accuracy of the time returned by the monotonic clock.
Access to accurate timing information, both for measurement and scheduling purposes, is a common requirement for many applications. For example, coordinating animations, sound, and other activity on the page requires access to high-resolution time to provide a good user experience. Similarly, measurement enables developers to track the performance of critical code components, detect regressions, and so on.
However, access to the same accurate timing information can sometimes be also used for malicious purposes by an attacker to guess and infer data that they can't see or access otherwise. For example, cache attacks, statistical fingerprinting and microarchitectural attacks are a privacy and security concern where a malicious web site may use high resolution timing data of various browser or application-initiated operations to differentiate between subset of users, identify a particular user or reveal unrelated but same-process user data - see [ CACHE-ATTACKS ] and [ SPECTRE ] for more background.
This
specification
defines
an
API
that
provides
sub-millisecond
time
resolution,
which
is
more
accurate
than
the
previously
available
millisecond
resolution
exposed
by
DOMTimeStamp
.
However,
even
without
this
new
API
an
attacker
may
be
able
to
obtain
high-resolution
estimates
through
repeat
execution
and
statistical
analysis.
To
ensure
that
the
new
API
does
not
significantly
improve
the
accuracy
or
speed
of
such
attacks,
the
recommended
minimum
resolution
of
the
DOMHighResTimeStamp
type
should
be
inaccurate
enough
to
prevent
attacks.
In order to mitigate such attacks user agents may deploy any technique they deem necessary. Deployment of those techniques may vary based on the browser's architecture, the user's device, the content and its ability to maliciousely read cross-origin data, or other practical considerations.
These techniques may include:
Mitigating such timing side-channel attacks entirely is practically not possible: either all operations would have to execute in a time that does not vary based on the value of any confidential information, or, the application would need to be isolated from any time-related primitives (clock, timers, counters, etc). Neither is practical due to the associated complexity for the browser and application developers and the associated negative effects on performance and responsiveness of applications.
This specification also defines an API that provides sub-millisecond time resolution of the zero time of the time origin, which requires and exposes a global monotonic clock to the application, and that must be shared across all the browser contexts. The global monotonic clock does not need to be tied to physical time, but is recommended to be set with respect to the [ ECMA-262 ] definition of time to avoid exposing new fingerprint entropy about the user — e.g. this time can already be easily obtained by the application, whereas exposing a new logical clock provides new information.
However,
even
with
above
mechanism
in
place,
the
global
monotonic
clock
may
provide
additional
clock
drift
resolution.
Today,
the
application
can
timestamp
the
time-of-day
and
monotonic
time
values
(via
Date.now()
and
)
at
multiple
points
within
the
same
context
and
observe
drift
between
them—e.g.
due
to
automatic
or
user
clock
adjustments.
With
the
performance.now()
performance.timeOrigin
attribute,
the
attacker
can
also
compare
the
time
at
which
time
origin
is
zero,
as
reported
by
the
global
monotonic
clock
,
against
the
current
time-of-day
estimate
of
when
it
is
zero
(i.e.
difference
between
Date.now()-performance.now()
and
performance.timeOrigin
)
and
potentially
observe
clock
drift
between
these
clocks
over
a
longer
time
period.
In practice, the same time drift can be observed by an application across multiple navigations: the application can record logical time in each context and use a client or server time synchronization mechanism to infer changes in the user's clock. Similarly, lower-layer mechanisms such as TCP timestamps may reveal same high-resolution information to the server without the need for multiple visits. As such, the information provided by this API should not expose any significant or previously not available entropy about the user.
The
[
HTML
]
specification
defines
the
following:
global
object
,
Worker
interface,
SharedWorker
interface,
official
moment
of
creation
,
WorkerGlobalScope
interface,
relevant
global
object
.
The
[
WEBIDL
]
specification
defines
the
following:
DOMTimeStamp
interface.
Thanks to Arvind Jain, Angelos D. Keromytis, Boris Zbarsky, Jason Weber, Karen Anderson, Nat Duca, Philippe Le Hegaret, Ryosuke Niwa, Simha Sethumadhavan, Todd Reifsteck, Tony Gentilcore, Vasileios P. Kemerlis, Yoav Weiss, and Yossef Oren for their contributions to this work.