cert_helper/

certificate.rs

mod builder;
mod common;
mod csr;
mod key;
mod policy;
mod usage;
use builder::select_hash;
pub use builder::{BuilderCommon, BuilderFields, HashAlg, UseesBuilderFields};
use common::{ValidityBound, set_validity};
pub use common::{X509Common, X509Parts};
pub use csr::{Csr, CsrBuilder, CsrOptions, CsrX509Common};
pub use key::KeyType;
pub(crate) use key::is_digestless_key;
#[cfg(feature = "pqc")]
use key::reject_mlkem_signing;
use key::{select_key, sign_certificate_digestless};
use openssl::asn1::{Asn1Object, Asn1OctetString, Asn1Time};
use openssl::bn::BigNum;
use openssl::error::ErrorStack;
use openssl::hash::{MessageDigest, hash};
use openssl::nid::Nid;
use openssl::pkey::{PKey, Private};
use openssl::stack::Stack;
use openssl::x509::extension::{AuthorityKeyIdentifier, BasicConstraints, SubjectAlternativeName};
use openssl::x509::{
    X509, X509Builder, X509Extension, X509NameBuilder, X509StoreContext, store::X509StoreBuilder,
};
pub use policy::CertificatePolicy;
use policy::append_certificate_policies;
use std::collections::{HashMap, HashSet};
use std::marker::PhantomData;
use std::net::IpAddr;
use std::path::Path;
pub use usage::Usage;
use usage::get_key_usage;
#[cfg(feature = "pqc")]
use usage::validate_pqc_key_usage;
use x509_parser::extensions::ParsedExtension;
use x509_parser::parse_x509_certificate;

/// Typestate marker for a [`CertBuilder`] with **no** path length set.
///
/// This is the default state ([`CertBuilder::new`] returns
/// `CertBuilder<PathLenUnset>`). In this state the builder can self-sign or sign
/// without a chain. Calling [`CertBuilder::pathlen`] transitions it to
/// [`PathLenSet`].
pub struct PathLenUnset;

/// Typestate marker for a [`CertBuilder`] with a path length set via
/// [`CertBuilder::pathlen`].
///
/// In this state the builder must be signed with
/// [`CertBuilder::build_and_sign_with_chain`], so the requested path length can be
/// validated against the signer's chain. The plain `build_and_sign` is not
/// available, preventing a CA from being issued without that check.
pub struct PathLenSet;

/// Holds the generated X.509 certificate and its associated private key.
///
/// `Debug` is derived; the `pkey` field prints opaquely (openssl's `PKey`
/// `Debug` does not expose key material), so it is safe to log a `Certificate`.
#[derive(Clone, Debug)]
pub struct Certificate {
    /// The X.509 certificate.
    pub x509: X509,
    /// The private key used to generate or sign the certificate.
    ///
    /// This is optional to allow for cases where the key is stored or managed separately.
    pub pkey: Option<PKey<Private>>,
}

impl X509Parts for Certificate {
    fn get_pem(&self) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
        Ok(self.x509.to_pem()?)
    }

    fn get_private_key(&self) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
        match self.pkey {
            Some(ref pkey) => Ok(pkey.private_key_to_pem_pkcs8()?),
            _ => Err("No private key found".into()),
        }
    }
    fn pem_extension(&self) -> &'static str {
        "_cert.pem"
    }
}

/// Helper trait to document that Certificate implements X509Common
pub trait CertificateX509Common: X509Common {}
impl CertificateX509Common for Certificate {}

impl Certificate {
    /// Loads a certificate and private key that are in PEM format from file
    /// and creates an X509 and PKey object.
    pub fn load_cert_and_key<C: AsRef<Path>, K: AsRef<Path>>(
        cert_pem_file: C,
        key_pem_file: K,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let cert_pem = std::fs::read(cert_pem_file)?;
        let key_pem = std::fs::read(key_pem_file)?;
        let cert = X509::from_pem(&cert_pem)?;
        let pkey = PKey::private_key_from_pem(&key_pem)?;
        Ok(Self {
            x509: cert,
            pkey: Some(pkey),
        })
    }

    /// Loads an X.509 certificate (without a private key) from a PEM file.
    ///
    /// The returned [`Certificate`] has `pkey: None`. This is intended for chain
    /// entries passed to [`CertBuilder::build_and_sign_with_chain`] or
    /// [`CsrOptions::pathlen`], which only read the certificate, never the key.
    ///
    /// # Errors
    /// Returns an error if the file cannot be read or does not contain a valid
    /// PEM-encoded X.509 certificate.
    pub fn load_cert<C: AsRef<Path>>(cert_pem_file: C) -> Result<Self, Box<dyn std::error::Error>> {
        let cert_pem = std::fs::read(cert_pem_file)?;
        let cert = X509::from_pem(&cert_pem)?;
        Ok(Self {
            x509: cert,
            pkey: None,
        })
    }
}

/// Builder for creating a new certificate and private key
pub struct CertBuilder<P = PathLenUnset> {
    fields: BuilderFields,
    valid_from: ValidityBound,
    valid_to: ValidityBound,
    policies: Vec<CertificatePolicy>,
    ca: bool,
    path_len: Option<u32>,
    _marker: PhantomData<P>,
}

