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// Re-export types from ans-types for convenience
74pub use ans_types::{
75 AgentEvent, AgentInfo, AnsName, Attestations, Badge, BadgePayload, BadgeStatus,
76 CertAttestation, CertFingerprint, CryptoError, EventType, Fqdn, MerkleProof, ParseError,
77 Producer, Version,
78};
79
80// Re-export from this crate
81pub use cache::{BadgeCache, CacheConfig};
82pub use dane::{
83 DanePolicy, DaneVerificationResult, TlsaMatchingType, TlsaRecord, TlsaSelector, TlsaUsage,
84};
85#[cfg(any(test, feature = "test-support"))]
86pub use dns::MockDnsResolver;
87pub use dns::{BadgeRecord, DnsResolver, DnsResolverConfig, HickoryDnsResolver};
88pub use error::{
89 AnsError, AnsResult, DaneError, DnsError, HttpError, TlogError, VerificationError,
90};
91#[cfg(any(test, feature = "test-support"))]
92pub use tlog::MockTransparencyLogClient;
93pub use tlog::{AuditResponse, HttpTransparencyLogClient, TransparencyLogClient};
94pub use verify::{
95 AnsVerifier, AnsVerifierBuilder, CertIdentity, ClientVerifier, FailurePolicy, ServerVerifier,
96 VerificationOutcome,
97};
98
99#[cfg(feature = "rustls")]
100pub use rustls_verifier::{AnsClientCertVerifier, AnsServerCertVerifier};