Expose cryptography backends via CryptoProvider #452

arckoor · 2025-10-17T14:55:48Z

Adds a CryptoProvider struct that allows replacing the built-in providers with something custom.
All the details from this implementation that could be considered "interesting" are stolen straight from rustls's CryptoProvider.

I've marked the new_signer, new_verifier and JWK functions from the two built in backends as pub, so you can do stuff like this:

fn new_signer(algorithm: &Algorithm, key: &EncodingKey) -> Result<Box<dyn JwtSigner>, Error> {
    let jwt_signer = match algorithm {
        Algorithm::EdDSA => Box::new(CustomEdDSASigner::new(key)?) as Box<dyn JwtSigner>,
        _ => jsonwebtoken::crypto::aws_lc::new_signer(algorithm, key)?,
    };

    Ok(jwt_signer)
}

i.e. overwrite just specific algorithms.

One area I'm a little unsure about is JwkUtils, 1) about the name and 2) about the Default implementation. The CryptoProvider::signer_ and CryptoProvider::verifier_factory functions are obviously mandatory for a custom provider, but not everyone uses JWK, so the default just uses dummy functions with unimplemented!().

arckoor · 2025-11-25T18:23:33Z

@Keats any chance of a review on this?

drusellers · 2025-12-02T16:30:59Z

Would this allow applications to use rustls rather than openssl?

arckoor · 2025-12-02T18:03:11Z

@drusellers As far as I know rustls doesn't implement the cryptography directly, rather it relies on other crates like ring, aws-lc-rs, rustcrypto, ...
So you can't really use rustls with this, but you can implement the cryptography with whatever backend you choose, be it openssl, botan, or something else entirely (this crate has aws-lc-rs and rustcrypto built in, using these doesn't require this PR)

Keats

I think this can be simplified

examples/custom_provider.rs

src/crypto/rust_crypto/mod.rs

Keats · 2025-12-08T14:00:21Z

src/crypto/macros.rs

+                Algorithm::PS384 => Box::new(rsa::RsaPss384Signer::new(key)?) as Box<dyn JwtSigner>,
+                Algorithm::PS512 => Box::new(rsa::RsaPss512Signer::new(key)?) as Box<dyn JwtSigner>,
+                Algorithm::EdDSA => Box::new(eddsa::EdDSASigner::new(key)?) as Box<dyn JwtSigner>,
+            };


that will get more complex if we start supporting some alg in some backend like #461

Keats · 2025-12-08T14:02:43Z

src/crypto/mod.rs

+    pub(crate) fn get_default() -> Option<&'static Arc<CryptoProvider>> {
+        PROCESS_DEFAULT_PROVIDER.get()
+    }
+}


Do we need that? We should be able to define a DEFAULT_PROVIDER using cargo features I think without needing the dance around that?

IIUC you mean that it automatically sets PROCESS_DEFAULT_PROVIDER to aws_lc::CryptoProvider if the aws feature is enabled? Yes that could be done, but similar to the JWK utility functions, that would mean you have to replace everything when you implement a custom provider, because otherwise if you select one of the built in features, you'd be locked into that provider.
This way you can implement whatever you want to, enable both aws and custom-provider, and fallback to aws for everything you haven't implemented.

My understanding of custom providers is that you do not want to add the rust-crypto/aws-lc dependencies? That feels a bit awkward otherwise

I feel that way, yes, others may not, I do not know. I did it this way because rustls did it this way, but I can change it if you want me to.

All that said while it could be assigned automatically for the rust_crypto and aws_lc_rs features, it still needs to provide a set method for outside crypto providers, and I'm honestly not sure how to do it any other way.

Unless you want a

#[cfg(feature = "custom-provider")] static PROCESS_DEFAULT_PROVIDER: OnceLock<Arc<CryptoProvider>> = OnceLock::new(); #[cfg(not(feature = "custom-provider")] # assign from crate features

which I personally think is pretty ugly.

So the way i was thinking about it is that people would create crates like jsonwebtoken-ring, jsonwebtoken-botan that are self contained

I'm not a fan of that to be honest. I can get behind separate crates as "companion crates" for jsonwebtoken, but doing a passthrough crate is imo a bad idea.
If my project requires two crates that both depend on jsonwebtoken, but use different implementations, i.e. jsonwebtoken-botan and jsonwebtoken-ring, I need to compile two crypto backends, and more importantly I need to trust two crypto backends.

I'd much rather they both require the base jsonwebtoken, and let me select the crypto provider at my crate level, be it a builtin one or one of the custom ones.

I'm not familiar with that pattern of selecting providers like apparently rustls does.

If my project requires two crates that both depend on jsonwebtoken, but use different implementations, i.e. jsonwebtoken-botan and jsonwebtoken-ring, I need to compile two crypto backends, and more importantly I need to trust two crypto backends.
I'd much rather they both require the base jsonwebtoken, and let me select the crypto provider at my crate level, be it a builtin one or one of the custom ones.