impl<P> UseesBuilderFields for CertBuilder<P> {
    fn fields_mut(&mut self) -> &mut BuilderFields {
        &mut self.fields
    }
}
impl Default for CertBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl<P> CertBuilder<P> {
    /// Add optional certificate policies
    ///
    /// # Arguments
    /// * `policies` - A list of certificate policies
    pub fn certificate_policies(mut self, policies: Vec<CertificatePolicy>) -> Self {
        self.policies = policies;
        self
    }
    /// Sets the `yyyy-mm-dd` date from which the certificate is valid.
    ///
    /// The date is parsed when the certificate is built, so a malformed value is
    /// reported as an error from the build step rather than a panic here.
    pub fn valid_from(mut self, valid_from: &str) -> Self {
        self.valid_from = ValidityBound::Date(valid_from.to_owned());
        self
    }
    /// Sets the `yyyy-mm-dd` date after which the certificate is no longer valid.
    ///
    /// The date is parsed when the certificate is built, so a malformed value is
    /// reported as an error from the build step rather than a panic here. When
    /// the certificate is signed by a CA, a date later than the signer's
    /// `notAfter` is rejected at build time; the default one-year window is
    /// clamped to the signer's `notAfter` instead.
    pub fn valid_to(mut self, valid_to: &str) -> Self {
        self.valid_to = ValidityBound::Date(valid_to.to_owned());
        self
    }
    /// Specifies whether the certificate should be a Certificate Authority (CA).
    ///
    /// # Arguments
    /// * `ca` - `true` if the certificate should be a CA, `false` otherwise.
    pub fn is_ca(mut self, ca: bool) -> Self {
        if ca {
            self.ca = ca;
            self.fields
                .set_key_usage(HashSet::from([Usage::certsign, Usage::crlsign]));
        }
        self
    }
    /// Add optional path length, it is the max number of **non-self-issued
    /// intermediate CA certs** that may follow this cert in a chain
    ///
    /// # Arguments
    /// * `path_len`- u32
    pub fn pathlen(self, path_len: u32) -> CertBuilder<PathLenSet> {
        CertBuilder {
            fields: self.fields,
            valid_from: self.valid_from,
            valid_to: self.valid_to,
            policies: self.policies,
            ca: self.ca,
            path_len: Some(path_len),
            _marker: PhantomData,
        }
    }

    /// Creates a self-signed X.509 certificate and its private key.
    ///
    /// # Errors
    /// Returns an error if a `valid_from`/`valid_to` date is not `yyyy-mm-dd`,
    /// if key generation fails, or if OpenSSL rejects the certificate contents.
    pub fn build_and_self_sign(&self) -> Result<Certificate, Box<dyn std::error::Error>> {
        let (mut builder, pkey) = self.prepare_x509_builder(None)?;

        // ML-KEM keys cannot produce signatures, so a self-signed certificate is
        // impossible — issue via build_and_sign() with a separate signing CA.
        #[cfg(feature = "pqc")]
        reject_mlkem_signing(
            &pkey,
            "ML-KEM (FIPS 203) is a key-encapsulation key and cannot produce \
             signatures, so it cannot self-sign a certificate. Issue an ML-KEM \
             certificate with CertBuilder::build_and_sign() using a signing CA \
             (e.g. an ML-DSA or ECDSA CA) instead.",
        )?;

        let ca_cert: X509 = if is_digestless_key(&pkey) {
            let build_cert = builder.build();
            sign_certificate_digestless(&build_cert, &pkey)
                .map_err(|e| format!("Failed to sign certificate with digestless key: {}", e))?;
            build_cert
        } else {
            builder.sign(&pkey, select_hash(&self.fields.signature_alg))?;
            builder.build()
        };

        Ok(Certificate {
            x509: ca_cert,
            pkey: Some(pkey),
        })
    }

