roughtime/

lib.rs

//! A [no_std]-capable client for the [Roughtime] secure time synchronization protocol.
//!
//! Roughtime lets a client obtain the current time from a set of untrusted servers while
//! being able to cryptographically prove, after the fact, that any server which lied about
//! the time can be caught (via Ed25519 signatures over a Merkle tree of recent requests).
//! This crate implements the **client** side only: building requests, parsing and verifying
//! responses, and (optionally) querying real servers over the network.
//!
//! [no_std]: https://docs.rust-embedded.org/book/intro/no-std.html
//! [Roughtime]: https://blog.cloudflare.com/roughtime/
//!
//! # Feature flags
//!
//! Exactly one crypto backend feature must be enabled:
//!
//! - `rustcrypto` — pure-Rust [`ed25519-dalek`] + [`sha2`], `no_std`-capable.
//! - `aws-lc-rs` — [`aws-lc-rs`], the default.
//! - `aws-lc-rs-fips` — `aws-lc-rs` built in FIPS mode.
//!
//! Layered on top:
//!
//! - `std` (default) — enables the networking clients and the Linux `os-clock` backend.
//! - `tokio-client` (default) — an async, concurrent multi-server query client.
//! - `blocking-client` — a synchronous [`std::net::UdpSocket`]-based client.
//! - `os-clock` — an opt-in Linux [`SystemClock`](clock::SystemClock) implementation that can
//!   set the OS wall clock forward to the verified time floor.
//! - `dnscrypt` (default) — resolves well-known Roughtime server hostnames via [`dnscrypt`],
//!   an authenticated, encrypted DNS transport, instead of the OS's plaintext, unauthenticated
//!   resolver. This closes the one remaining plaintext, unauthenticated hop in an otherwise
//!   end-to-end-verified time-sync flow, and means callers no longer have to resolve/pin server
//!   IPs by hand. See [`resolve::resolve_servers`]/[`resolve::resolve_servers_async`] and
//!   [`client::TokioClient::query_well_known`]/[`client::BlockingClient::query_well_known`].
//! - `build-time-floor` — opt-in, **not** in `default`. Ratchets the anti-rollback floor
//!   forward to the build day using the build machine's wall clock. Leave this disabled for
//!   reproducible builds (e.g. attested boot images); see [`floor`] for details.
//!
//! [`dnscrypt`]: https://docs.rs/dnscrypt
//!
//! A `no_std` consumer (e.g. a kernel or bootloader) should build with
//! `--no-default-features --features rustcrypto` to get the wire-format, request-building,
//! and response-verification primitives with no networking or OS dependency — supplying its
//! own I/O and randomness.
//!
//! # Requirement: a global allocator
//!
//! This crate always uses `alloc` (for `Vec`-backed message parsing), even in `no_std` builds.
//! `no_std` consumers must provide a global allocator.
//!
//! # Security posture
//!
//! This is a client-only crate: it never holds Ed25519 *private* key material, only verifies
//! server-supplied public keys and signatures. The one client-generated secret-like value is
//! the 64-byte nonce, which is zeroized on drop (see [`request::Nonce`]). Raw response bytes
//! and extracted public keys are intentionally **not** zeroized — they are bulk public-protocol
//! data, and scrubbing them would cost real performance for no confidentiality benefit.

#![no_std]
#![doc(html_root_url = "https://docs.rs/roughtime")]

extern crate alloc;

#[cfg(feature = "std")]
extern crate std;

pub mod clock;
pub mod date;
pub mod error;
pub mod floor;
pub mod request;
pub mod servers;
pub mod tags;
pub mod verify;
pub mod wire;

mod crypto;

#[cfg(test)]
mod test_fixtures;

#[cfg(feature = "std")]
pub mod client;

#[cfg(feature = "os-clock")]
pub mod os_clock;

#[cfg(feature = "dnscrypt")]
pub mod resolve;

pub use error::Error;
pub use request::{Nonce, build_request};
pub use servers::{ROUGHTIME_SERVERS, RoughtimeServer};
pub use verify::{VerifiedTime, verify_response};

#[cfg(feature = "dnscrypt")]
pub use resolve::resolve_servers;
#[cfg(all(feature = "dnscrypt", feature = "tokio-client"))]
pub use resolve::resolve_servers_async;