What does it look like from the pov of let's say jsonwebtoken-botan implementer and user?

As the implementer, you define your own crypto provider, and expose it somewhere in your crate.
As a user, you add both jsonwebtoken and jsonwebtoken-botan to your dependencies, and install the provider.
And then it just works.

This should be feature of power user, not regular user.
Most people prefer to add jsonbwebtoken and it just works
It is bug that rustls require you to install specific backend when both aws-lc and ring are enabled as features

The best user experience if we define following logic:

If user installed provider, return it

Otherwise return following in order of features combo:

If both rust-crypto and aws-lc defined then return awc-lc

If aws-lc defined return aws-lc

If rust-crypto defined then return rust-cryptop

src/decoding.rs

arckoor · 2025-12-08T22:01:06Z

@Keats I made the JWK functions private after all. For the PROCESS_DEFAULT_PROVIDER I still think this is the best way to do it, so I left it as is. I also removed the custom-provider feature, because it wasn't really doing anything anymore after making all the things pub / adding getters, so now you users just select neither of the built-in providers.

In regards to the macro, I also left it as is, if #461 goes through and does gate the implementation itself behind a feature, I guess the best would be to remove the macro and write the functions by hand for each built-in provider.

As for the example, I used the botan-rs crate, though I'm not confident you'll like it, it does force devs (and notably CI) to compile botan from source everytime.
That said, I chose it because 1) rust_crypto and aws_ls_rs are already here, and I didn't just want to duplicate the code 2) ring still seems to be unmaintained 3) openssl you have to compile as well and 4) I'm not aware of other solid options.
I feel it might be best to just duplicate the rust_crypto EdDSA implementation for the example, but then I don't know how useful the example is.
A different way to do it would be to introduce an internal __custom_provider_example = [dep:botan] feature, but that doesn't sound too great either :/

arckoor · 2025-12-14T00:33:09Z

src/crypto/mod.rs

+    pub extract_ec_public_key_coordinates:
+        fn(&[u8], Algorithm) -> Result<(EllipticCurve, Vec<u8>, Vec<u8>)>,
+    /// Given some data and a name of a hash function, compute hash_function(data)
+    pub compute_digest: fn(&[u8], ThumbprintHash) -> Vec<u8>,


Seems I forgot to bring this up before, but it would really be great if we could do a breaking change to turn this into Result<Vec<u8>>. Everything else lets you return an error should it happen in your custom provider (e.g. botan can technically error here, because it does go through an FFI, and while it shouldn't error, I still need to call unwrap here)

DoumanAsh

I left some comments how to implement it better and simplify provider logic
I think it would be also great to have NOOP provider implementation to be used by default instead of relying on Option to reduce indirection

src/crypto/macros.rs

DoumanAsh · 2025-12-18T22:36:21Z

src/crypto/mod.rs

+
+    use super::CryptoProvider;
+
+    static PROCESS_DEFAULT_PROVIDER: OnceLock<Arc<CryptoProvider>> = OnceLock::new();


Why would you use Arc if you anyway should create provider as static once?
It would be the best to just put it behind &'static CryptoProvider

Example
https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=094ee9e4b95e9d87e1651a4511db4d51

DoumanAsh · 2025-12-18T22:39:23Z

src/crypto/mod.rs

+    pub(crate) fn get_default() -> Option<&'static Arc<CryptoProvider>> {
+        PROCESS_DEFAULT_PROVIDER.get()
+    }
+}


This should be feature of power user, not regular user.
Most people prefer to add jsonbwebtoken and it just works
It is bug that rustls require you to install specific backend when both aws-lc and ring are enabled as features

The best user experience if we define following logic:

If user installed provider, return it

Otherwise return following in order of features combo:

If both rust-crypto and aws-lc defined then return awc-lc

If aws-lc defined return aws-lc

If rust-crypto defined then return rust-cryptop

DoumanAsh · 2025-12-18T22:41:14Z

src/crypto/mod.rs