    fn prepare_x509_builder(
        &self,
        signer: Option<&Certificate>,
    ) -> Result<(X509Builder, PKey<Private>), Box<dyn std::error::Error>> {
        let mut name_builder = X509NameBuilder::new()?;
        name_builder.append_entry_by_nid(Nid::COMMONNAME, &self.fields.common_name)?;
        if !self.fields.country_name.trim().is_empty() {
            name_builder.append_entry_by_nid(Nid::COUNTRYNAME, &self.fields.country_name)?;
        }
        if !self.fields.state_province.trim().is_empty() {
            name_builder
                .append_entry_by_nid(Nid::STATEORPROVINCENAME, &self.fields.state_province)?;
        }
        if !self.fields.locality_time.trim().is_empty() {
            name_builder.append_entry_by_nid(Nid::LOCALITYNAME, &self.fields.locality_time)?;
        }
        if !self.fields.organization.trim().is_empty() {
            name_builder.append_entry_by_nid(Nid::ORGANIZATIONNAME, &self.fields.organization)?;
        }
        if !self.fields.organization_unit.trim().is_empty() {
            name_builder
                .append_entry_by_nid(Nid::ORGANIZATIONALUNITNAME, &self.fields.organization_unit)?;
        }

        let name = name_builder.build();

        let mut builder = X509::builder()?;
        builder.set_version(2)?;

        let serial_number = {
            let mut serial = BigNum::new()?;
            serial.rand(159, openssl::bn::MsbOption::MAYBE_ZERO, false)?;
            serial.to_asn1_integer()?
        };

        let pkey = match &self.fields.existing_key {
            Some(pkey) => pkey.clone(),
            None => select_key(&self.fields.key_type)?,
        };
        builder.set_serial_number(&serial_number)?;
        builder.set_subject_name(&name)?;
        builder.set_pubkey(&pkey)?;
        set_validity(
            &mut builder,
            &self.valid_from,
            &self.valid_to,
            signer.map(|s| &*s.x509),
        )?;
        match signer {
            Some(signer) => builder.set_issuer_name(signer.x509.subject_name())?,
            None => builder.set_issuer_name(&name)?,
        }

        let key_usage = self.fields.usage.clone().unwrap_or_default();
        append_certificate_policies(&mut builder, &self.policies)?;
        // Enforce post-quantum KeyUsage rules (signature-only ML-DSA/SLH-DSA vs
        // keyEncipherment-only ML-KEM). See validate_pqc_key_usage.
        #[cfg(feature = "pqc")]
        validate_pqc_key_usage(&pkey, &key_usage)?;

        if self.ca {
            let result = ca_basic_constraints(self.path_len)?;
            builder.append_extension(result)?;
        } else {
            builder.append_extension(BasicConstraints::new().build()?)?;
        }

        let (tracked_key_usage, tracked_extended_key_usage) = get_key_usage(&Some(key_usage));
        if tracked_key_usage.is_used() {
            builder.append_extension(tracked_key_usage.into_inner().build()?)?;
        }
        if tracked_extended_key_usage.is_used() {
            builder.append_extension(tracked_extended_key_usage.into_inner().build()?)?;
        }

        // A CA is identified by its DN and key id, never by SAN — so don't invent one.
        // End-entity certs get the CN copied in, since RFC 6125 verifiers ignore CN.
        let names = san_names(&self.fields, !self.ca);
        if !names.is_empty() {
            // RFC 5280 §4.2.1.6 — never emit an empty SAN
            let mut san = SubjectAlternativeName::new();
            for n in &names {
                add_san_entry(&mut san, n);
            }
            if let Some(signer_cert) = signer {
                builder.append_extension(
                    san.build(&builder.x509v3_context(Some(&signer_cert.x509), None))?,
                )?;
            } else {
                builder.append_extension(san.build(&builder.x509v3_context(None, None))?)?;
            }
        }

        if let Some(signer_cert) = signer {
            if signer_cert.x509.subject_key_id().is_some() {
                let aki = AuthorityKeyIdentifier::new()
                    .keyid(true)
                    .issuer(false)
                    .build(&builder.x509v3_context(Some(&signer_cert.x509), None))?;
                builder.append_extension(aki)?;
            }
        } else {
            // add aki that is the same as ski for self signed
            let oid = Asn1Object::from_str("2.5.29.35")?; // OID för Authority Key Identifier (AKI)
            let pubkey_der = pkey.public_key_to_der()?;
            let aki_hash = hash(MessageDigest::sha1(), &pubkey_der)?;
            let der_encoded = yasna::construct_der(|writer| {
                writer.write_sequence(|writer| {
                    writer
                        .next()
                        .write_tagged_implicit(yasna::Tag::context(0), |writer| {
                            writer.write_bytes(aki_hash.as_ref());
                        })
                })
            });
            let aki_asn1 = Asn1OctetString::new_from_bytes(&der_encoded)?;
            let ext = X509Extension::new_from_der(oid.as_ref(), false, &aki_asn1)?;
            builder.append_extension(ext)?;
        }
        // tried
        // let ski = SubjectKeyIdentifier::new().build(&builder.x509v3_context(None, None))?;
        // but got miss/match in hash values so I calculate the ski explicitly with sha1
        // to verify with openssl cli
        // RSA:
        // openssl x509 -in mytestca_cert.pem -inform PEM -pubkey -noout | openssl rsa -pubin -outform DER | openssl dgst -c -sha1
        // EC:
        // openssl x509 -in mytestca_cert.pem -inform PEM -pubkey -noout| openssl pkey -pubin -outform DER| openssl dgst -c -sha1
        let oid = Asn1Object::from_str("2.5.29.14")?; // OID för Subject Key Identifier (SKI)
        let pubkey_der = pkey.public_key_to_der()?;
        let ski_hash = hash(MessageDigest::sha1(), &pubkey_der)?;
        let der_encoded = yasna::construct_der(|writer| {
            writer.write_bytes(ski_hash.as_ref());
        });
        let ski_asn1 = Asn1OctetString::new_from_bytes(&der_encoded)?;
        let ext = X509Extension::new_from_der(oid.as_ref(), false, &ski_asn1)?;
        builder.append_extension(ext)?;

        Ok((builder, pkey))
    }
}

