Skip to main content

auth_framework/methods/client_cert/
mod.rs

1//! Client certificate authentication (application-layer mTLS identity extraction).
2//!
3//! # Where this fits in the stack
4//!
5//! ```text
6//! TLS layer   ─── mTLS handshake ──► proves client holds the private key
7//! This module ─── cert inspection ──► extracts identity, applies policy
8//! ```
9//!
10//! The TLS handshake cryptographically proves that the client possesses the
11//! private key corresponding to the certificate it presented.  Once TLS is
12//! established, the server-side application receives the **verified** certificate
13//! as DER bytes.  This module's job is the *second* part: inspecting the certificate
14//! to answer "who is this client?" and "are they permitted?".
15//!
16//! # What this module covers
17//!
18//! Any PKI-based client authentication that delivers an X.509 certificate to
19//! the application layer:
20//! - Software client certificates (p12/pfx, PEM bundles)
21//! - Smart card client certificates (SC/PKCS#11, hardware-bound private key)
22//! - US government PIV (NIST SP 800-73) certificates
23//! - CAC (Common Access Card) certificates
24//!
25//! From this module's perspective a smart card certificate is just an X.509 DER
26//! byte string.  The PC/SC protocol that extracts it from the physical card is
27//! handled at the transport layer (PKCS#11 middleware, OS TLS stack, etc.).
28//!
29//! # What this module does NOT do
30//!
31//! - **Cryptographic signature verification of the cert chain**: that belongs in the
32//!   TLS library (rustls, native-tls).  `ClientCertConfig::trusted_ca_ders` is a
33//!   *defence-in-depth* post-TLS policy check (issuer DN matching), not a replacement
34//!   for TLS-level chain verification.
35//! - **OCSP / CRL revocation checking**: a future extension.  Rely on the TLS layer's
36//!   revocation configuration for now.
37//! - **PC/SC card reader access**: use a PKCS#11 middleware library at the transport
38//!   layer (e.g. OpenSC).
39
40use std::collections::HashSet;
41use std::sync::Arc;
42use std::time::SystemTime;
43
44use crate::{
45    authentication::credentials::Credential,
46    errors::{AuthError, Result},
47};
48
49// ─── Configuration ────────────────────────────────────────────────────────────
50
51/// Configuration for [`ClientCertAuthMethod`].
52#[derive(Debug, Clone)]
53pub struct ClientCertConfig {
54    /// DER-encoded trusted CA certificates.
55    ///
56    /// When non-empty, the presented certificate's issuer DN is matched against
57    /// the subjects of these CAs.  This provides a meaningful policy guard when
58    /// the list is kept to a small, curated set of CAs you actually trust.
59    ///
60    /// **Security note**: this is an *issuer DN equality check*, not a full
61    /// cryptographic path validation.  For cryptographic assurance configure your
62    /// TLS library's trusted CA store, then use this list as a second policy filter.
63    pub trusted_ca_ders: Vec<Vec<u8>>,
64
65    /// Subject DN substrings that are allowed.  An empty list accepts any subject
66    /// (given other checks pass).  Matching is case-sensitive substring search on
67    /// the full Distinguished Name string (e.g. `"CN=alice"` or just `"alice"`).
68    pub subject_allowlist: Vec<String>,
69
70    /// Issuer DN substrings that are allowed.  An empty list accepts any issuer.
71    pub issuer_allowlist: Vec<String>,
72
73    /// When `true`, the certificate must contain a Subject Alternative Name (SAN)
74    /// extension.  PIV and modern TLS certificates always carry one; older
75    /// enterprise CAs sometimes do not.
76    pub require_san: bool,
77
78    /// Lifetime of the session issued after successful authentication (seconds).
79    pub token_lifetime_secs: u64,
80}
81
82impl Default for ClientCertConfig {
83    fn default() -> Self {
84        Self {
85            trusted_ca_ders: Vec::new(),
86            subject_allowlist: Vec::new(),
87            issuer_allowlist: Vec::new(),
88            require_san: false,
89            token_lifetime_secs: 3600,
90        }
91    }
92}
93
94impl ClientCertConfig {
95    /// Create a permissive configuration with a 1-hour session lifetime.
96    pub fn new() -> Self {
97        Self::default()
98    }
99
100    /// Builder: add a trusted CA (DER-encoded).
101    pub fn trust_ca(mut self, ca_der: Vec<u8>) -> Self {
102        self.trusted_ca_ders.push(ca_der);
103        self
104    }
105
106    /// Builder: allow only subjects whose DN contains `pattern`.
107    pub fn allow_subject(mut self, pattern: impl Into<String>) -> Self {
108        self.subject_allowlist.push(pattern.into());
109        self
110    }
111
112    /// Builder: allow only issuers whose DN contains `pattern`.
113    pub fn allow_issuer(mut self, pattern: impl Into<String>) -> Self {
114        self.issuer_allowlist.push(pattern.into());
115        self
116    }
117
118    /// Builder: require a SAN extension.
119    pub fn with_require_san(mut self) -> Self {
120        self.require_san = true;
121        self
122    }
123}
124
125// ─── Identity type ────────────────────────────────────────────────────────────
126
127/// Identity extracted from a successfully validated client certificate.
128#[derive(Debug, Clone)]
129pub struct CertIdentity {
130    /// Full Distinguished Name of the subject (e.g. `"CN=alice, O=Example Corp"`).
131    pub subject_dn: String,
132    /// Common Name (CN) extracted from the subject, if present.
133    pub common_name: Option<String>,
134    /// Subject Alternative Names collected from the SAN extension, if present.
135    /// Each entry is prefixed with its type: `"dns:host.example.com"`,
136    /// `"email:user@example.com"`, `"ip:192.0.2.1"`.
137    pub sans: Vec<String>,
138    /// Full Distinguished Name of the issuer.
139    pub issuer_dn: String,
140}
141
142// ─── Method ───────────────────────────────────────────────────────────────────
143
144/// Application-layer client certificate authenticator.
145///
146/// Validates an X.509 client certificate presented after an mTLS handshake and
147/// extracts a [`CertIdentity`] that higher-level code can use to create a session.
148///
149/// ## Minimal usage
150///
151/// ```rust,no_run
152/// use auth_framework::methods::client_cert::{ClientCertAuthMethod, ClientCertConfig};
153/// use auth_framework::authentication::credentials::Credential;
154///
155/// # let cert_der: Vec<u8> = unimplemented!();
156/// let method = ClientCertAuthMethod::new(ClientCertConfig::new());
157///
158/// // `cert_der` comes from your HTTP framework's peer certificate extraction.
159/// let identity = method.authenticate(&Credential::client_cert_from_tls(cert_der))?;
160/// # Ok::<_, auth_framework::errors::AuthError>(())
161/// ```
162pub struct ClientCertAuthMethod {
163    config: ClientCertConfig,
164}
165
166impl ClientCertAuthMethod {
167    /// Create a new authenticator with the given configuration.
168    pub fn new(config: ClientCertConfig) -> Self {
169        Self { config }
170    }
171
172    /// Validate `credential` and return the caller's certificate identity.
173    ///
174    /// Accepts `Credential::Certificate { certificate, .. }`.  The `private_key`
175    /// field is **ignored** — key possession was already proved by the TLS
176    /// handshake.  Use [`Credential::client_cert_from_tls`] to construct the
177    /// credential without supplying a private key.
178    pub fn authenticate(&self, credential: &Credential) -> Result<CertIdentity> {
179        let cert_der = match credential {
180            Credential::Certificate {
181                certificate,
182                private_key,
183                ..
184            } => {
185                if !private_key.is_empty() {
186                    tracing::warn!(
187                        "ClientCertAuthMethod received a non-empty private_key — \
188                         it will be ignored.  For mTLS flows use \
189                         `Credential::client_cert_from_tls(der_bytes)`."
190                    );
191                }
192                certificate.as_slice()
193            }
194            other => {
195                return Err(AuthError::InvalidCredential {
196                    credential_type: other.credential_type().to_string(),
197                    message: "ClientCertAuthMethod requires a Credential::Certificate. \
198                              Use Credential::client_cert_from_tls(der_bytes) for mTLS flows."
199                        .to_string(),
200                });
201            }
202        };
203
204        self.validate_der(cert_der)
205    }
206
207    // ── Validation pipeline ───────────────────────────────────────────────────
208
209    fn validate_der(&self, cert_der: &[u8]) -> Result<CertIdentity> {
210        use x509_parser::prelude::*;
211
212        if cert_der.is_empty() {
213            return Err(AuthError::InvalidCredential {
214                credential_type: "certificate".to_string(),
215                message: "Certificate DER bytes are empty".to_string(),
216            });
217        }
218
219        let (_, cert) =
220            X509Certificate::from_der(cert_der).map_err(|_| AuthError::InvalidCredential {
221                credential_type: "certificate".to_string(),
222                message: "Failed to parse X.509 DER certificate — verify that the bytes \
223                          are DER-encoded (not PEM) and are not truncated."
224                    .to_string(),
225            })?;
226
227        self.check_validity(&cert)?;
228        self.check_subject_allowlist(&cert)?;
229        self.check_issuer_allowlist(&cert)?;
230        self.check_san_required(&cert)?;
231        self.check_trust_chain(cert_der)?;
232        self.extract_identity(&cert)
233    }
234
235    fn check_validity(&self, cert: &x509_parser::certificate::X509Certificate<'_>) -> Result<()> {
236        let now = SystemTime::now()
237            .duration_since(SystemTime::UNIX_EPOCH)
238            .unwrap_or_default()
239            .as_secs() as i64;
240
241        let not_before = cert.validity().not_before.timestamp();
242        let not_after = cert.validity().not_after.timestamp();
243
244        if now < not_before {
245            return Err(AuthError::InvalidCredential {
246                credential_type: "certificate".to_string(),
247                message: format!(
248                    "Certificate is not yet valid (valid from Unix timestamp {})",
249                    not_before
250                ),
251            });
252        }
253        if now > not_after {
254            return Err(AuthError::InvalidCredential {
255                credential_type: "certificate".to_string(),
256                message: "Certificate has expired".to_string(),
257            });
258        }
259        Ok(())
260    }
261
262    fn check_subject_allowlist(
263        &self,
264        cert: &x509_parser::certificate::X509Certificate<'_>,
265    ) -> Result<()> {
266        if self.config.subject_allowlist.is_empty() {
267            return Ok(());
268        }
269        let subject = cert.subject().to_string();
270        if !self
271            .config
272            .subject_allowlist
273            .iter()
274            .any(|p| subject.contains(p.as_str()))
275        {
276            return Err(AuthError::InvalidCredential {
277                credential_type: "certificate".to_string(),
278                message: format!("Subject DN '{}' is not in the subject allowlist", subject),
279            });
280        }
281        Ok(())
282    }
283
284    fn check_issuer_allowlist(
285        &self,
286        cert: &x509_parser::certificate::X509Certificate<'_>,
287    ) -> Result<()> {
288        if self.config.issuer_allowlist.is_empty() {
289            return Ok(());
290        }
291        let issuer = cert.issuer().to_string();
292        if !self
293            .config
294            .issuer_allowlist
295            .iter()
296            .any(|p| issuer.contains(p.as_str()))
297        {
298            return Err(AuthError::InvalidCredential {
299                credential_type: "certificate".to_string(),
300                message: format!("Issuer DN '{}' is not in the issuer allowlist", issuer),
301            });
302        }
303        Ok(())
304    }
305
306    fn check_san_required(
307        &self,
308        cert: &x509_parser::certificate::X509Certificate<'_>,
309    ) -> Result<()> {
310        if !self.config.require_san {
311            return Ok(());
312        }
313        // SAN extension OID: 2.5.29.17
314        let has_san = cert
315            .extensions()
316            .iter()
317            .any(|ext| ext.oid.to_id_string() == "2.5.29.17");
318        if !has_san {
319            return Err(AuthError::InvalidCredential {
320                credential_type: "certificate".to_string(),
321                message: "Certificate does not contain a Subject Alternative Name (SAN) \
322                          extension, but require_san is enabled in the configuration."
323                    .to_string(),
324            });
325        }
326        Ok(())
327    }
328
329    /// Issuer DN matching against trusted CAs.
330    ///
331    /// Finds a CA in `trusted_ca_ders` whose subject DN equals the end-entity
332    /// certificate's issuer DN.  This is effective as a policy filter when the CA
333    /// list is carefully maintained; it is NOT a cryptographic signature check.
334    fn check_trust_chain(&self, cert_der: &[u8]) -> Result<()> {
335        if self.config.trusted_ca_ders.is_empty() {
336            return Ok(());
337        }
338
339        use x509_parser::prelude::*;
340
341        let (_, cert) =
342            X509Certificate::from_der(cert_der).map_err(|_| AuthError::InvalidCredential {
343                credential_type: "certificate".to_string(),
344                message: "Failed to re-parse certificate for chain check".to_string(),
345            })?;
346        let issuer_dn = cert.issuer().to_string();
347
348        let found = self.config.trusted_ca_ders.iter().any(|ca_der| {
349            if let Ok((_, ca_cert)) = X509Certificate::from_der(ca_der) {
350                ca_cert.subject().to_string() == issuer_dn
351            } else {
352                false
353            }
354        });
355
356        if !found {
357            return Err(AuthError::InvalidCredential {
358                credential_type: "certificate".to_string(),
359                message: format!(
360                    "No trusted CA found for issuer '{}'. \
361                     Add the issuing CA's DER bytes to ClientCertConfig::trusted_ca_ders.",
362                    issuer_dn
363                ),
364            });
365        }
366        Ok(())
367    }
368
369    fn extract_identity(
370        &self,
371        cert: &x509_parser::certificate::X509Certificate<'_>,
372    ) -> Result<CertIdentity> {
373        let subject_dn = cert.subject().to_string();
374        let issuer_dn = cert.issuer().to_string();
375
376        // First CN attribute in the subject RDN sequence.
377        let common_name = cert
378            .subject()
379            .iter_common_name()
380            .next()
381            .and_then(|attr| attr.as_str().ok())
382            .map(str::to_string);
383
384        // Collect DNS, email, and IP SANs from the SAN extension (OID 2.5.29.17).
385        let mut sans: Vec<String> = Vec::new();
386        for ext in cert.extensions() {
387            if ext.oid.to_id_string() == "2.5.29.17"
388                && let x509_parser::extensions::ParsedExtension::SubjectAlternativeName(san) =
389                    ext.parsed_extension()
390            {
391                for gn in &san.general_names {
392                    let entry = match gn {
393                        x509_parser::extensions::GeneralName::DNSName(s) => {
394                            format!("dns:{s}")
395                        }
396                        x509_parser::extensions::GeneralName::RFC822Name(s) => {
397                            format!("email:{s}")
398                        }
399                        x509_parser::extensions::GeneralName::IPAddress(ip) => {
400                            format!("ip:{}", fmt_ip(ip))
401                        }
402                        _ => continue,
403                    };
404                    sans.push(entry);
405                }
406            }
407        }
408
409        Ok(CertIdentity {
410            subject_dn,
411            common_name,
412            sans,
413            issuer_dn,
414        })
415    }
416}
417
418/// Format raw IP bytes as dotted-decimal (IPv4) or colon-hex (IPv6).
419fn fmt_ip(bytes: &[u8]) -> String {
420    match bytes.len() {
421        4 => format!("{}.{}.{}.{}", bytes[0], bytes[1], bytes[2], bytes[3]),
422        16 => {
423            let parts: Vec<String> = bytes
424                .chunks(2)
425                .map(|c| format!("{:02x}{:02x}", c[0], c[1]))
426                .collect();
427            parts.join(":")
428        }
429        _ => format!("{:?}", bytes),
430    }
431}
432
433// ── Certificate Pinning ───────────────────────────────────────────────────────
434
435/// Certificate fingerprint for pinning.
436///
437/// Stores the SHA-256 hash of a DER-encoded certificate for pin comparison.
438#[derive(Debug, Clone, PartialEq, Eq, Hash)]
439pub struct CertPin {
440    /// SHA-256 fingerprint as a lowercase hex string.
441    pub sha256_hex: String,
442}
443
444impl CertPin {
445    /// Compute a pin from DER-encoded certificate bytes.
446    pub fn from_der(cert_der: &[u8]) -> Self {
447        use sha2::{Digest, Sha256};
448        let digest = Sha256::digest(cert_der);
449        Self {
450            sha256_hex: hex::encode(digest),
451        }
452    }
453
454    /// Create a pin from a known hex fingerprint.
455    pub fn from_hex(hex_fingerprint: impl Into<String>) -> Self {
456        Self {
457            sha256_hex: hex_fingerprint.into().to_lowercase(),
458        }
459    }
460}
461
462/// A certificate pin store for enforcing certificate pinning.
463///
464/// When pinning is enabled, only certificates whose SHA-256 fingerprint
465/// appears in this store are accepted.
466#[derive(Debug, Clone, Default)]
467pub struct CertPinStore {
468    pins: Arc<std::sync::RwLock<HashSet<String>>>,
469}
470
471impl CertPinStore {
472    /// Create a new empty pin store.
473    pub fn new() -> Self {
474        Self::default()
475    }
476
477    /// Add a pin by SHA-256 hex fingerprint.
478    pub fn add(&self, pin: &CertPin) {
479        self.pins.write().unwrap().insert(pin.sha256_hex.clone());
480    }
481
482    /// Remove a pin.
483    pub fn remove(&self, pin: &CertPin) -> bool {
484        self.pins.write().unwrap().remove(&pin.sha256_hex)
485    }
486
487    /// Check if a certificate (DER) matches any pinned fingerprint.
488    pub fn is_pinned(&self, cert_der: &[u8]) -> bool {
489        let pin = CertPin::from_der(cert_der);
490        self.pins.read().unwrap().contains(&pin.sha256_hex)
491    }
492
493    /// Number of stored pins.
494    pub fn count(&self) -> usize {
495        self.pins.read().unwrap().len()
496    }
497}
498
499// ── Revocation Checking ───────────────────────────────────────────────────────
500
501/// Revocation check result.
502#[derive(Debug, Clone, PartialEq, Eq)]
503pub enum RevocationStatus {
504    /// Certificate is known to be good (not revoked).
505    Good,
506    /// Certificate has been revoked.
507    Revoked {
508        /// RFC 5280 CRLReason (optional).
509        reason: Option<String>,
510    },
511    /// Revocation status is unknown (e.g., responder unavailable).
512    Unknown,
513}
514
515/// An in-memory CRL (Certificate Revocation List) store.
516///
517/// For production deployments, the TLS layer should handle CRL/OCSP. This
518/// provides an application-layer defence-in-depth check against known-revoked
519/// serial numbers.
520#[derive(Debug, Clone, Default)]
521pub struct CrlStore {
522    /// Revoked certificate serial numbers (hex-encoded), keyed by issuer DN.
523    revoked: Arc<std::sync::RwLock<std::collections::HashMap<String, HashSet<String>>>>,
524}
525
526impl CrlStore {
527    /// Create a new empty CRL store.
528    pub fn new() -> Self {
529        Self::default()
530    }
531
532    /// Mark a certificate serial number as revoked for a given issuer DN.
533    pub fn add_revoked(&self, issuer_dn: &str, serial_hex: &str) {
534        self.revoked
535            .write()
536            .unwrap()
537            .entry(issuer_dn.to_string())
538            .or_default()
539            .insert(serial_hex.to_lowercase());
540    }
541
542    /// Check if a certificate (by issuer DN and serial hex) is revoked.
543    pub fn check(&self, issuer_dn: &str, serial_hex: &str) -> RevocationStatus {
544        let store = self.revoked.read().unwrap();
545        if let Some(serials) = store.get(issuer_dn) {
546            if serials.contains(&serial_hex.to_lowercase()) {
547                return RevocationStatus::Revoked { reason: None };
548            }
549        }
550        RevocationStatus::Good
551    }
552
553    /// Check a DER-encoded certificate against the CRL store.
554    pub fn check_der(&self, cert_der: &[u8]) -> RevocationStatus {
555        use x509_parser::prelude::*;
556        let Ok((_, cert)) = X509Certificate::from_der(cert_der) else {
557            return RevocationStatus::Unknown;
558        };
559        let issuer = cert.issuer().to_string();
560        let serial = cert.raw_serial_as_string().to_lowercase();
561        self.check(&issuer, &serial)
562    }
563
564    /// Total count of revoked serial numbers across all issuers.
565    pub fn revoked_count(&self) -> usize {
566        self.revoked.read().unwrap().values().map(|s| s.len()).sum()
567    }
568
569    /// Remove all entries for an issuer.
570    pub fn clear_issuer(&self, issuer_dn: &str) {
571        self.revoked.write().unwrap().remove(issuer_dn);
572    }
573}
574
575// ── Certificate-Bound Access Tokens (RFC 8705) ───────────────────────────────
576
577/// Computes a certificate thumbprint for use in RFC 8705 certificate-bound
578/// access tokens (mTLS client certificate binding).
579///
580/// Returns the base64url-encoded SHA-256 hash of the DER-encoded certificate,
581/// suitable for the `x5t#S256` confirmation claim in JWT access tokens.
582pub fn cert_thumbprint_s256(cert_der: &[u8]) -> String {
583    use base64::Engine;
584    use sha2::{Digest, Sha256};
585    let digest = Sha256::digest(cert_der);
586    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(digest)
587}
588
589/// Verify that a presented certificate matches the `x5t#S256` thumbprint
590/// bound to an access token (RFC 8705 §3).
591pub fn verify_cert_binding(cert_der: &[u8], expected_thumbprint: &str) -> Result<()> {
592    let actual = cert_thumbprint_s256(cert_der);
593    if actual == expected_thumbprint {
594        Ok(())
595    } else {
596        Err(AuthError::InvalidCredential {
597            credential_type: "certificate".to_string(),
598            message: format!(
599                "Certificate thumbprint mismatch: token bound to '{}', presented cert has '{}'",
600                expected_thumbprint, actual
601            ),
602        })
603    }
604}
605
606// ─── Tests ────────────────────────────────────────────────────────────────────
607
608#[cfg(test)]
609mod tests {
610    use super::*;
611
612    // ── Configuration ─────────────────────────────────────────────────────────
613
614    #[test]
615    fn test_config_default() {
616        let cfg = ClientCertConfig::default();
617        assert!(cfg.trusted_ca_ders.is_empty());
618        assert!(cfg.subject_allowlist.is_empty());
619        assert!(cfg.issuer_allowlist.is_empty());
620        assert!(!cfg.require_san);
621        assert_eq!(cfg.token_lifetime_secs, 3600);
622    }
623
624    #[test]
625    fn test_config_builder_chain() {
626        let cfg = ClientCertConfig::new()
627            .allow_subject("alice")
628            .allow_issuer("MyCA")
629            .with_require_san();
630        assert_eq!(cfg.subject_allowlist, ["alice"]);
631        assert_eq!(cfg.issuer_allowlist, ["MyCA"]);
632        assert!(cfg.require_san);
633    }
634
635    // ── Error paths (no real cert required) ───────────────────────────────────
636
637    #[test]
638    fn test_wrong_credential_type_rejected() {
639        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
640        let cred = Credential::Password {
641            username: "u".into(),
642            password: "p".into(),
643        };
644        let err = method.authenticate(&cred).unwrap_err();
645        assert!(
646            format!("{err}").contains("Certificate"),
647            "unexpected: {err}"
648        );
649    }
650
651    #[test]
652    fn test_empty_der_rejected() {
653        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
654        let cred = Credential::Certificate {
655            certificate: vec![],
656            private_key: vec![],
657            passphrase: None,
658        };
659        let err = method.authenticate(&cred).unwrap_err();
660        assert!(format!("{err}").contains("empty"), "unexpected: {err}");
661    }
662
663    #[test]
664    fn test_garbage_der_rejected() {
665        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
666        let cred = Credential::Certificate {
667            certificate: vec![0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x02, 0x03, 0x04],
668            private_key: vec![],
669            passphrase: None,
670        };
671        assert!(method.authenticate(&cred).is_err());
672    }
673
674    // ── Certificate DER builder for tests ─────────────────────────────────────
675    //
676    // Constructs a minimal self-signed Ed25519 X.509v3 certificate in DER.
677    // Validity dates are hardcoded as UTCTime raw bytes (ISO 8601 compact form).
678    //
679    // To regenerate equivalent certs with openssl:
680    //   openssl req -x509 -newkey ed25519 -keyout /tmp/k.pem -out /tmp/c.pem \
681    //     -days 730 -nodes -subj "/CN=<cn>"
682    //   openssl x509 -in /tmp/c.pem -outform DER | xxd -i
683    fn build_cert_der(
684        cn: &str,
685        not_before_utc: &[u8; 13], // raw UTCTime bytes e.g. b"250101000000Z"
686        not_after_utc: &[u8; 13],
687    ) -> Vec<u8> {
688        use ring::rand::SystemRandom;
689        use ring::signature::{Ed25519KeyPair, KeyPair};
690
691        let rng = SystemRandom::new();
692        let pkcs8 = Ed25519KeyPair::generate_pkcs8(&rng).unwrap();
693        let kp = Ed25519KeyPair::from_pkcs8(pkcs8.as_ref()).unwrap();
694        let pub_key = kp.public_key().as_ref(); // 32 bytes
695
696        // Short-form TLV (content < 128 bytes)
697        let tlv = |tag: u8, content: &[u8]| -> Vec<u8> {
698            assert!(
699                content.len() < 128,
700                "content too large for short-form TLV: {} bytes",
701                content.len()
702            );
703            let mut v = vec![tag, content.len() as u8];
704            v.extend_from_slice(content);
705            v
706        };
707
708        // TLV with definite long form when content >= 128 bytes
709        let long_tlv = |tag: u8, content: &[u8]| -> Vec<u8> {
710            let len = content.len();
711            let mut v = vec![tag];
712            if len < 128 {
713                v.push(len as u8);
714            } else {
715                // Two-byte length (content < 65536)
716                v.push(0x81);
717                v.push(len as u8);
718            }
719            v.extend_from_slice(content);
720            v
721        };
722
723        // OID 1.3.101.112 (id-EdDSA / Ed25519)
724        let alg_id = tlv(0x30, &[0x06, 0x03, 0x2B, 0x65, 0x70]);
725
726        // Name: SEQUENCE { SET { SEQUENCE { OID 2.5.4.3, UTF8String cn } } }
727        let cn_bytes = cn.as_bytes();
728        let utf8_cn = tlv(0x0C, cn_bytes);
729        let oid_cn = [0x06u8, 0x03, 0x55, 0x04, 0x03];
730        let seq_atv = [oid_cn.as_slice(), utf8_cn.as_slice()].concat();
731        let name = tlv(0x30, &tlv(0x31, &tlv(0x30, &seq_atv)));
732
733        // Validity: SEQUENCE { UTCTime nb, UTCTime na }
734        let nb_der = tlv(0x17, not_before_utc);
735        let na_der = tlv(0x17, not_after_utc);
736        let validity = tlv(0x30, &[nb_der.as_slice(), na_der.as_slice()].concat());
737
738        // SubjectPublicKeyInfo: SEQUENCE { alg_id, BIT STRING { 0x00 || pub_key } }
739        let mut bit_content = vec![0x00u8];
740        bit_content.extend_from_slice(pub_key);
741        let bit_str = tlv(0x03, &bit_content);
742        let spki = tlv(0x30, &[alg_id.as_slice(), bit_str.as_slice()].concat());
743
744        // TBSCertificate
745        let version = [0xA0u8, 0x03, 0x02, 0x01, 0x02]; // [0] EXPLICIT INTEGER 2 (v3)
746        let serial = tlv(0x02, &[0x01]);
747        let tbs_body: Vec<u8> = [
748            version.as_slice(),
749            serial.as_slice(),
750            alg_id.as_slice(), // signatureAlgorithm
751            name.as_slice(),   // issuer
752            validity.as_slice(),
753            name.as_slice(), // subject (same as issuer: self-signed)
754            spki.as_slice(),
755        ]
756        .concat();
757        let tbs = long_tlv(0x30, &tbs_body);
758
759        // Self-sign the TBSCertificate bytes
760        let sig = kp.sign(&tbs);
761        let mut sig_content = vec![0x00u8]; // BIT STRING: 0 unused bits
762        sig_content.extend_from_slice(sig.as_ref()); // 64 bytes
763        let sig_bit_str = tlv(0x03, &sig_content);
764
765        // Certificate: SEQUENCE { tbs, signatureAlgorithm, signatureValue }
766        let cert_body: Vec<u8> =
767            [tbs.as_slice(), alg_id.as_slice(), sig_bit_str.as_slice()].concat();
768        long_tlv(0x30, &cert_body)
769    }
770
771    // Validity windows (UTCTime raw bytes):
772    //   Valid now (2025-01-01 → 2027-01-01)
773    fn valid_cert(cn: &str) -> Vec<u8> {
774        build_cert_der(cn, b"250101000000Z", b"270101000000Z")
775    }
776    //   Expired (2020-01-01 → 2021-01-01)
777    fn expired_cert(cn: &str) -> Vec<u8> {
778        build_cert_der(cn, b"200101000000Z", b"210101000000Z")
779    }
780    //   Future (2028-01-01 → 2030-01-01)
781    fn future_cert(cn: &str) -> Vec<u8> {
782        build_cert_der(cn, b"280101000000Z", b"300101000000Z")
783    }
784
785    fn cert_cred(der: Vec<u8>) -> Credential {
786        Credential::Certificate {
787            certificate: der,
788            private_key: vec![],
789            passphrase: None,
790        }
791    }
792
793    // ── Certificate-based tests ────────────────────────────────────────────────
794
795    #[test]
796    fn test_valid_cert_accepted() {
797        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
798        let id = method
799            .authenticate(&cert_cred(valid_cert("alice")))
800            .expect("valid cert should be accepted");
801        assert!(
802            id.subject_dn.contains("alice"),
803            "subject should contain CN: {}",
804            id.subject_dn
805        );
806        assert_eq!(id.common_name.as_deref(), Some("alice"));
807    }
808
809    #[test]
810    fn test_expired_cert_rejected() {
811        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
812        let err = method
813            .authenticate(&cert_cred(expired_cert("bob")))
814            .unwrap_err();
815        let msg = format!("{err}");
816        assert!(msg.contains("expired"), "expected 'expired' in: {msg}");
817    }
818
819    #[test]
820    fn test_future_cert_rejected() {
821        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
822        let err = method
823            .authenticate(&cert_cred(future_cert("carol")))
824            .unwrap_err();
825        let msg = format!("{err}");
826        assert!(msg.contains("valid"), "expected 'valid' in: {msg}");
827    }
828
829    #[test]
830    fn test_subject_allowlist_permits_matching_cn() {
831        let cfg = ClientCertConfig::new().allow_subject("alice");
832        assert!(
833            ClientCertAuthMethod::new(cfg)
834                .authenticate(&cert_cred(valid_cert("alice")))
835                .is_ok()
836        );
837    }
838
839    #[test]
840    fn test_subject_allowlist_blocks_non_matching_cn() {
841        let cfg = ClientCertConfig::new().allow_subject("alice");
842        let err = ClientCertAuthMethod::new(cfg)
843            .authenticate(&cert_cred(valid_cert("mallory")))
844            .unwrap_err();
845        let msg = format!("{err}");
846        assert!(msg.contains("allowlist"), "expected 'allowlist' in: {msg}");
847    }
848
849    #[test]
850    fn test_issuer_allowlist_permits_self_signed_when_matches() {
851        // Self-signed: issuer DN == subject DN == "CN=alice"
852        let cfg = ClientCertConfig::new().allow_issuer("alice");
853        assert!(
854            ClientCertAuthMethod::new(cfg)
855                .authenticate(&cert_cred(valid_cert("alice")))
856                .is_ok()
857        );
858    }
859
860    #[test]
861    fn test_issuer_allowlist_blocks_unmatched_issuer() {
862        let cfg = ClientCertConfig::new().allow_issuer("TrustedCorp");
863        let err = ClientCertAuthMethod::new(cfg)
864            .authenticate(&cert_cred(valid_cert("alice")))
865            .unwrap_err();
866        let msg = format!("{err}");
867        assert!(msg.contains("allowlist"), "expected 'allowlist' in: {msg}");
868    }
869
870    #[test]
871    fn test_require_san_rejects_cert_without_san() {
872        // Our test cert builder produces no SAN extension.
873        let cfg = ClientCertConfig::new().with_require_san();
874        let err = ClientCertAuthMethod::new(cfg)
875            .authenticate(&cert_cred(valid_cert("alice")))
876            .unwrap_err();
877        let msg = format!("{err}");
878        assert!(
879            msg.contains("Subject Alternative Name") || msg.contains("SAN"),
880            "expected SAN mention in: {msg}"
881        );
882    }
883
884    #[test]
885    fn test_trusted_ca_accepts_when_issuer_dn_matches() {
886        // A self-signed cert is its own issuer; adding it to trusted_ca_ders
887        // means its own subject DN matches the issuer DN look-up.
888        let der = valid_cert("alice");
889        let cfg = ClientCertConfig::new().trust_ca(der.clone());
890        assert!(
891            ClientCertAuthMethod::new(cfg)
892                .authenticate(&cert_cred(der))
893                .is_ok()
894        );
895    }
896
897    #[test]
898    fn test_trusted_ca_rejects_when_no_ca_matches() {
899        let untrusted_cert = valid_cert("alice");
900        // Different self-signed cert = different subject DN
901        let different_ca = valid_cert("OtherCA");
902        let cfg = ClientCertConfig::new().trust_ca(different_ca);
903        let err = ClientCertAuthMethod::new(cfg)
904            .authenticate(&cert_cred(untrusted_cert))
905            .unwrap_err();
906        let msg = format!("{err}");
907        assert!(
908            msg.contains("trusted CA") || msg.contains("issuer"),
909            "expected CA/issuer mention in: {msg}"
910        );
911    }
912
913    #[test]
914    fn test_client_cert_from_tls_constructor() {
915        let der = valid_cert("sys");
916        let cred = Credential::client_cert_from_tls(der.clone());
917        match &cred {
918            Credential::Certificate {
919                certificate,
920                private_key,
921                passphrase,
922            } => {
923                assert_eq!(certificate, &der);
924                assert!(private_key.is_empty(), "private_key should be empty");
925                assert!(passphrase.is_none());
926            }
927            _ => panic!("Expected Credential::Certificate"),
928        }
929
930        // Also verify it authenticates successfully
931        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
932        assert!(method.authenticate(&cred).is_ok());
933    }
934
935    #[test]
936    fn test_issuer_dn_populated_in_identity() {
937        let method = ClientCertAuthMethod::new(ClientCertConfig::new());
938        let id = method
939            .authenticate(&cert_cred(valid_cert("charlie")))
940            .unwrap();
941        // Self-signed: issuer == subject
942        assert_eq!(id.issuer_dn, id.subject_dn);
943    }
944
945    // ── Certificate Pinning ─────────────────────────────────────
946
947    #[test]
948    fn test_cert_pin_from_der() {
949        let der = valid_cert("pin-test");
950        let pin = CertPin::from_der(&der);
951        assert_eq!(pin.sha256_hex.len(), 64); // SHA-256 hex = 64 chars
952    }
953
954    #[test]
955    fn test_cert_pin_deterministic() {
956        let der = vec![0x30, 0x82, 0x01, 0x00];
957        let p1 = CertPin::from_der(&der);
958        let p2 = CertPin::from_der(&der);
959        assert_eq!(p1, p2);
960    }
961
962    #[test]
963    fn test_cert_pin_from_hex() {
964        let pin = CertPin::from_hex("AABB");
965        assert_eq!(pin.sha256_hex, "aabb"); // lowercase
966    }
967
968    #[test]
969    fn test_cert_pin_store_add_and_check() {
970        let store = CertPinStore::new();
971        let der = valid_cert("pinned");
972        let pin = CertPin::from_der(&der);
973        store.add(&pin);
974        assert_eq!(store.count(), 1);
975        assert!(store.is_pinned(&der));
976        assert!(!store.is_pinned(&valid_cert("not-pinned")));
977    }
978
979    #[test]
980    fn test_cert_pin_store_remove() {
981        let store = CertPinStore::new();
982        let der = valid_cert("removable");
983        let pin = CertPin::from_der(&der);
984        store.add(&pin);
985        assert!(store.remove(&pin));
986        assert!(!store.is_pinned(&der));
987        assert_eq!(store.count(), 0);
988    }
989
990    // ── CRL Store ───────────────────────────────────────────────
991
992    #[test]
993    fn test_crl_store_add_and_check() {
994        let store = CrlStore::new();
995        store.add_revoked("CN=TestCA", "0a1b2c");
996        assert_eq!(
997            store.check("CN=TestCA", "0a1b2c"),
998            RevocationStatus::Revoked { reason: None }
999        );
1000        assert_eq!(store.check("CN=TestCA", "ffffff"), RevocationStatus::Good);
1001        assert_eq!(store.check("CN=OtherCA", "0a1b2c"), RevocationStatus::Good);
1002    }
1003
1004    #[test]
1005    fn test_crl_store_case_insensitive_serial() {
1006        let store = CrlStore::new();
1007        store.add_revoked("CN=CA", "aAbBcC");
1008        assert_eq!(
1009            store.check("CN=CA", "AABBCC"),
1010            RevocationStatus::Revoked { reason: None }
1011        );
1012    }
1013
1014    #[test]
1015    fn test_crl_store_check_der() {
1016        let store = CrlStore::new();
1017        let der = valid_cert("crl-test");
1018        // Without any revocations → Good
1019        assert_eq!(store.check_der(&der), RevocationStatus::Good);
1020    }
1021
1022    #[test]
1023    fn test_crl_store_revoked_count() {
1024        let store = CrlStore::new();
1025        store.add_revoked("CN=CA1", "01");
1026        store.add_revoked("CN=CA1", "02");
1027        store.add_revoked("CN=CA2", "01");
1028        assert_eq!(store.revoked_count(), 3);
1029    }
1030
1031    #[test]
1032    fn test_crl_store_clear_issuer() {
1033        let store = CrlStore::new();
1034        store.add_revoked("CN=CA", "01");
1035        store.add_revoked("CN=CA", "02");
1036        store.clear_issuer("CN=CA");
1037        assert_eq!(store.revoked_count(), 0);
1038    }
1039
1040    // ── RFC 8705 Certificate-Bound Tokens ───────────────────────
1041
1042    #[test]
1043    fn test_cert_thumbprint_s256() {
1044        let der = valid_cert("rfc8705");
1045        let thumbprint = cert_thumbprint_s256(&der);
1046        // base64url-encoded SHA-256 = 43 chars
1047        assert_eq!(thumbprint.len(), 43);
1048    }
1049
1050    #[test]
1051    fn test_cert_thumbprint_deterministic() {
1052        let der = vec![0x30, 0x82, 0x00, 0x01];
1053        let t1 = cert_thumbprint_s256(&der);
1054        let t2 = cert_thumbprint_s256(&der);
1055        assert_eq!(t1, t2);
1056    }
1057
1058    #[test]
1059    fn test_verify_cert_binding_success() {
1060        let der = valid_cert("bound");
1061        let thumbprint = cert_thumbprint_s256(&der);
1062        assert!(verify_cert_binding(&der, &thumbprint).is_ok());
1063    }
1064
1065    #[test]
1066    fn test_verify_cert_binding_mismatch() {
1067        let der = valid_cert("bound");
1068        let err = verify_cert_binding(&der, "wrong-thumbprint").unwrap_err();
1069        let msg = format!("{err}");
1070        assert!(msg.contains("mismatch"), "expected 'mismatch' in: {msg}");
1071    }
1072}