+
+    /// Get the default if it has been set yet, or determine one from the crate features if possible.
+    pub(crate) fn get_default_or_install_from_crate_features() -> &'static Arc<Self> {
+        if let Some(provider) = Self::get_default() {


You should encapsulate it inside where you use OnceLock to get benefit of (it is optimized for happy path)
https://doc.rust-lang.org/std/sync/struct.OnceLock.html#method.get_or_init

This can be very simply implemented like this

static PROVIDER: OnceLock<&'static CryptoProvider> = OnceLock::new(); pub fn install_provider(provider: &'static CryptoProvider) -> Result<(), &'static CryptoProvider> { PROVIDER.set(provider) } pub(crate) fn get_default_provider() -> &'static CryptoProvider { #[cfg(all(feature = "rust_crypto", not(feature = "aws_lc_rs")))] pub static DEFAULT: CryptoProvider = rust_crypto::DEFAULT_PROVIDER; #[cfg(feature = "aws_lc_rs")] pub static DEFAULT: CryptoProvider = rust_crypto::DEFAULT_PROVIDER; #[cfg(all(not(feature = "rust_crypto"), not(feature = "aws_lc_rs")))] pub static DEFAULT: CryptoProvider = NOOP_PROVIDER; //create it return &DEFAULT; } pub(crate) fn get_default_or_install() -> &'static CryptoProvider { LOCK.get_or_nit(get_default_provider) }

Note that all these if/else branches will have big impact as you introduce too much checks for what could be simplified quite easily

arckoor · 2025-12-18T23:01:09Z

@DoumanAsh I can sympathize with most of the comments, and will try them out soon-ish. What I don't sympathize with is returning a default provider when both features are enabled. If there is a default provider, it should be a default feature. Making cryptographic choices for the user that they might not know about is imo a very bad idea.

DoumanAsh · 2025-12-18T23:11:22Z

@arckoor This is user responsibility to install provider he wants use, if he doesn't want to install any, then user is fine with any. I suggest AWS-LC because it has FIPS mode by default, which makes it most reasonable choice
If user care, he would manually install provider always so I think it is reasonable tradeoff to ensure jsonwebtoken as library is always working and only panic if you do not install any provider or enable no crypto features

P.s. let me know if you need any help to get this PR ready, it would be nice to get jsonwebtoken into working state when both crypto features are enabled

P.s.s Please note that it is my personal opinion and has nothing to with author of the library so defer to Keats's approval to get this PR merged

Keats · 2025-12-19T08:15:46Z

I agree with @arckoor if several features are enabled in the tree but the user didn't pick. That's a one time choice for the user but for example aws-ls-rc doesn't work with WASM afaik so I would rather not pick the backend library without a clear input in case of conflict.

DoumanAsh · 2025-12-19T12:33:34Z

@Keats The problem is that feature can be enabled by your dependency, it can be alleviated by having NOOP backend so that library could encourage others not to enable features I guess, but if for some reason you accidentally enable both features, you have no way to diagnose it simply, so that's my concern

arckoor · 2025-12-20T00:33:57Z

@Keats oh joy, CI fails because of the botan use in the example. I don't know what other crypto lib to use, if you have any preference, please let me know. I can also copy paste code from one of the built in providers, or just remove the example entirely and e.g. point to my jsonwebtoken-botan repo, or something else entirely, whatever you think is best.

arckoor force-pushed the custom-provider branch from 4483fd7 to 370f904 Compare October 17, 2025 15:57

Keats mentioned this pull request Oct 19, 2025

Notable increase in transitive dependencies and of binary size between 9.3.1 and 10.1.0 #455

Closed

Keats requested changes Dec 8, 2025

View reviewed changes

arckoor added 2 commits December 8, 2025 22:51

Expose cryptography backends via CryptoProvider

b419984

remove custom-provider feature, make jwk utility functions private

3344881

arckoor force-pushed the custom-provider branch from 38698b3 to 3344881 Compare December 8, 2025 21:51

Export entire signature crate to prevent confusion for Error type

5940de1

Keats mentioned this pull request Dec 11, 2025

Consider bringing back ring #468

Closed

make more things public

a01397e

arckoor commented Dec 14, 2025

View reviewed changes

Keats mentioned this pull request Dec 18, 2025

Make crate work when two crypto backends are selected #471

Closed

DoumanAsh reviewed Dec 18, 2025

View reviewed changes


		use super::CryptoProvider;

		static PROCESS_DEFAULT_PROVIDER: OnceLock<Arc<CryptoProvider>> = OnceLock::new();

Expose cryptography backends via CryptoProvider #452

Are you sure you want to change the base?

Expose cryptography backends via CryptoProvider #452

Uh oh!

Conversation

arckoor commented Oct 17, 2025

Uh oh!

arckoor commented Nov 25, 2025

Uh oh!

drusellers commented Dec 2, 2025

Uh oh!

arckoor commented Dec 2, 2025

Uh oh!

Keats left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

arckoor commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DoumanAsh left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DoumanAsh Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arckoor commented Dec 18, 2025

Uh oh!

DoumanAsh commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Keats commented Dec 19, 2025

Uh oh!

DoumanAsh commented Dec 19, 2025

Uh oh!

arckoor commented Dec 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

arckoor commented Dec 8, 2025 •

edited

Loading

DoumanAsh left a comment •

edited

Loading

DoumanAsh Dec 18, 2025 •

edited

Loading

DoumanAsh commented Dec 18, 2025 •

edited

Loading