impl CertBuilder<PathLenUnset> {
    /// Create a new CertBuilder with defaults and one year from now as valid date
    pub fn new() -> Self {
        Self {
            fields: BuilderFields::default(),
            valid_from: ValidityBound::DaysFromNow(0), // today, resolved at build
            valid_to: ValidityBound::DaysFromNow(365), // one year from now
            ca: false,
            policies: Default::default(),
            path_len: None,
            _marker: PhantomData,
        }
    }
    /// Creates a certificate and private key signed by `signer`.
    ///
    /// # Errors
    /// Returns an error if `signer` is not a valid CA within its validity period
    /// or has no private key, if a `valid_from`/`valid_to` date is not
    /// `yyyy-mm-dd`, if an explicit `valid_to` is later than the signer's
    /// `notAfter`, or if OpenSSL rejects the certificate contents.
    pub fn build_and_sign(
        &self,
        signer: &Certificate,
    ) -> Result<Certificate, Box<dyn std::error::Error>> {
        let can_sign = can_sign_cert(signer)?;
        if !can_sign {
            let err = format!(
                "Cannot sign with signer certificate {:?}: it must be a valid CA \
             (BasicConstraints CA flag set, KeyUsage keyCertSign, within its validity \
             period) and have an associated private key",
                signer.x509.subject_name()
            );
            return Err(err.into());
        }
        let (mut builder, pkey) = self.prepare_x509_builder(Some(signer))?;
        let signer_key = signer
            .pkey
            .as_ref()
            .ok_or("signer certificate has no associated private key; cannot sign")?;
        let cert: X509 = if is_digestless_key(signer_key) {
            let build_cert = builder.build();
            sign_certificate_digestless(&build_cert, signer_key)
                .map_err(|e| format!("Failed to sign certificate with digestless key: {}", e))?;
            build_cert
        } else {
            builder.sign(signer_key, select_hash(&self.fields.signature_alg))?;
            builder.build()
        };
        Ok(Certificate {
            x509: cert,
            pkey: Some(pkey),
        })
    }
}

impl CertBuilder<PathLenSet> {
    /// Creates a CA certificate signed by `signer`, enforcing its path length against `chain`.
    ///
    /// # Errors
    /// Returns an error under the same conditions as [`CertBuilder::build_and_sign`],
    /// and additionally if the requested path length does not fit under the
    /// constraints already present in `chain`.
    pub fn build_and_sign_with_chain(
        &self,
        signer: &Certificate,
        chain: &[&Certificate],
    ) -> Result<Certificate, Box<dyn std::error::Error>> {
        let can_sign = can_sign_cert(signer)?;
        if !can_sign {
            let err = format!(
                "Cannot sign with signer certificate {:?}: it must be a valid CA \
             (BasicConstraints CA flag set, KeyUsage keyCertSign, within its validity \
             period) and have an associated private key",
                signer.x509.subject_name()
            );
            return Err(err.into());
        }
        let chain_x509: Vec<&X509> = chain.iter().map(|c| &c.x509).collect();
        enforce_path_len(self.ca, self.path_len, signer, &chain_x509)?;

        let (mut builder, pkey) = self.prepare_x509_builder(Some(signer))?;
        let signer_key = signer
            .pkey
            .as_ref()
            .ok_or("signer certificate has no associated private key; cannot sign")?;
        let cert: X509 = if is_digestless_key(signer_key) {
            let build_cert = builder.build();
            sign_certificate_digestless(&build_cert, signer_key)
                .map_err(|e| format!("Failed to sign certificate with digestless key: {}", e))?;
            build_cert
        } else {
            builder.sign(signer_key, select_hash(&self.fields.signature_alg))?;
            builder.build()
        };
        Ok(Certificate {
            x509: cert,
            pkey: Some(pkey),
        })
    }
}
fn ca_basic_constraints(path_len: Option<u32>) -> Result<X509Extension, ErrorStack> {
    let mut bc = BasicConstraints::new();
    bc.ca().critical();
    if let Some(len) = path_len {
        bc.pathlen(len);
    }
    bc.build()
}

/// Verifies a certificate against a root certificate and the intermediate
/// chain leading up to it.
/// Note: The root certificate should not be included in the chain.
pub fn verify_cert(
    cert: &X509,
    ca: &X509,
    cert_chain: Vec<&X509>,
) -> Result<bool, Box<dyn std::error::Error>> {
    // Build a certificate store and add the issuer
    let mut store_builder = X509StoreBuilder::new()?;
    store_builder.add_cert(ca.clone())?;
    let store = store_builder.build();

    // Create a verification context
    let mut ctx = X509StoreContext::new()?;
    let mut chain = Stack::new()?; // create an empty chain
    cert_chain
        .iter()
        .try_for_each(|c| chain.push((*c).clone()))?;
    ctx.init(&store, cert, &chain, |c| c.verify_cert())?;
    let verified = ctx.error() == openssl::x509::X509VerifyResult::OK;
    Ok(verified)
}

/// Takes a vector of certificates and returns a vector ordered
/// from the root to the leaf, with the leaf certificate as the last element.
///
/// For example, if the input list contains `ca2`, `leaf`, and `ca1`,
/// and the signing order is `ca1 -> ca2 -> leaf`,
/// the returned vector will be `[ca1, ca2, leaf]`.
///
/// If multiple valid chains are possible, the longest one is returned.
pub fn create_cert_chain_from_cert_list(
    certs: Vec<X509>,
) -> Result<Vec<X509>, Box<dyn std::error::Error>> {
    let mut subject_map: HashMap<Vec<u8>, X509> = HashMap::new();
    let mut issuer_map: HashMap<Vec<u8>, Vec<u8>> = HashMap::new();

    for cert in &certs {
        let subject = cert.subject_name().to_der()?;
        let issuer = cert.issuer_name().to_der()?;
        subject_map.insert(subject.clone(), cert.clone());
        issuer_map.insert(subject, issuer);
    }

    // Find leaf certificates (those that are not issuers of any other cert)
    let all_issuers: Vec<Vec<u8>> = issuer_map
        .iter()
        .filter(|(subject, issuer)| subject != issuer) // ignore the self-signed self-reference
        .map(|(_, issuer)| issuer.clone())
        .collect();
    let leaf_certs: Vec<X509> = subject_map
        .iter()
        .filter(|(subject, _)| !all_issuers.contains(subject))
        .map(|(_, cert)| cert.clone())
        .collect();

    // Try to build the longest chain from each leaf
    let mut longest_chain = Vec::new();

    for leaf in leaf_certs {
        let mut chain = vec![leaf.clone()];
        let mut current_cert = leaf;

        while let Ok(issuer_der) = current_cert.issuer_name().to_der() {
            if let Some(parent_cert) = subject_map.get(&issuer_der) {
                if parent_cert.subject_name().to_der()? == current_cert.subject_name().to_der()? {
                    break; // Self-signed, stop here
                }
                chain.push(parent_cert.clone());
                current_cert = parent_cert.clone();
            } else {
                break; // Issuer not found in the list
            }
        }

        if chain.len() > longest_chain.len() {
            longest_chain = chain;
        }
    }

    // Reverse to have root (or highest known CA) first
    longest_chain.reverse();
    Ok(longest_chain)
}

