rkik_nts/
lib.rs

1//! # rkik-nts
2//!
3//! A high-level NTS (Network Time Security) Client library based on ntpd-rs from the Pendulum Project.
4//!
5//! This library provides a simple, safe, and ergonomic API for querying time from NTS-secured NTP servers.
6//! It handles the complexity of NTS key exchange and authenticated time synchronization, making it easy
7//! to integrate secure time synchronization into your applications.
8//!
9//! ## Features
10//!
11//! - **Simple API**: Easy-to-use client interface with sensible defaults
12//! - **Real NTS Authentication (RFC 8915)**: Proper cryptographic authentication of NTP queries
13//! - **AEAD Protection**: All NTP packets are authenticated using negotiated AEAD algorithms
14//! - **Anti-Replay**: Unique identifiers prevent replay attacks
15//! - **Cookie Management**: Automatic cookie consumption and replenishment
16//! - **Certificate Diagnostics**: TLS certificate information capture for security auditing
17//! - **TLS Debugging**: SSLKEYLOGFILE support for Wireshark traffic analysis
18//! - **Async/Await**: Built on Tokio for efficient async I/O
19//! - **Configurable**: Flexible configuration options for advanced use cases
20//! - **Based on ntpd-rs**: Built on the battle-tested ntpd-rs implementation from Project Pendulum
21//!
22//! ## Security
23//!
24//! This library implements real NTS authentication according to RFC 8915:
25//!
26//! - **NTS-KE (Key Exchange)**: TLS handshake to negotiate AEAD algorithm and obtain keys
27//! - **NTS-Protected NTP**: UDP packets contain NTS extension fields:
28//!   - Unique Identifier (anti-replay)
29//!   - NTS Cookie (authenticates client)
30//!   - Cookie Placeholder (requests new cookies)
31//!   - AEAD Authenticator (protects entire packet)
32//!
33//! All responses are cryptographically verified. Modified or spoofed responses are rejected.
34//!
35//! ## Quick Start
36//!
37//! ```no_run
38//! use rkik_nts::{NtsClient, NtsClientConfig};
39//!
40//! #[tokio::main]
41//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
42//!     // Create a client configuration
43//!     let config = NtsClientConfig::new("time.cloudflare.com");
44//!
45//!     // Create and connect the client
46//!     let mut client = NtsClient::new(config);
47//!     client.connect().await?;
48//!
49//!     // Query the current time (authenticated)
50//!     let time = client.get_time().await?;
51//!
52//!     println!("Network time: {:?}", time.network_time);
53//!     println!("System time:  {:?}", time.system_time);
54//!     println!("Offset:       {} ms", time.offset_signed());
55//!     println!("Authenticated: {}", time.authenticated);
56//!
57//!     Ok(())
58//! }
59//! ```
60//!
61//! ## Configuration
62//!
63//! The library supports extensive configuration through [`NtsClientConfig`]:
64//!
65//! ```
66//! use rkik_nts::NtsClientConfig;
67//! use std::time::Duration;
68//!
69//! let config = NtsClientConfig::new("time.cloudflare.com")
70//!     .with_port(4460)
71//!     .with_timeout(Duration::from_secs(5))
72//!     .with_max_retries(3);
73//! ```
74//!
75//! ## Certificate Information
76//!
77//! Access TLS certificate information from the NTS-KE handshake:
78//!
79//! ```no_run
80//! use rkik_nts::{NtsClient, NtsClientConfig};
81//!
82//! # #[tokio::main]
83//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
84//! let config = NtsClientConfig::new("time.cloudflare.com");
85//! let mut client = NtsClient::new(config);
86//! client.connect().await?;
87//!
88//! // Access certificate and NTS-KE information
89//! if let Some(ke_info) = client.nts_ke_info() {
90//!     println!("AEAD Algorithm: {}", ke_info.aead_algorithm);
91//!     println!("Initial Cookies: {}", ke_info.initial_cookie_count);
92//!     if let Some(cert) = &ke_info.certificate {
93//!         println!("Certificate Subject: {}", cert.subject);
94//!         println!("Certificate Issuer: {}", cert.issuer);
95//!         println!("Valid: {} to {}", cert.valid_from, cert.valid_until);
96//!         println!("Fingerprint: {}", cert.fingerprint_sha256);
97//!         println!("Self-signed: {}", cert.is_self_signed);
98//!     }
99//! }
100//! # Ok(())
101//! # }
102//! ```
103//!
104//! ## Integration with rkik
105//!
106//! This library is designed for seamless integration with rkik, but can also be used
107//! as a standalone NTS client library in any Rust application.
108
109#![deny(missing_docs)]
110#![warn(rust_2018_idioms)]
111
112pub mod client;
113pub mod config;
114pub mod error;
115mod nts_ke;
116pub(crate) mod nts_ntp;
117pub mod types;
118
119// Re-export main types for convenience
120pub use client::{NtsClient, NtsKeInfo};
121pub use config::NtsClientConfig;
122pub use error::{Error, Result};
123pub use types::{CertificateInfo, TimeSnapshot};
rkik_nts/lib.rs

rkik_nts/
lib.rs
