ntp_usg

A Network Time Protocol (NTP) packet parsing and client library written in Rust.

Features

• 🔒 Safe & Secure: #![deny(unsafe_code)] crate-wide; only platform FFI in the optional clock module uses unsafe
• 📚 Well Documented: Comprehensive API documentation with examples
• ⚡ Configurable Timeouts: Control request timeouts for different network conditions
• 🔄 Async Ready: Optional async support via Tokio or smol
• 🕐 Y2036 Safe: Era-aware timestamp handling for the NTP 32-bit rollover
• 🌍 Multi-Server Support: Query multiple NTP servers for improved reliability
• 🔐 Network Time Security: NTS (RFC 8915) with TLS 1.3 key establishment and AEAD authentication
• 📡 Continuous Client: Adaptive poll interval, multi-peer, and interleaved mode (RFC 9769)
• 🌐 IPv6 Dual-Stack: Automatic IPv4/IPv6 socket binding
• 🧩 no_std Support: Core parsing works without std or alloc
• ⏱️ Clock Adjustment: Platform-native slew/step correction (Linux, macOS, Windows)
• 🦀 Modern Rust: Edition 2024 with MSRV 1.93
• ✅ Well Tested: CI/CD on Linux, macOS, and Windows

Installation

Add this to your Cargo.toml:

[dependencies]
ntp_usg = "2.0"

Minimum Supported Rust Version (MSRV): 1.93 Edition: 2024

Feature Flags

For no_std environments, disable default features:

[dependencies]
ntp_usg = { version = "2.0", default-features = false }          # core parsing only
ntp_usg = { version = "2.0", default-features = false, features = ["alloc"] }  # + Vec-based types

Usage

Basic Example

use chrono::TimeZone;

fn main() {
    let address = "time.nist.gov:123";
    let response = ntp::request(address).unwrap();
    let unix_time = ntp::unix_time::Instant::from(response.transmit_timestamp);
    let local_time = chrono::Local
        .timestamp_opt(unix_time.secs(), unix_time.subsec_nanos() as _)
        .unwrap();
    println!("Current time: {}", local_time);
}

Custom Timeout

use std::time::Duration;

let response = ntp::request_with_timeout("time.nist.gov:123", Duration::from_secs(10))?;

Async with Tokio

Enable the tokio feature:

[dependencies]
ntp_usg = { version = "2.0", features = ["tokio"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = ntp::async_ntp::request("time.nist.gov:123").await?;
    println!("Offset: {:.6} seconds", result.offset_seconds);
    Ok(())
}

Continuous Client

The continuous client polls servers with adaptive intervals and supports interleaved mode (RFC 9769):

use ntp::client::NtpClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, mut state_rx) = NtpClient::builder()
        .server("time.nist.gov:123")
        .min_poll(4)
        .max_poll(10)
        .build()
        .await?;

    tokio::spawn(client.run());

    // Wait for sync state updates.
    while state_rx.changed().await.is_ok() {
        let state = state_rx.borrow();
        println!("Offset: {:.6}s, Delay: {:.6}s", state.offset, state.delay);
    }
    Ok(())
}

NTS (Network Time Security)

Enable the nts feature for authenticated NTP:

[dependencies]
ntp_usg = { version = "2.0", features = ["nts"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use ntp::nts::NtsSession;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = NtsSession::from_ke("time.cloudflare.com").await?;
    let result = session.request().await?;
    println!("NTS offset: {:.6}s", result.offset_seconds);
    Ok(())
}

NTS Continuous Client

Combine NTS authentication with the continuous polling client:

use ntp::client::NtpClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, mut state_rx) = NtpClient::builder()
        .nts_server("time.cloudflare.com")
        .min_poll(4)
        .max_poll(10)
        .build()
        .await?;

    tokio::spawn(client.run());

    while state_rx.changed().await.is_ok() {
        let state = state_rx.borrow();
        println!("Offset: {:.6}s, NTS: {}", state.offset, state.nts_authenticated);
    }
    Ok(())
}

Async with smol

Enable the smol-runtime feature:

[dependencies]
ntp_usg = { version = "2.0", features = ["smol-runtime"] }
smol = "2"

use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    smol::block_on(async {
        let result = ntp::smol_ntp::request_with_timeout(
            "time.nist.gov:123",
            Duration::from_secs(5),
        ).await?;
        println!("Offset: {:.6} seconds", result.offset_seconds);
        Ok(())
    })
}

The smol continuous client uses Arc<RwLock<NtpSyncState>> for state sharing:

use ntp::smol_client::NtpClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    smol::block_on(async {
        let (client, state) = NtpClient::builder()
            .server("time.nist.gov:123")
            .build()
            .await?;

        smol::spawn(client.run()).detach();

        loop {
            smol::Timer::after(std::time::Duration::from_secs(5)).await;
            let s = state.read().unwrap();
            println!("Offset: {:.6}s, Delay: {:.6}s", s.offset, s.delay);
        }
    })
}

Clock Adjustment

Enable the clock feature to correct the system clock based on NTP measurements:

[dependencies]
ntp_usg = { version = "2.0", features = ["clock", "tokio"] }

use ntp::clock;

// Gradual correction (slew) for small offsets
clock::slew_clock(0.05)?;

// Immediate correction (step) for large offsets
clock::step_clock(-1.5)?;

// Automatic: slew if |offset| <= 128ms, step otherwise
let method = clock::apply_correction(offset)?;

Multiple Servers

See examples/multiple_servers.rs for a complete example of querying multiple NTP servers.

Examples

Run the included examples to see the library in action:

# Basic request example
cargo run --example request

# Custom timeout demonstration
cargo run --example timeout

# Query multiple servers
cargo run --example multiple_servers

# Detailed packet information
cargo run --example packet_details

# Async concurrent queries (requires tokio feature)
cargo run --example async_request --features tokio

# Continuous client with poll management (requires tokio feature)
cargo run --example continuous --features tokio

# NTS-authenticated request (requires nts feature)
cargo run --example nts_request --features nts

# NTS continuous client (requires nts feature)
cargo run --example nts_continuous --features nts

# Smol one-shot request
cargo run --example smol_request --features smol-runtime

# Smol continuous client
cargo run --example smol_continuous --features smol-runtime

# Clock adjustment (requires root/sudo on Unix, Administrator on Windows)
cargo run --example clock_adjust --features "clock tokio"

Roadmap

• async support (tokio)
• NTP era handling (Y2036)
• IPv6 dual-stack support
• Continuous client with adaptive polling
• Interleaved mode (RFC 9769)
• Network Time Security (RFC 8915)
• IO-independent parsing (FromBytes/ToBytes traits)
• no_std support (with optional alloc)
• smol support (one-shot, continuous, and NTS)
• System clock adjustment (slew/step on Linux, macOS, Windows)
• NTP server functionality

Contributing

Pull requests and issues are welcome! Please see our GitHub repository for more information.

License

ntp_usg is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.