fn add_san_entry(san: &mut SubjectAlternativeName, value: &str) {
    match value.parse::<IpAddr>() {
        Ok(ip) => san.ip(&ip.to_string()),
        Err(_) => san.dns(value),
    };
}

/// The SAN entries for a certificate or signing request: everything the caller
/// asked for, plus the common name when it belongs there.
///
/// `include_cn` is false for CA certificates — a CA is identified by its
/// distinguished name and key identifier during path validation, so it carries
/// no SAN at all. It is true for end-entity certificates and for signing
/// requests, because RFC 6125 verifiers match on the SAN and ignore the CN.
///
/// The CN is skipped when the caller already listed it, so a name given both
/// ways is emitted once rather than twice.
///
/// Callers must not emit an extension when this returns an empty list —
/// RFC 5280 §4.2.1.6 requires a present SubjectAltName to hold at least one
/// entry.
pub(crate) fn san_names(fields: &BuilderFields, include_cn: bool) -> Vec<&str> {
    let mut names: Vec<&str> = fields
        .alternative_names
        .iter()
        .map(String::as_str)
        .collect();
    if include_cn
        && !fields.common_name.trim().is_empty()
        && !fields.alternative_names.contains(&fields.common_name)
    {
        names.push(&fields.common_name);
    }
    names
}

fn enforce_path_len(
    is_ca: bool,
    path_len: Option<u32>,
    signer: &Certificate,
    chain: &[&X509],
) -> Result<(), Box<dyn std::error::Error>> {
    // No pathLen set (or non-CA) → nothing to enforce, no chain required.
    // Matches CertBuilder: a no-pathLen / unlimited CA isn't budget-checked.
    if !is_ca || path_len.is_none() {
        return Ok(());
    }
    let budget = verify_cert_path(signer, chain)?;
    if let (Some(b), Some(m)) = (budget, path_len)
        && m >= b
    {
        return Err("requested pathLen exceeds what the signer's chain permits".into());
    }
    Ok(())
}

fn verify_cert_path(
    signer: &Certificate,
    chain: &[&X509],
) -> Result<Option<u32>, Box<dyn std::error::Error>> {
    let mut owned: Vec<X509> = chain.iter().map(|c| (*c).clone()).collect();
    owned.push(signer.x509.clone());
    let ordered = create_cert_chain_from_cert_list(owned)?;
    let root = ordered.first().unwrap();
    let pubkey = root.public_key()?;
    if !root.verify(&pubkey)? {
        let err = format!(
            "Could not find self signed root, found last ancestor {:?}",
            root.subject_name()
        );
        return Err(err.into());
    }
    let signer = ordered.last().unwrap();
    let intermediates: Vec<&X509> = ordered
        .get(1..ordered.len().saturating_sub(1)) // 1..0 → None for len==1
        .unwrap_or(&[])
        .iter()
        .collect();
    match verify_cert(signer, root, intermediates) {
        Ok(true) => {
            let mut budget: Option<i64> = None;
            for (d, ancestor) in ordered.iter().rev().enumerate() {
                if let Some(p) = ancestor.pathlen() {
                    // ancestor's declared pathLen
                    let candidate = p as i64 - d as i64; // can be negative — that's fine
                    budget = Some(budget.map_or(candidate, |b| b.min(candidate)));
                }
            }
            match budget {
                Some(b) if b < 1 => {
                    Err("signer's path length budget is exhausted; cannot issue a CA".into())
                }
                Some(b) => Ok(Some(b as u32)), // b >= 1 here, cast is safe
                None => Ok(None),              // no pathLen anywhere → unlimited
            }
        }
        _ => {
            let err = format!(
                "Cannot verify the crtificate chain for {:?}",
                signer.subject_name()
            );
            Err(err.into())
        }
    }
}

fn can_sign_cert(cert: &Certificate) -> Result<bool, Box<dyn std::error::Error>> {
    if cert.pkey.is_none() {
        return Ok(false);
    }

    let der = cert.x509.to_der()?;
    let (_, parsed_cert) = parse_x509_certificate(&der)?;

    let mut is_ca = false;
    let mut can_sign = false;
    let now = Asn1Time::days_from_now(0)?;
    let valid_time = cert.x509.not_before().compare(&now)? != std::cmp::Ordering::Greater
        && cert.x509.not_after().compare(&now)? == std::cmp::Ordering::Greater;

    for ext in parsed_cert.tbs_certificate.extensions().iter() {
        match &ext.parsed_extension() {
            ParsedExtension::BasicConstraints(bc) => {
                is_ca = bc.ca;
            }
            ParsedExtension::KeyUsage(ku) => {
                can_sign = ku.key_cert_sign();
            }
            _ => {}
        }
    }
    Ok(is_ca && can_sign && valid_time)
}

