bhx5chain

This library provides functionality for working with an ordered array of X.509 certificates as defined in RFC 9360 for use in other The Blockhouse Technology Limited (TBTL) projects.

Details

The primary way to use this library is to construct an X5Chain struct using the Builder struct. There is also JwtX5Chain for working with JWTs.

For additional documentation & examples, take a look at the crate documentation.

Changelog

The changelog can be found here.

License

^{Licensed under GNU Affero General Public License, Version 3.}

lib.rs:

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");