Crate bh_jws_utils

Expand description

This crate provides functions and types for working with JSON Web Signatures (JWS).

§Details

The primary way to use this library is via the JwtSigner and JwtVerifier traits, which provide functionality for signing JWTs and verifying signed JWTs. A default openssl backed implementation of these traits is available by using the openssl_impl::Es256Signer and openssl_impl::Es256Verifier structs which implement JwtSigner and JwtVerifier respectively. These implementations are available under the default feature openssl which can be disabled and replaced by a custom implementation.

A custom implementation must implement the Signer trait for signing JWKs, SignatureVerifier trait for verifying signatures and optionally the HasJwkKid trait if you need to access the JWK key id. The JwtSigner and JwtVerifier traits are implemented automatically for the custom implementation if the custom implementation implements the Signer and SignatureVerifier traits respectively.

§Examples

§Sign and verify a JWT

use bh_jws_utils::{json_object, Es256Signer, Es256Verifier, JwtSigner, JwtVerifier};

// Construct a new signer
let signer = Es256Signer::generate("dummy-kid".to_string()).unwrap();

// Construct a JWT
let dummy_jwt = json_object!({
   "sub": "1234567890",
   "name": "John Doe",
   "iat": 1516239022
});

// Sign the JWT
let signed_jwt = signer.sign_jwt(dummy_jwt).unwrap();

// Get the public JWK for verification
let public_jwk = signer.public_jwk().unwrap();

// Verify the JWT
let token: serde_json::Value = Es256Verifier
    .verify_jwt_signature(signed_jwt.as_str(), &public_jwk)
    .unwrap();

Re-exports§

pub use jwt;

Macros§

json_object: Helper macro with the same syntax as serde_json::json specialized for constructing JSON objects.

Structs§

EcJwkPrivate: Struct representing private JWK for keys which use elliptic curve algorithms It contains public JWK and a private key part d of JWK.
Es256Signer: Signer implementation supporting the ES256 algorithm (ECDSA using the P-256 curve and the SHA-256 hash function).
Es256Verifier: SignatureVerifier implementation supporting the ES256 algorithm (ECDSA using the P-256 curve and the SHA-256 hash function).
JwkSet: Models JWK Set. A JSON object that represents a set of JWKs.
SignerWithChain: Signer decorator with an X.509 certificate chain associated with the key pair.

Enums§

CryptoError: Cryptographic error
FormatError: Error in JWK format
SignatureError: Error in JWS signature
SigningAlgorithm: Signature algorithms approved for use in the context of EUDI.

Constants§

SIGNING_ALG_ES256: JWS "alg" header parameter value for digital signature algorithm ECDSA using P-256 and SHA-256, as specified in RFC7518.
SIGNING_ALG_ES384: JWS "alg" header parameter value for digital signature algorithm ECDSA using P-384 and SHA-384, as specified in RFC7518.
SIGNING_ALG_ES512: JWS "alg" header parameter value for digital signature algorithm ECDSA using P-521 and SHA-512, as specified in RFC7518.
SIGNING_ALG_PS256: JWS "alg" header parameter value for digital signature algorithm RSASSA-PSS using SHA-256 and MGF1 with SHA-256, as specified in RFC7518.
SIGNING_ALG_PS384: JWS "alg" header parameter value for digital signature algorithm RSASSA-PSS using SHA-384 and MGF1 with SHA-384, as specified in RFC7518.
SIGNING_ALG_PS512: JWS "alg" header parameter value for digital signature algorithm RSASSA-PSS using SHA-512 and MGF1 with SHA-512, as specified in RFC7518.

Traits§

HasJwkKid: Subtrait for Signer-s which have an associated JWK kid (Key ID) parameter. This is used to set the kid header parameter when signing a JWT.
HasX5Chain: Subtrait for Signer-s which have an associated x5chain.
JwtSigner: An external backend capable of signing JWTs.
JwtVerifier: An external backend capable of verifying the signatures of JWTs.
SignatureVerifier: An external backend for signature verification, to be used for verifying JWS signatures.
Signer: An external signing backend, to be used for computing a JWS signature.

Functions§

base64_url_encode: Returns the base64url-encoded string of the given input.
construct_jws_payload: Create payload for a JWS, given its header and claims.
ec_public_affine_coords_to_jwk: Constructs the JwkPublic from the coordinates of the public ECDSA key using P-256 curve.
openssl_ec_pub_key_to_jwk: Construct a JWK JSON object for provided public key. Note: only ECDSA keys using P-256 curve are supported!
public_jwk_from_x5chain_leaf: Retrieve public JWK from the provided x5chain certificate chain leaf.

Type Aliases§

BoxError: Type alias for a boxed error.
Coordinate: A 32-byte coordinate for the elliptic curve.
Es256SignerWithChain: Signer implementation supporting the ES256 algorithm (ECDSA using the P-256 curve and the SHA-256 hash function). This is a wrapper over Es256Signer that adds support for producing X5Chain.
JwkPublic: A JSON object meant to represent a public JWK.