#[cfg(test)]
mod tests {
    use super::*;

    use std::io::Write;
    use std::path::Path;
    use tempfile::NamedTempFile;
    use x509_parser::extensions::GeneralName;

    #[test]
    fn create_ca_with_path_len_set() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .pathlen(0)
            .build_and_self_sign()
            .unwrap();
        assert_eq!(ca.x509.pathlen(), Some(0));
    }

    #[test]
    fn create_ca_with_no_path_len_set() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        assert_eq!(ca.x509.pathlen(), None);
    }

    #[test]
    fn key_usage_is_marked_critical() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let leaf = CertBuilder::new()
            .common_name("leaf")
            .key_usage([Usage::certsign].into_iter().collect())
            .build_and_sign(&ca)
            .unwrap();
        let der = leaf.x509.to_der().unwrap();
        let (_, parsed) = parse_x509_certificate(&der).unwrap();

        let ku = parsed
            .tbs_certificate
            .extensions()
            .iter()
            .find(|ext| matches!(ext.parsed_extension(), ParsedExtension::KeyUsage(_)))
            .expect("certificate should carry a KeyUsage extension");

        assert!(ku.critical, "KeyUsage must be critical (RFC 5280 §4.2.1.3)");
    }

    #[test]
    fn extended_key_usage_is_not_marked_critical() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let leaf = CertBuilder::new()
            .common_name("leaf")
            .key_usage([Usage::serverauth].into_iter().collect())
            .build_and_sign(&ca)
            .unwrap();
        let der = leaf.x509.to_der().unwrap();
        let (_, parsed) = parse_x509_certificate(&der).unwrap();

        let eku = parsed
            .tbs_certificate
            .extensions()
            .iter()
            .find(|ext| matches!(ext.parsed_extension(), ParsedExtension::ExtendedKeyUsage(_)))
            .expect("certificate should carry a ExtendedKeyUsage extension");

        assert!(!eku.critical, "Extened KeyUsage not critical by default");
    }

    #[test]
    fn san_names_should_be_added_correctly() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let leaf = CertBuilder::new()
            .common_name("leaf")
            .alternative_names(vec!["localhost", "127.0.0.1", "::1"])
            .key_usage([Usage::serverauth].into_iter().collect())
            .build_and_sign(&ca)
            .unwrap();
        let der = leaf.x509.to_der().unwrap();
        let (_, parsed) = parse_x509_certificate(&der).unwrap();
        let san = parsed
            .subject_alternative_name()
            .unwrap()
            .expect("leaf should carry a SubjectAltName extension");

        let mut dns: Vec<&str> = Vec::new();
        let mut ips: Vec<IpAddr> = Vec::new();
        for gn in &san.value.general_names {
            match gn {
                GeneralName::DNSName(name) => dns.push(name),
                GeneralName::IPAddress(bytes) => ips.push(match bytes.len() {
                    4 => IpAddr::from(<[u8; 4]>::try_from(*bytes).unwrap()),
                    16 => IpAddr::from(<[u8; 16]>::try_from(*bytes).unwrap()),
                    n => panic!("iPAddress SAN must be 4 or 16 octets, got {n}"),
                }),
                other => panic!("unexpected GeneralName in SAN: {other:?}"),
            }
        }

        // `alternative_names` is a HashSet — sort before comparing or this flakes.
        dns.sort_unstable();
        ips.sort_unstable();

        // The CN is copied into the SAN list, so "leaf" appears alongside the
        // explicitly requested names.
        assert_eq!(dns, ["leaf", "localhost"]);
        assert_eq!(
            ips,
            [
                "127.0.0.1".parse::<IpAddr>().unwrap(),
                "::1".parse::<IpAddr>().unwrap()
            ]
        )
    }

    #[test]
    fn common_name_listed_in_alternative_names_is_not_duplicated() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        // The CN is also given explicitly — it must still appear exactly once.
        let leaf = CertBuilder::new()
            .common_name("example.com")
            .alternative_names(vec!["example.com", "www.example.com"])
            .key_usage([Usage::serverauth].into_iter().collect())
            .build_and_sign(&ca)
            .unwrap();

        let der = leaf.x509.to_der().unwrap();
        let (_, parsed) = parse_x509_certificate(&der).unwrap();
        let san = parsed
            .subject_alternative_name()
            .unwrap()
            .expect("leaf should carry a SubjectAltName");

        let mut dns: Vec<&str> = san
            .value
            .general_names
            .iter()
            .filter_map(|gn| match gn {
                GeneralName::DNSName(n) => Some(*n),
                _ => None,
            })
            .collect();
        dns.sort_unstable();

        assert_eq!(dns, ["example.com", "www.example.com"]);
    }

    #[test]
    fn incomplete_chain_without_root_is_rejected() {
        let ca = CertBuilder::new()
            .common_name("Root")
            .is_ca(true)
            .pathlen(2)
            .build_and_self_sign()
            .unwrap();
        let inter = CertBuilder::new()
            .common_name("Inter")
            .is_ca(true)
            .pathlen(1)
            .build_and_sign_with_chain(&ca, &[])
            .unwrap();

        // sign with `inter` but forget to pass its chain → top of chain is `inter`,
        // which is not self-signed → reject
        let err = CertBuilder::new()
            .common_name("Sub")
            .is_ca(true)
            .pathlen(0)
            .build_and_sign_with_chain(&inter, &[])
            .expect_err("incomplete chain (missing root) must be rejected");
        assert!(
            err.to_string().contains("Could not find self signed root"),
            "got: {err}"
        );
    }

    #[test]
    fn unlimited_root_can_issue_ca() {
        let root = CertBuilder::new()
            .common_name("Unlimited Root")
            .is_ca(true) // note: no .pathlen() → None / unlimited
            .build_and_self_sign()
            .unwrap();
        assert_eq!(root.x509.pathlen(), None);

        // budget is None → no ceiling; even a large declared pathLen is fine
        let inter = CertBuilder::new()
            .common_name("Inter")
            .is_ca(true)
            .pathlen(5)
            .build_and_sign_with_chain(&root, &[])
            .unwrap();
        assert_eq!(inter.x509.pathlen(), Some(5));
    }

    #[test]
    fn create_cert_chain_and_verify() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .pathlen(1)
            .build_and_self_sign()
            .unwrap();
        let chain: Vec<&Certificate> = Vec::new();
        let inter_ca = CertBuilder::new()
            .common_name("My Test inter Ca")
            .is_ca(true)
            .pathlen(0)
            .build_and_sign_with_chain(&ca, chain.as_slice())
            .unwrap();
        let leaf = CertBuilder::new()
            .common_name("My Test leaf")
            .build_and_sign(&inter_ca)
            .unwrap();
        assert_eq!(ca.x509.pathlen(), Some(1));
        assert_eq!(leaf.x509.pathlen(), None);
        assert!(verify_cert(&leaf.x509, &ca.x509, vec![&inter_ca.x509]).unwrap());
    }

    #[test]
    fn create_ca_cert_chain_and_verify() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .pathlen(2)
            .build_and_self_sign()
            .unwrap();
        let chain: Vec<&Certificate> = Vec::new();
        let inter_ca = CertBuilder::new()
            .common_name("My Test inter Ca")
            .is_ca(true)
            .pathlen(1)
            .build_and_sign_with_chain(&ca, chain.as_slice())
            .unwrap();
        let leaf = CertBuilder::new()
            .common_name("leaf ca")
            .is_ca(true)
            .pathlen(0)
            .build_and_sign_with_chain(&inter_ca, &[&ca])
            .unwrap();

        assert_eq!(leaf.x509.pathlen(), Some(0));
    }

    #[test]
    fn can_not_create_ca_cert_chain_with_wrong_intermediate_ca_path() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .pathlen(2)
            .build_and_self_sign()
            .unwrap();
        let chain: Vec<&Certificate> = Vec::new();
        let inter_ca = CertBuilder::new()
            .common_name("My Test inter Ca")
            .is_ca(true)
            .pathlen(0)
            .build_and_sign_with_chain(&ca, chain.as_slice())
            .unwrap();
        let err = CertBuilder::new()
            .common_name("leaf ca")
            .is_ca(true)
            .pathlen(0)
            .build_and_sign_with_chain(&inter_ca, &[&ca])
            .expect_err("");

        assert!(
            err.to_string()
                .contains("signer's path length budget is exhausted; cannot issue a CA"),
            "signer's path length budget is exhausted; cannot issue a CA got: {err}"
        );
    }

    #[test]
    fn root_ca_have_one_path_length_and_can_not_sign_ca() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .pathlen(1)
            .build_and_self_sign()
            .unwrap();

        let chain: Vec<&Certificate> = Vec::new();

        // A user mistake: an intermediate claiming pathlen(1) under a root that only
        // permits one CA below it. Must be rejected at issuance.
        let err = CertBuilder::new()
            .common_name("My Test inter Ca")
            .is_ca(true)
            .pathlen(1)
            .build_and_sign_with_chain(&ca, chain.as_slice())
            .expect_err("inter CA with pathlen(1) under root pathlen(1) must be rejected");

        assert!(
            err.to_string()
                .contains("requested pathLen exceeds what the signer's chain permits"),
            "expected a pathLen-exceeds error, got: {err}"
        );
    }

    #[test]
    fn build_and_sign_without_signer_private_key_errors_not_panics() {
        let ca = CertBuilder::new()
            .common_name("My Test Ca")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let keyless_ca = Certificate {
            x509: ca.x509.clone(),
            pkey: None,
        };

        let err = CertBuilder::new()
            .common_name("leaf")
            .build_and_sign(&keyless_ca)
            .expect_err("signing with a key-less CA must return an error, not panic");
        assert!(
            err.to_string().contains("private key"),
            "expected a missing-private-key error, got: {err}"
        );
    }

    #[test]
    fn ensure_that_supplied_private_key_is_used() {
        let ca_one = CertBuilder::new()
            .common_name("My Test Ca1")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let ca_two = CertBuilder::new()
            .common_name("My Test Ca2")
            .is_ca(true)
            .private_key(ca_one.pkey.unwrap())
            .build_and_self_sign()
            .unwrap();
        assert_eq!(
            ca_one
                .x509
                .public_key()
                .unwrap()
                .public_key_to_der()
                .unwrap(),
            ca_two
                .x509
                .public_key()
                .unwrap()
                .public_key_to_der()
                .unwrap()
        )
    }
    #[test]
    fn save_certificate() {
        let ca = CertBuilder::new().common_name("My Test Ca").is_ca(true);
        match ca.build_and_self_sign() {
            Ok(cert) => {
                let output_file = NamedTempFile::new().unwrap();
                let full_path = output_file.path();
                let parent_dir: &Path = full_path.parent().unwrap();
                let file_name: &str = full_path.file_name().unwrap().to_str().unwrap();
                cert.save(parent_dir, file_name)
                    .expect("Failed to save certificate and key");
                let written_file_path = parent_dir.join(file_name);
                assert!(written_file_path.exists(), "File was not created");
            }
            Err(_) => panic!("Failed to creat certificate"),
        }
    }

    #[test]
    fn read_certificate_and_key_from_file() {
        let cert_pem = b"-----BEGIN CERTIFICATE-----
MIICiDCCAemgAwIBAgIUO3+y1WZPRRNs8dmZZTUHMj6TdiowCgYIKoZIzj0EAwQw
WzETMBEGA1UEAwwKTXkgVGVzdCBDYTELMAkGA1UEBhMCU0UxEjAQBgNVBAgMCVN0
b2NraG9sbTESMBAGA1UEBwwJU3RvY2tob2xtMQ8wDQYDVQQKDAZteSBvcmcwHhcN
MjUwNzA4MTExMzI2WhcNMjYwNzA4MTExMzI2WjBbMRMwEQYDVQQDDApNeSBUZXN0
IENhMQswCQYDVQQGEwJTRTESMBAGA1UECAwJU3RvY2tob2xtMRIwEAYDVQQHDAlT
dG9ja2hvbG0xDzANBgNVBAoMBm15IG9yZzCBmzAQBgcqhkjOPQIBBgUrgQQAIwOB
hgAEADZXcQK2ihgVTJeGx5FKm1x+R+ivygIvMnkv03faq1LpLU3doKX38DEO/cSW
Ev5u+kcjspXeeDPhqJFC8rRAz4awAMk+D0mXEms7xpFPh0HmI6NNcJc5eJ/8ZsEJ
GH1a34y0Yn6259gqlwAh2Eh9Nx1579BAanRr8lr+n1tZ09T/9AQho0gwRjAMBgNV
HRMEBTADAQH/MAsGA1UdDwQEAwIBBjApBgNVHREEIjAgggZjYS5jb22CCnd3dy5j
YS5jb22CCk15IFRlc3QgQ2EwCgYIKoZIzj0EAwQDgYwAMIGIAkIB8NVUgRIuNXmJ
cLCQ74Ub7Dqo71S0+iCrZF1YyJA8/q65aqMCT54k5Yx7HRBUUVHbCEpDXRqGPsIH
frfe5OmS3qICQgDBn07o0CcyfoSEd+Xoj2+/RBuU0vo9lUP7TKj7tssBxzEQFoxX
eE1qT98UIe78FZ+zqjwZTN9MCSsatuim6pXvOA==
-----END CERTIFICATE-----";

        let key_pem = b"-----BEGIN PRIVATE KEY-----
MIHuAgEAMBAGByqGSM49AgEGBSuBBAAjBIHWMIHTAgEBBEIAgvZTeQgGysadAX0r
aZB5Lk4vjHy5iVuKdvcGdYt9NBvYx+Ib3Uk7vqMag7M1jyHL0Xf9uNtT2mxBmzBG
3CF+EgOhgYkDgYYABAA2V3ECtooYFUyXhseRSptcfkfor8oCLzJ5L9N32qtS6S1N
3aCl9/AxDv3ElhL+bvpHI7KV3ngz4aiRQvK0QM+GsADJPg9JlxJrO8aRT4dB5iOj
TXCXOXif/GbBCRh9Wt+MtGJ+tufYKpcAIdhIfTcdee/QQGp0a/Ja/p9bWdPU//QE
IQ==
-----END PRIVATE KEY-----";

        let mut cert_file = NamedTempFile::new().expect("Failed to create temp cert file");
        let mut key_file = NamedTempFile::new().expect("Failed to create temp key file");

        cert_file.write_all(cert_pem).expect("Failed to write cert");
        key_file.write_all(key_pem).expect("Failed to write key");

        let result = Certificate::load_cert_and_key(cert_file.path(), key_file.path());
        assert!(
            result.is_ok(),
            "Failed to load cert and key: {:?}",
            result.err()
        );
    }

    #[test]
    fn load_cert_reads_cert_without_key() {
        use std::io::Write;
        // Setup: a self-signed cert written to a temp PEM file.
        let cert = CertBuilder::new()
            .common_name("load-cert-test")
            .is_ca(true)
            .build_and_self_sign()
            .unwrap();
        let mut file = tempfile::NamedTempFile::new().unwrap();
        file.write_all(&cert.x509.to_pem().unwrap()).unwrap();

        // Invoke.
        let loaded = Certificate::load_cert(file.path()).unwrap();

        // Expect: no private key, and the subject survived the round-trip.
        assert!(
            loaded.pkey.is_none(),
            "load_cert must not carry a private key"
        );
        assert_eq!(
            loaded
                .x509
                .subject_name()
                .try_cmp(cert.x509.subject_name())
                .unwrap(),
            std::cmp::Ordering::Equal,
        );
    }

    #[test]
    fn load_cert_missing_file_errors() {
        let err = Certificate::load_cert("/no/such/file/here.pem").expect_err("msg");
        assert!(
            err.to_string().contains("No such file or directory"),
            "No such file or directory, got: {err}"
        );
    }
}