roughly 0.1.0__py3-none-any.whl

roughly/__init__.py

@@ -0,0 +1 @@
+"""Roughtime protocol implementation in Python."""

roughly/cli.py

@@ -0,0 +1,336 @@
+import asyncio
+import base64
+import json
+import logging
+import time
+import traceback
+from pathlib import Path
+from typing import Any, cast
+
+import click
+
+import roughly.client
+import roughly.ecosystem
+import roughly.errors
+import roughly.server
+
+# ruff: noqa: FBT001 FBT002 PLR0913
+
+REASON_EXPLANATIONS: dict[roughly.errors.RoughtimeErrorReason, str] = {
+    "key-age": "The delegated signing key isn't valid at the current time.",
+    "merkle": (
+        "The server signed timestamps for multiple requests at once."
+        " This response could not be proven to be part of the signed batch."
+    ),
+    "signature-response": "The server's response signature could not be verified.",
+    "signature-certificate": "The server's delegation certificate signature could not be verified.",
+}
+
+
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Enable logging",
+)
+@click.group()
+def cli(verbose: bool) -> None:
+    """roughly: A Roughtime client."""
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+async def _query(
+    host: str, port: int, public_key: bytes, *, timeout: float
+) -> roughly.client.VerifiableResponse:
+    async with asyncio.timeout(timeout):
+        return await roughly.client.send_request(host, port, public_key)
+
+
+async def _very_dangerously_query(
+    host: str, port: int, public_key: bytes | None, *, timeout: float
+) -> roughly.client.VerifiableResponse:
+    async with asyncio.timeout(timeout):
+        return await roughly.client.very_dangerously_send_request_and_do_not_verify(
+            host,
+            port,
+            public_key,
+        )
+
+
+@cli.command()
+@click.argument("host")
+@click.argument("port", type=int, default=2002)
+@click.argument("public-key", required=False)
+@click.option("--terse", is_flag=True, help="Only output the time")
+@click.option("--timeout", type=float, default=5.0, help="Request timeout in seconds")
+@click.option(
+    "--very-dangerously-disable-verification",
+    is_flag=True,
+    help="Disable response verification. Only use this if you ABSOLUTELY know what you're doing!",
+)
+def query(
+    host: str,
+    port: int,
+    public_key: str | None,
+    terse: bool,
+    timeout: float,
+    very_dangerously_disable_verification: bool,
+) -> None:
+    """Query a Roughtime server for the current time."""
+    query_function = _query
+    if very_dangerously_disable_verification:
+        query_function = _very_dangerously_query
+    elif public_key is None:
+        click.echo(
+            "Public key is required unless --very-dangerously-disable-verification is set",
+            err=True,
+        )
+        return
+
+    try:
+        # The cast here is needed, but safe, because of the check above.
+        key_bytes = None
+        if public_key is not None:
+            key_bytes = base64.b64decode(public_key)
+        response = asyncio.run(query_function(host, port, cast(Any, key_bytes), timeout=timeout))
+    except TimeoutError:
+        click.echo("Request timed out", err=True)
+        return
+    except roughly.errors.VerificationError as e:
+        traceback.print_exc()
+        click.echo()
+        click.echo("Response received but rejected during verification", err=True)
+        explanation = REASON_EXPLANATIONS.get(e.reason)
+        if explanation:
+            click.echo(f"{e.reason}: {explanation}", err=True)
+        else:
+            click.echo(f"Reason: {e.reason}", err=True)
+        return
+    except roughly.errors.RoughtimeError:
+        traceback.print_exc()
+        click.echo()
+        click.echo("A Roughtime protocol error occured while querying the server", err=True)
+        click.echo("If you believe this is a bug, please file an issue", err=True)
+        return
+
+    unix_time = response.signed_response.midpoint
+    radius = response.signed_response.radius
+    if terse:
+        click.echo(unix_time)
+    else:
+        click.echo(f"Current time: {unix_time} ± {radius} seconds")
+
+
+@cli.group()
+def ecosystem() -> None:
+    """Commands for working with Roughtime ecosystems."""
+
+
+async def _ecosystem_state(ecosystem_path: Path) -> None:
+    ecosystem = roughly.ecosystem.load_ecosystem(ecosystem_path)
+    selected_servers = await roughly.ecosystem.pick_servers(ecosystem)
+
+    click.echo(
+        f"Out of {len(ecosystem)} servers, {len(selected_servers)} yielded proper responses."
+    )
+    failed_to_select = {server.name for server in ecosystem} - {
+        server.name for server in selected_servers
+    }
+
+    if failed_to_select:
+        click.echo("Failed to select the following servers:")
+        for server in failed_to_select:
+            click.echo(f"- {server}")
+
+    click.echo("\nAvailable servers:")
+    for server in selected_servers:
+        click.echo(f"- {server.name} ({server.version:#x})")
+
+    tasks: list[
+        asyncio.Task[tuple[roughly.ecosystem.Server, roughly.client.VerifiableResponse | None]]
+    ] = []
+
+    for server in selected_servers:
+        task = asyncio.create_task(
+            roughly.ecosystem._query_server(  # pyright: ignore[reportPrivateUsage]
+                server,
+                timeout=1.0,
+            )
+        )
+        tasks.append(task)
+
+    results = await asyncio.gather(*tasks)
+
+    current_time = time.time()
+    click.echo(f"\nAt {current_time:.0f} (machine time) received responses from:")
+    for server, response in results:
+        if response is not None:
+            server_time = response.signed_response.midpoint
+            radius = response.signed_response.radius
+            click.echo(f"- {server.name}: time={server_time} ± {radius} seconds")
+
+
+@ecosystem.command()
+@click.argument(
+    "ecosystem-path",
+    type=click.Path(exists=True, path_type=Path),
+    default=Path("ecosystem.json"),
+)
+def state(ecosystem_path: Path) -> None:
+    """Evaluate the state of a Roughtime ecosystem."""
+    asyncio.run(_ecosystem_state(ecosystem_path))
+
+
+async def _malfeasance_test(
+    ecosystem_path: Path,
+    always_write: bool = False,
+    report_location: Path | None = None,
+) -> None:
+    report_location = report_location or Path("malfeasance_report.json")
+    ecosystem = roughly.ecosystem.load_ecosystem(ecosystem_path)
+    selected_servers = await roughly.ecosystem.pick_servers(ecosystem)
+    click.echo("Selected servers for malfeasance testing:")
+    for server in selected_servers:
+        click.echo(f"- {server.name}")
+    responses = await roughly.ecosystem.query_servers(selected_servers)
+    report = roughly.ecosystem.malfeasance_report(responses, selected_servers)
+
+    if had_malfeasance := roughly.ecosystem.confirm_malfeasance(report):
+        click.echo(f"Malfeasance detected. Writing report to '{report_location}'.")
+        with report_location.open("w", encoding="utf-8") as f:
+            json.dump(report, f, indent=2)
+    else:
+        click.echo("No malfeasance detected.")
+
+    if not had_malfeasance and always_write:
+        with report_location.open("w", encoding="utf-8") as f:
+            json.dump(report, f, indent=2)
+        click.echo(f"Report saved to '{report_location}' (no malfeasance detected).")
+
+
+@ecosystem.command()
+@click.option(
+    "--always-write",
+    is_flag=True,
+    help="Always write a malfeasance report, even if no malfeasance is detected",
+)
+@click.option(
+    "--report-location",
+    type=click.Path(path_type=Path),
+    help="Location to save the malfeasance report",
+)
+@click.option(
+    "--ecosystem-path",
+    type=click.Path(exists=True, path_type=Path),
+    default=Path("ecosystem.json"),
+    help="Path to the ecosystem JSON file",
+)
+def malfeasance(always_write: bool, report_location: Path | None, ecosystem_path: Path) -> None:
+    """Run a malfeasance test on the Roughtime ecosystem."""
+    asyncio.run(
+        _malfeasance_test(
+            always_write=always_write,
+            report_location=report_location,
+            ecosystem_path=ecosystem_path,
+        )
+    )
+
+
+@cli.group()
+def server() -> None:
+    """Commands for running a Roughtime server."""
+
+
+@server.command(name="run")
+@click.option("--host", default="0.0.0.0", help="Host to bind to")  # noqa: S104
+@click.option("--port", "-p", default=2002, type=int, help="Port to bind to")
+@click.option(
+    "--private-key",
+    type=str,
+    help="Base64-encoded 32-byte Ed25519 private key. If not provided, generates a new key.",
+    envvar="ROUGHLY_PRIVATE_KEY",
+)
+@click.option(
+    "--radius",
+    default=3,
+    type=int,
+    help="Uncertainty radius in seconds",
+)
+@click.option(
+    "--validity-seconds",
+    default=None,
+    type=int,
+    help="Validity period for the delegated key in seconds. "
+    "If not set, defaults to 3600 seconds (1 hour).",
+)
+@click.option(
+    "--no-grease",
+    is_flag=True,
+    help="Disable response greasing",
+    envvar="ROUGHLY_NO_GREASE",
+)
+@click.option(
+    "--grease-probability",
+    default=None,
+    type=float,
+    help="Probability of greasing responses (between 0.0 and 1.0). "
+    f"If not set, defaults to {roughly.server.GREASE_PROBABILITY} "
+    f"({roughly.server.GREASE_PROBABILITY * 100:.2f}%).",
+    envvar="ROUGHLY_GREASE_PROBABILITY",
+)
+def server_run(
+    host: str,
+    port: int,
+    private_key: str | None,
+    radius: int,
+    validity_seconds: int | None,
+    no_grease: bool,
+    grease_probability: float | None,
+) -> None:
+    """Run a Roughtime server."""
+    key_bytes = base64.b64decode(private_key) if private_key else None
+
+    config = roughly.server.Server.create(
+        key_bytes,
+        validity_seconds=validity_seconds,
+        radius=radius,
+        grease=not no_grease,
+        grease_probability=grease_probability,
+    )
+
+    pub_bytes = roughly.server.public_key_bytes(config.long_term_key)
+    public_key_b64 = base64.b64encode(pub_bytes).decode()
+    click.echo(f"Server public key (base64): {public_key_b64}")
+    click.echo(f"Starting Roughtime server on {host}:{port}")
+
+    try:
+        asyncio.run(roughly.server.serve(config, host, port))
+    except KeyboardInterrupt:
+        click.echo("\nServer stopped.")
+
+
+@server.command(name="keygen")
+def server_keygen() -> None:
+    """Generate a new Ed25519 key pair for the server."""
+    key = roughly.server.generate_key()
+    private_key_bytes = key.private_bytes_raw()
+    pub_key_bytes = roughly.server.public_key_bytes(key)
+    output_data = f"ROUGHLY_PRIVATE_KEY={base64.b64encode(private_key_bytes).decode()}"
+
+    path = Path(".env")
+    if path.exists() and not click.confirm(
+        "'.env' file already exists. Overwrite?", default=False, show_default=True
+    ):
+        click.echo("Aborting key generation.")
+        return
+
+    with path.open("w", encoding="utf-8") as f:
+        f.write(output_data + "\n")
+
+    click.echo(f"Public key (base64): {base64.b64encode(pub_key_bytes).decode()}")
+    click.echo(f"Private key saved to '{path}'. Keep it secret!")
+
+
+if __name__ == "__main__":
+    cli()

