roughly

An asynchronous implemenation of the Roughtime protocol for Python.

Implements the Roughtime protocol as described in https://datatracker.ietf.org/doc/html/draft-ietf-ntp-roughtime-19.

Draft versions 07 through 19 are supported for querying servers.
Draft versions 10 through 19 are supported for running a server. Also supports queries from Google Roughtime clients.

Quickstart

Installation

You can install roughly from PyPI using your favorite package manager, for example with pip:

pip install roughly
# or with the cli extra
pip install roughly[cli]

As a CLI

Querying

You can use roughly as a command line tool to query Roughtime servers. Install roughly with the cli extra using your favorite CLI package manager, for example with uv (or pipx):

uv tool install roughly[cli]
pipx install roughly[cli]

Then you can query a Roughtime server like so:

roughly query time.teax.dev 2002 84pMADvKUcSOq5RNbVRjVrjiU16Dxo2XV2Qkm+4DRTg=

Or run ecosystem queries (assuming you have an ecosystem.json file):

roughly ecosystem malfeasance
roughly ecosystem state

Running a server

You can also run your own Roughtime server using roughly.

First, generate a keypair:

roughly server keygen

This will output a .env file containing the server's private key.

You can then run the server like so:

ROUGHLY_PRIVATE_KEY="your_private_key_here" roughly -v server run

By default, the server will bind to 0.0.0.0:2002. You can change this using the --host and --port flags. I recommend running the server with verbose logging enabled (-v), so you can see incoming requests and debug any issues. Additionally you might want to consider turning off response greasing while testing using the --no-grease flag.

Every server run option can also be set through an environment variable, named after the flag with a ROUGHLY_ prefix. Check roughly server run --help for more information.

As a library

Querying

roughly can be used as an asynchronous library to query Roughtime servers from your own Python code.

importroughly.client# <snip!>response=awaitroughly.client.send_request(
host="time.teax.dev",
port=2002,
public_key=base64.b64decode(b"84pMADvKUcSOq5RNbVRjVrjiU16Dxo2XV2Qkm+4DRTg="),
)
midpoint=response.signed_response.midpointradius=response.signed_response.radiusprint(f"time: {midpoint} ± {radius}s")

send_request verifies the response before returning. Any failure raises roughly.errors.VerificationError; malformed packets raise PacketError. Both inherit from RoughtimeError. Once you have a response, true time is somewhere in the range [midpoint - radius, midpoint + radius].

An ecosystem is a list of servers a client can query. roughly.ecosystem provides a flow for querying them and checking for disagreement:

frompathlibimportPathimportjsonfromroughly.ecosystemimport (
confirm_malfeasance,
load_ecosystem,
malfeasance_report,
pick_servers,
query_servers,
)
ecosystem=load_ecosystem(Path("ecosystem.json"))
selected_servers=awaitpick_servers(ecosystem)
responses=awaitquery_servers(selected_servers)
report=malfeasance_report(responses, selected_servers)
ifconfirm_malfeasance(report):
print("something scary is going on!")
withopen("malfeasance_report.json", "w") asf:
json.dump(report, f, indent=2)

pick_servers filters down to servers that are actually reachable right now. query_servers returns one (VerifiableResponse, raw_bytes) per server. confirm_malfeasance returns true when the responses can't all be true at the same time.

Running a server

You can also programmatically run your own Roughtime server. Server.create() mints a long-term ed25519 keypair on each call, so for any server clients should be able to keep talking to across restarts, pass private_key=... with a key you've persisted yourself:

importroughly.serverserver=roughly.server.Server.create() # generates a fresh keypairawaitroughly.server.serve(server)

The reason to use the library directly instead of the CLI is that both roughly.server.Server and roughly.server.UDPHandler are designed to be extended. A sample use case is a deliberately malfeasant server:

importroughlyimportroughly.serverclassScaryServer(roughly.server.Server):
@staticmethoddefget_time() ->int:
# return a wrong-ish timereturnint(time.time()) +random.randint(-3600, 3600)
awaitroughly.server.serve(ScaryServer.create())

Ecosystem

An example ecosystem file can be found at ecosystem.json, I tried my best to include as many servers as I could find.

If you know of any other Roughtime servers, run your own server, or have updated public keys for any of the listed servers, please open a PR or an issue!

Interoperability

The interopability matrix of roughly against Roughtime servers looks like this:

Roughly as a client

Server	Result
butterfield	✅
cloudflare	✅
pyroughtime	✅
roughenough	✅
roughtimed	✅
roughly	✅
tannerryan-roughtime	✅

Roughly as a server

Client	Result
cloudflare	✅
craggy	✅
node-roughtime	✅
pyroughtime	✅
roughenough	✅
roughly	✅
tannerryan-roughtime	✅
vroughtime	✅

draft-7

Support for draft-7 is limited, in the sense that roughly will fit responses from draft-7 servers into the draft-15 data structures. This means that some fields that are not present in draft-8+ (such as DUT1, DTAI, and LEAP) will be missing. Additionally draft-7 offered for the precision of radius to be in microseconds, while draft-8+ uses seconds, this precision will be lost when querying draft-7 servers, and be clamped to a minimum of one second.

License

This project is licensed under the MIT License. See the LICENSE file for details.