Crate bhx5chain 

This crate provides functions and types for working with an ordered array of X.509 certificates (x5chain) as defined in RFC 9360.

Details

The primary API this crate offers is the X5Chain struct.

We also have a JwtX5Chain type which should be used when working with JSON Web Token (JWT). This should only be treated as a “wrapper” type around X5Chain, and as such isn’t meant for any manipulation of the certificate chain itself.

Examples

Simple Use

You can construct the X5Chain directly if you have openssl::x509::X509 certificates. The following example assumes that is the case for *_certificate variables.

let x5chain = bhx5chain::X5Chain::new(vec![leaf_certificate, intermediary_certificate])
    .expect("valid x5chain");

let trust = bhx5chain::X509Trust::new(vec![trusted_root_certificate]);

x5chain
    .verify_against_trusted_roots(&trust)
    .expect("trusted x5chain");

Advanced Use

If you need to create multiple leaf certificates during the runtime but base the X5Chain on some intermediary certificates & private key, you could use the Builder. (Note that this is not a production-grade CA implementation.)

let intermediary_private_key = std::fs::read_to_string("path-to-intermediary-private-key.pem")
    .expect("read intermediary private key");
let intermediary_certificate = std::fs::read_to_string("path-to-intermediary-certificate.pem")
    .expect("read intermediary certificate");
let trusted_root_certificate = std::fs::read_to_string("path-to-root-certificate.pem")
    .expect("read trusted root certificate");

// Setup the builder for `x5chain`
let x5chain_builder = bhx5chain::Builder::new(
    &intermediary_private_key,
    &intermediary_certificate,
    &trusted_root_certificate,
)
.expect("create x5chain builder");

let leaf_public_key =
    std::fs::read_to_string("path-to-leaf-public-key.pem").expect("read leaf public key");

// Optionally set the VC Issuer Identifier.
let iss = iref::UriBuf::new("https://example.com/leaf".into()).unwrap();

// Complete the `x5chain`
let x5chain = x5chain_builder
    .generate_x5chain(&leaf_public_key, Some(&iss))
    .expect("generate x5chain");

Conversion Between X5Chain & JwtX5Chain

// Convert the `x5chain` into `JwtX5Chain` in order to serialize it in a JWT.
let jwt_x5chain: bhx5chain::JwtX5Chain = x5chain.try_into().expect("valid x5chain");

// Alternatively, after deserializing the `JwtX5Chain` out of JWT, convert to `X5Chain` type.
let x5chain: bhx5chain::X5Chain = jwt_x5chain.try_into().expect("valid x5chain");

Structs

Builder

Builder of X5Chain; essentially a lightweight intermediary certificate authority.

JwtX5Chain

X5Chain helper struct for working with JSON Web Token (JWT).

X5Chain

The x5chain as defined in RFC 9360.

X509Trust

A collection of X509 trusted root certificates.

Enums

Error

Error returned by the crate API.

Type Aliases

Result

The bherror::Result type with the error type of x5chain::Error, used throughout this crate.