roughly/client.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import struct
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar
+
+import cryptography.exceptions
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from roughly import tags
+from roughly.errors import PacketError, RoughtimeError, VerificationError
+from roughly.models import (
+    Message,
+    Packet,
+    Response,
+    Tag,
+)
+from roughly.shared import (
+    GOOGLE_ROUGHTIME_SENTINEL,
+    RESPONSE_CONTEXT_STRING,
+    VERSIONS_SUPPORTED,
+    ProtocolProfile,
+    find_by_predicate,
+    partial_sha512,
+    pop_by_tag,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+T = TypeVar("T")
+
+
+logger = logging.getLogger(__name__)
+
+
+class QueueDatagramProtocol(asyncio.DatagramProtocol):
+    def __init__(self) -> None:
+        self.transport: asyncio.DatagramTransport | None = None
+        self.queue: asyncio.Queue[tuple[bytes, tuple[str, int]] | Exception] = asyncio.Queue()
+
+    def connection_made(self, transport: asyncio.DatagramTransport) -> None:
+        self.transport = transport
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        self.queue.put_nowait((data, addr))
+
+    def error_received(self, exc: Exception) -> None:
+        self.queue.put_nowait(exc)
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        if exc:
+            self.queue.put_nowait(exc)
+        self.queue.put_nowait(RoughtimeError("Connection closed unexpectedly"))
+
+    async def recv(self) -> bytes:
+        item = await self.queue.get()
+        if isinstance(item, Exception):
+            raise item
+        return item[0]
+
+
+async def open_udp_socket(host: str, port: int):  # noqa: ANN201
+    loop = asyncio.get_running_loop()
+    transport, protocol = await loop.create_datagram_endpoint(
+        QueueDatagramProtocol,
+        remote_addr=(host, port),
+    )
+    return transport, protocol
+
+
+async def send_request(
+    host: str,
+    port: int,
+    public_key: bytes,
+    *,
+    versions: Iterable[int] | None = None,
+    nonce: bytes | None = None,
+) -> VerifiableResponse:
+    response = await very_dangerously_send_request_and_do_not_verify(
+        host,
+        port,
+        public_key,
+        versions=versions,
+        nonce=nonce,
+    )
+    response.verify(public_key)
+    logger.debug("Verified response from %s:%d", host, port)
+    return response
+
+
+async def very_dangerously_send_request_and_do_not_verify(
+    host: str,
+    port: int,
+    public_key: bytes | None = None,
+    *,
+    versions: Iterable[int] | None = None,
+    nonce: bytes | None = None,
+) -> VerifiableResponse:
+    """As should be clear from the function name, this function sends a Roughtime request
+    but does NOT verify the response in any way. This is dangerous and should only be used
+    if you REALLY know what you're doing."""  # noqa: D205 D209
+    logger.debug(
+        "Sending request to %s:%d with versions=%s",
+        host,
+        port,
+        ", ".join(f"{v:#x}" for v in versions) if versions else "default",
+    )
+    transport, protocol = await open_udp_socket(host, port)
+    logger.debug("Opened UDP socket to %s:%d", host, port)
+
+    try:
+        p = build_request(versions=versions, public_key=public_key, nonce=nonce)
+        payload = p.dump()
+        transport.sendto(payload)
+        logger.debug("Sent request to %s:%d", host, port)
+
+        data = await protocol.recv()
+        logger.debug("Received %d bytes from %s:%d", len(data), host, port)
+        response = VerifiableResponse.from_packet(raw=data, request=payload)
+        logger.debug("Parsed (unverified) response from %s:%d", host, port)
+    finally:
+        transport.close()
+
+    return response
+
+
+def build_request(
+    versions: Iterable[int] | None = None,
+    public_key: bytes | None = None,
+    nonce: bytes | None = None,
+) -> Packet:
+    """Build a spec-compliant request padded to 1024 bytes (UDP)."""
+    if versions is None:
+        versions = VERSIONS_SUPPORTED
+
+    ver = b"".join(struct.pack("<I", v) for v in versions)  # VER: uint32 list
+
+    if nonce is None:
+        nonce = os.urandom(32)
+
+    tag_list: list[Tag] = [
+        Tag(tag=tags.VER, value=ver),
+        Tag(tag=tags.NONC, value=nonce),
+        Tag(tag=tags.TYPE, value=struct.pack("<I", tags.TYPE_REQUEST)),
+    ]
+
+    if public_key is not None:
+        tag_list.append(Tag(tag=tags.SRV, value=partial_sha512(b"\xff" + public_key)))
+
+    message = Message(tags=tag_list)
+    message.prepare()
+    return Packet(message=message)
+
+
+@dataclass
+class VerifiableResponse(Response):
+    """Client-side response with verification context."""
+
+    raw: bytes
+    """The raw bytes of the Roughtime response packet"""
+
+    request: bytes
+    """The raw bytes of Roughtime packet that triggered this response"""
+
+    packet: Packet
+    """The full Roughtime response packet"""
+
+    dele_raw: bytes
+    """The raw DELE tag bytes for signature verification"""
+
+    srep_raw: bytes
+    """The raw SREP tag bytes for signature verification"""
+
+    _profile: ProtocolProfile
+
+    @property
+    def version(self) -> int:
+        """The version of the response."""
+        if not self.signed_response.version:
+            result = find_by_predicate(self.packet.message.tags, lambda t: t.tag == tags.VER)
+            if result is None:
+                raise PacketError("No VER tag found in response packet")
+            (version,) = struct.unpack("<I", self.packet.message.tags[result].value[:4])
+            return version
+
+        return self.signed_response.version
+
+    @classmethod
+    def from_packet(cls, *, raw: bytes, request: bytes) -> VerifiableResponse:
+        p = Packet.from_bytes(raw)
+
+        ver_result = find_by_predicate(p.message.tags, lambda t: t.tag == tags.VER)
+        if ver_result is not None:
+            (wire_ver,) = struct.unpack("<I", p.message.tags[ver_result].value)
+        else:
+            wire_ver = GOOGLE_ROUGHTIME_SENTINEL
+        wire_profile = ProtocolProfile.from_version(wire_ver)
+
+        response, dele_raw, srep_raw = Response.from_message(p.message, profile=wire_profile)
+
+        verifiable = cls(
+            signature=response.signature,
+            nonce=response.nonce,
+            type=response.type,
+            path=response.path,
+            signed_response=response.signed_response,
+            certificate=response.certificate,
+            index=response.index,
+            raw=raw,
+            request=request,
+            packet=p,
+            dele_raw=dele_raw,
+            srep_raw=srep_raw,
+            _profile=wire_profile,
+        )
+        verifiable._profile = ProtocolProfile.from_version(verifiable.version)
+
+        if wire_profile.type_tag_required and response.type is None:
+            raise PacketError("TYPE tag missing in response")
+
+        request_message = Packet.from_bytes(request).message
+        vers = pop_by_tag(request_message.tags, tags.VER)
+        versions = struct.unpack(f"<{len(vers.value) // 4}I", vers.value)
+        if verifiable.version not in versions:
+            raise PacketError(
+                f"Response version {verifiable.version:#x} not in request VER list: "
+                + ", ".join(f"{v:#x}" for v in versions)
+            )
+
+        nonc = pop_by_tag(request_message.tags, tags.NONC)
+        if verifiable.nonce != nonc.value:
+            raise PacketError("Response NONC does not match request NONC")
+
+        return verifiable
+
+    def _verify_merkle(self) -> bool:
+        raw = self.request if self._profile.leaf_from_request else self.nonce
+        h = self._profile.hasher(b"\x00" + raw)
+
+        for i, node in enumerate(self.path):
+            if (self.index >> i) & 1 == 0:
+                h = self._profile.hasher(b"\x01" + h + node)
+            else:
+                h = self._profile.hasher(b"\x01" + node + h)
+
+        return h == self.signed_response.root
+
+    def verify(self, long_term_public_key_bytes: bytes) -> bool:  # noqa: C901
+        delegation_context_string = self._profile.delegation_context
+
+        # 5.4. Validity of Response
+
+        # Structural checks on the signed response (§5.2.5).
+        srep = self.signed_response
+
+        # §5.2.5 L691: RADI MUST NOT be zero.
+        if srep.radius == 0:
+            raise VerificationError("RADI must not be zero", reason="radius")
+
+        # §5.2.5 L701-704: VERS structure (skip Google profile, which has no VERS tag).
+        if srep.versions:
+            if len(srep.versions) > 32:  # noqa: PLR2004
+                raise VerificationError(
+                    f"VERS contains {len(srep.versions)} entries (max 32)",
+                    reason="versions",
+                )
+            for prev, curr in zip(srep.versions, srep.versions[1:], strict=False):
+                if curr <= prev:
+                    raise VerificationError(
+                        "VERS must be strictly ascending and unique",
+                        reason="versions",
+                    )
+            if srep.version not in srep.versions:
+                raise VerificationError(
+                    f"VERS does not contain the response version {srep.version:#x}",
+                    reason="versions",
+                )
+
+        # The signature in CERT was made with the long-term key of the server.
+        long_term_public_key = ed25519.Ed25519PublicKey.from_public_bytes(
+            long_term_public_key_bytes
+        )
+        try:
+            long_term_public_key.verify(
+                self.certificate.signature,
+                delegation_context_string + self.dele_raw,
+            )
+        except cryptography.exceptions.InvalidSignature as e:
+            raise VerificationError(
+                "Certificate signature invalid", reason="signature-certificate"
+            ) from e
+
+        # The MIDP timestamp lies in the interval specified by the MINT and MAXT timestamps.
+        midp = self.signed_response.midpoint
+        if not (
+            self.certificate.delegation.min_time <= midp <= self.certificate.delegation.max_time
+        ):
+            raise VerificationError(
+                "MIDP timestamp is outside of delegation bounds", reason="key-age"
+            )
+
+        # The INDX and PATH values prove a hash value derived from the request packet was
+        # included in the Merkle tree with value ROOT
+        if not self._verify_merkle():
+            raise VerificationError("Merkle tree verification failed", reason="merkle")
+
+        # The signature of SREP in SIG validates with the public key in DELE.
+        public_key = ed25519.Ed25519PublicKey.from_public_bytes(
+            self.certificate.delegation.public_key
+        )
+        try:
+            public_key.verify(self.signature, RESPONSE_CONTEXT_STRING + self.srep_raw)
+        except cryptography.exceptions.InvalidSignature as e:
+            raise VerificationError(
+                "Response signature invalid", reason="signature-response"
+            ) from e
+
+        return True