X509Validator

X.509 certificate chain validator.

Overview

This library validates an X.509 certificate chain against a set of root certificates and a policy. This is an essential building block for a wide range of PKI applications. It ships with a default verifier and a number of built-in verifier policies.

This library is heavily inspired by, and follows the design of, the verifier from the swift-certificates library. Some pragmatic ideas and project structure have been taken from rustls.

Requirements

• Rust 1.88 or newer, edition 2024.

Installation

Add the dependency and pick a crypto backend:

x509-validator = { version = "0.3.0", features = ["aws_lc"] }

There is no default backend: without one of these features enabled, the crate compiles but verifies nothing. You can also provide your own by implementing SignatureVerifier — see the custom_crypto_backend example.

Example code

use x509_validator::rfc5280::RFC5280Policy;
use x509_validator::store::CertificateStore;
use x509_validator::Validator;
use x509_validator::rfc5280::Timestamp;
use x509_validator::{Certificate, FromDer};

fn example(root_der: &[u8], intermediate_der: &[u8], leaf_der: &[u8], now: Timestamp) {
    let parse = |der| Certificate::from_der(der).expect("parse").1;
    let (root, intermediate, leaf) = (parse(root_der), parse(intermediate_der), parse(leaf_der));

    // Roots are trusted a priori. Intermediates are only available to build
    // through — each still has to be signed by something leading back to a root.
    let roots = CertificateStore::from_iter([root]);
    let intermediates = CertificateStore::from_iter([intermediate]);

    let policy = RFC5280Policy::new(now);
    let validator = Validator::with_policy(roots, policy);

    match validator.validate_with_diagnostics(&leaf, &intermediates, &mut |_| {}) {
        Ok(chain) => {
            // Leaf first, root last.
            for cert in chain.iter() {
                println!("{}", cert.tbs_certificate.subject);
            }
        }
        Err(reasons) => {
            // Empty means no candidate chain reached a root, so the policy was
            // never asked.
            for reason in reasons {
                println!("rejected: {reason}");
            }
        }
    }
}

The closure is the diagnostic channel: chain building reports every issuer it considers and every candidate it discards through it. If you don't need any of that, call validate(&leaf, &intermediates) instead.

More are in examples:

cargo run -p x509-validator-examples --example webpki

Approach

Parsing is done by x509-parser.

Crypto is swappable via the feature flags above, or you can supply your own SignatureVerifier.

Policy is where the actual rules live. A ValidationPolicy receives each candidate chain and accepts or rejects it. The built-in ones:

Policies compose with the policy! macro, so a TLS client's checks read as one list:

use x509_validator::rfc5280::{EkuPolicy, RFC5280Policy, Timestamp};
use x509_validator::{ServerIdentityPolicy, policy};

fn tls_client_policy(now: Timestamp, hostname: &str) -> impl x509_validator::ValidationPolicy {
    policy! {
        RFC5280Policy::new(now);
        EkuPolicy::server_auth();
        ServerIdentityPolicy::new(Some(hostname), None)
    }
}

Benchmarks

Two crates, in x509-validator-bench:

• measure — Regression benchmarks.
• compare — Compare backends, parsers, other verifiers, and the Swift original across four groups (index).

Fuzzing

Four cargo-fuzz targets live in fuzz, covering parsing, chain validation, server identity matching and name constraints. They run on every pull request and nightly; see the fuzzing README to run them locally.

Contributing

Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the X509Validator project, and everyone taking part is expected to follow our Code of Conduct.

License

X509Validator is distributed under the following two licenses:

• Apache License version 2.0.
• MIT license.

These are included as LICENSE-APACHE and LICENSE-MIT respectively.
You may use this software under the terms of any of these licenses, at your option.