ans_verify/
lib.rs

1#![warn(missing_docs)]
2
3//! # ANS Trust Verification Library
4//!
5//! This library implements the ANS (Agent Name Service) Trust Verification Flow,
6//! providing tools for verifying agent identity and trust status.
7//!
8//! ## Overview
9//!
10//! The ANS architecture uses a dual-certificate model:
11//! - **Public Server Certificate**: Issued by a public CA (e.g., Let's Encrypt)
12//! - **Private Identity Certificate**: Issued by the ANS Private CA
13//!
14//! Verification relies on:
15//! - DNS `_ans-badge` TXT records pointing to the transparency log (with `_ra-badge` fallback)
16//! - Transparency Log API returning badges with status and certificate fingerprints
17//! - Certificate fingerprint comparison
18//! - Optional DANE/TLSA verification for additional DNS-based certificate binding
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! use ans_verify::{AnsVerifier, VerificationOutcome, CertIdentity};
24//!
25//! #[tokio::main]
26//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
27//!     let verifier = AnsVerifier::new().await?;
28//!
29//!     // After TLS handshake, extract server certificate and verify
30//!     let cert_der: &[u8] = &[]; // Your certificate bytes
31//!     let cert_identity = CertIdentity::from_der(cert_der)?;
32//!
33//!     let outcome = verifier
34//!         .verify_server("agent.example.com", &cert_identity)
35//!         .await;
36//!
37//!     match outcome {
38//!         VerificationOutcome::Verified { badge, .. } => {
39//!             println!("Verified ANS agent: {}", badge.agent_name());
40//!         }
41//!         VerificationOutcome::NotAnsAgent { fqdn } => {
42//!             println!("Not a registered ANS agent: {}", fqdn);
43//!         }
44//!         _ => println!("Verification failed"),
45//!     }
46//!
47//!     Ok(())
48//! }
49//! ```
50//!
51//! ## Features
52//!
53//! - DNS-based badge discovery via `_ans-badge` TXT records (with `_ra-badge` fallback)
54//! - Transparency Log API integration for badge retrieval
55//! - Certificate fingerprint verification (SHA-256)
56//! - Optional DANE/TLSA verification with configurable policies
57//! - DNSSEC validation support
58//! - Configurable DNS resolvers (System, Cloudflare, Google, Quad9)
59//! - Response caching with configurable TTL
60//! - Async-first design with tokio
61//! - Optional rustls integration for TLS handshake verification
62
63mod cache;
64mod dane;
65mod dns;
66mod error;
67mod tlog;
68mod verify;
69
70#[cfg(feature = "rustls")]
71mod rustls_verifier;
72
73#[cfg(feature = "scitt")]
74mod scitt;
75
76// Re-export types from ans-types for convenience
77pub use ans_types::{
78    AgentEvent, AgentInfo, AnsName, Attestations, Badge, BadgePayload, BadgeStatus,
79    CertAttestation, CertFingerprint, CryptoError, EventType, Fqdn, MerkleProof, ParseError,
80    Producer, Version,
81};
82
83// Re-export from this crate
84pub use cache::{BadgeCache, CacheConfig, CacheKey, CachedBadge};
85pub use dane::{
86    DanePolicy, DaneVerificationResult, TlsaMatchingType, TlsaRecord, TlsaSelector, TlsaUsage,
87};
88#[cfg(any(test, feature = "test-support"))]
89pub use dns::MockDnsResolver;
90pub use dns::{BadgeRecord, DnsResolver, DnsResolverConfig, HickoryDnsResolver};
91pub use error::{
92    AnsError, AnsResult, DaneError, DnsError, HttpError, TlogError, VerificationError,
93};
94#[cfg(any(test, feature = "test-support"))]
95pub use tlog::MockTransparencyLogClient;
96pub use tlog::{AuditResponse, HttpTransparencyLogClient, TransparencyLogClient};
97pub use verify::{
98    AnsVerifier, AnsVerifierBuilder, CertIdentity, ClientVerifier, FailurePolicy, ServerVerifier,
99    VerificationOutcome,
100};
101
102#[cfg(feature = "scitt")]
103pub use verify::{ScittConfig, ScittTierPolicy};
104
105#[cfg(feature = "rustls")]
106pub use rustls_verifier::{AnsClientCertVerifier, AnsServerCertVerifier};
107
108#[cfg(feature = "scitt")]
109pub use scitt::{
110    ClockFn, HttpScittClient, KeyRefreshHandle, ReceiptCache, RefreshableKeyStore, ScittClient,
111    ScittError, ScittHeaderSupplier, ScittHeaders, ScittKeyStore, ScittOutgoingHeaders,
112    ScittRefreshHandle, ScittVerificationCache, StatusTokenCache, TrustedKey, VerifiedReceipt,
113    VerifiedStatusToken, system_clock, verify_receipt, verify_status_token,
114};
115
116#[cfg(all(feature = "scitt", any(test, feature = "test-support")))]
117pub use scitt::{
118    MockScittClient, ParsedCoseSign1, compute_sig_structure_digest, matches_identity_cert,
119    matches_server_cert, parse_cose_sign1, verify_status_token_at,
120};
ans_verify/lib.rs

ans_verify/
lib.rs
