Decoupled crypto backends (the rest) (#428)

* support wasm

* upgrade dependency

* remove ring

* fix wasm test failed

* fix cargo format

* change ci branch

* fix ci

* fix ci

* fix ci

* remove ci branch

* fix examples ed25519 test failed

* Next version

* Remove downgrade steps

* feat(encoder): Add encoder builder

* feat(encoder): Convert to dynamic dispatch

* feat(decoder): Create decoder

* test: Get HMAC tests passing

* docs: Neaten up docstrings

* feat(crypto): Implement JwtSigner and JwtVerifier for aws-lc-rs

* feat: Remove builder style implementation

* feat: Use original encoding and decoding key structs

* feat(crypto): Add RSA family

* Add ECDSA via AWS-LC

This is following the existing scheme established in hmac & rsa.

* Implement EdDSA through AWS-LC

* Verify ES and ED keys are of the right type

* Implement RSA-PSS via AWS-LC

* Implement EdDSA via RustCrypto/Dalek

* Implement EcDSA through RustCrypto

* Implement RSA via RustCrypto

* Clean up optional dependencies

* Fix all test-breaking issues with the RustCrypto versions

* Re-add the crypto::{sign, verify} convenience functions

* Require at least one crypto backend to be enabled

* Ensure tests pass without use_pem feature as well

* Fix dependency features & clippy lints

* Reduce code duplication in crypto impls through macros

* Move try_get_hmac_secret directly into en-/decoding key impls

* Re-enable the HMAC sign & verify test cases

* Uncomment the algorithm matching in verify_signature again

This was commented out with the note that it wasn't "captured anywhere,"
presumably in tests, but is present in similar form in the
pre-decoupling version of the code.

* Inline _encode and _decode

They had todos for docstrings, and I realized they're single-use and
should probably not be exposed publicly anyway.

* Fix some docstring typos

* Don't default to a crypto backend

In most situations AWS-LC is the better backend, but it's not available
on all platforms, for example WASM. Explicitly asking the user to pick a
backend is also more future-proof.

* Explicitly annotate an implicit lifetime

This is fixing a Clippy complaint.

* Enable getrandom/js for WASM tests in CI

* Update readme & changelog for version 10

* Run CI on newer versions of Ubuntu

Running most of them on the latest version, at the moment 24.04, except
for the test run that's pinned to Rust 1.73, which is pinned to 24.04.

* Bump the MSRV to 1.85

Some dependencies are now on the 2024 edition.

---------

Co-authored-by: 陈圳佳 <[email protected]>
Co-authored-by: Vincent Prouillet <[email protected]>
Co-authored-by: Vincent Prouillet <[email protected]>
Co-authored-by: sidrubs <[email protected]>

Author: 4 people

.github/workflows/ci.yml

@@ -1,83 +1,86 @@
 name: ci
 on:
-  push:
-    branches:
-      - master
-  pull_request:
+    push:
+        branches:
+            - master
+    pull_request:
 
 jobs:
-  style:
-    name: Format
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: rustfmt
-      - name: Check format
-        run: cargo fmt --check
+    style:
+        name: Format
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: actions/checkout@v3
+            -   name: Install Rust
+                uses: dtolnay/rust-toolchain@stable
+                with:
+                    components: rustfmt
+            -   name: Check format
+                run: cargo fmt --check
 
-  clippy:
-    name: Clippy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-      - run: cargo clippy --all-targets --all-features -- -D warnings
+    clippy:
+        name: Clippy
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                backend: [ aws_lc_rs, rust_crypto ]
+        steps:
+            -   uses: actions/checkout@v3
+            -   uses: dtolnay/rust-toolchain@stable
+                with:
+                    components: clippy
+            -   run: cargo clippy --all-targets --features ${{ matrix.backend }} -- -D warnings
 
-  tests:
-    name: Tests
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        build: [pinned, stable, nightly]
-        include:
-          - build: pinned
-            os: ubuntu-20.04
-            rust: 1.73.0
-          - build: stable
-            os: ubuntu-20.04
-            rust: stable
-          - build: nightly
-            os: ubuntu-20.04
-            rust: nightly
-    steps:
-      - uses: actions/checkout@v3
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: ${{ matrix.rust }}
+    tests:
+        name: Tests
+        runs-on: ${{ matrix.os }}
+        strategy:
+            matrix:
+                build: [ pinned, stable, nightly ]
+                backend: [ aws_lc_rs, rust_crypto ]
+                include:
+                    -   build: pinned
+                        os: ubuntu-24.04
+                        rust: 1.85.0
+                    -   build: stable
+                        os: ubuntu-latest
+                        rust: stable
+                    -   build: nightly
+                        os: ubuntu-latest
+                        rust: nightly
+        steps:
+            -   uses: actions/checkout@v3
+            -   name: Install Rust
+                uses: dtolnay/rust-toolchain@master
+                with:
+                    toolchain: ${{ matrix.rust }}
 
-      - name: Build System Info
-        run: rustc --version
+            -   name: Build System Info
+                run: rustc --version
 
-      - name: Run tests default features
-        run: cargo test
+            -   name: Run tests default features
+                run: cargo test --features ${{ matrix.backend }}
 
-      - name: Run tests no features
-        run: cargo test --no-default-features
+            -   name: Run tests no features
+                run: cargo test --no-default-features --features ${{ matrix.backend }}
 
-  wasm:
-    name: Run tests in wasm
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: wasm32-unknown-unknown
+    wasm:
+        name: Run tests in wasm
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: actions/checkout@v3
+            -   name: Install Rust
+                uses: dtolnay/rust-toolchain@stable
+                with:
+                    targets: wasm32-unknown-unknown
 
-      - uses: actions/setup-node@v4
+            -   uses: actions/setup-node@v4
 
-      - name: Install wasm-pack
-        run: cargo install wasm-pack
+            -   name: Install wasm-pack
+                run: cargo install wasm-pack
 
-      - name: Run tests default features
-        run: wasm-pack test --node
-
-      - name: Run tests no features
-        run: wasm-pack test --node --no-default-features
+            -   name: Run tests default features
+                run: wasm-pack test --node --features rust_crypto,getrandom/js
 
+            -   name: Run tests no features
+                run: wasm-pack test --node --no-default-features --features rust_crypto,getrandom/js

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 10.0.0 (unreleased)
+
+- Introduce alternative crypto backends (AWS-LC, RustCrypto)
+
 ## 9.3.1 (2024-02-06)
 
 - Update base64

Cargo.toml

@@ -17,26 +17,39 @@ include = [
     "README.md",
     "CHANGELOG.md",
 ]
-rust-version = "1.73.0"
+rust-version = "1.85.0"
 
 [dependencies]
-serde_json = "1.0"
-serde = { version = "1.0", features = ["derive"] }
 base64 = "0.22"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+signature = { version = "2.2.0", features = ["std"] }
+
 # For PEM decoding
 pem = { version = "3", optional = true }
 simple_asn1 = { version = "0.6", optional = true }
 
-[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-ring = { version = "0.17.4", features = ["std"] }
+# "aws_lc_rs" feature
+aws-lc-rs = { version = "1.10.0", optional = true }
+
+# "rust_crypto" feature
+ed25519-dalek = { version = "2.1.1", optional = true, features = ["pkcs8"] }
+hmac = { version = "0.12.1", optional = true }
+p256 = { version = "0.13.2", optional = true, features = ["ecdsa"] }
+p384 = { version = "0.13.0", optional = true, features = ["ecdsa"] }
+rand = { version = "0.8.5", optional = true, features = ["std"], default-features = false }
+rsa = { version = "0.9.6", optional = true }
+sha2 = { version = "0.10.7", optional = true, features = ["oid"] }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 js-sys = "0.3"
-ring = { version = "0.17.4", features = ["std", "wasm32_unknown_unknown_js"] }
+getrandom = "0.2"
 
 [dev-dependencies]
 wasm-bindgen-test = "0.3.1"
-
+ed25519-dalek = { version = "2.1.1", features = ["pkcs8", "rand_core"] }
+rand = { version = "0.8.5", features = ["std"], default-features = false }
+rand_core = "0.6.4"
 [target.'cfg(not(all(target_arch = "wasm32", not(any(target_os = "emscripten", target_os = "wasi")))))'.dev-dependencies]
 # For the custom time example
 time = "0.3"
@@ -50,6 +63,8 @@ criterion = { version = "0.4", default-features = false }
 [features]
 default = ["use_pem"]
 use_pem = ["pem", "simple_asn1"]
+rust_crypto = ["ed25519-dalek", "hmac", "p256", "p384", "rand", "rsa", "sha2"]
+aws_lc_rs = ["aws-lc-rs"]
 
 [[bench]]
 name = "jwt"

README.md

@@ -8,12 +8,14 @@ See [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) for more inf
 Add the following to Cargo.toml:
 
 ```toml
-jsonwebtoken = "9"
+jsonwebtoken = { version = "10", features = ["aws_lc_rs"] }
 # If you do not need pem decoding, you can disable the default feature `use_pem` that way:
-# jsonwebtoken = {version = "9", default-features = false }
+# jsonwebtoken = {version = "10", default-features = false, features = ["aws_lc_rs"] }
 serde = {version = "1.0", features = ["derive"] }
 ```
 
+Two crypto backends are available via features, `aws_lc_rs` and `rust_crypto`, exactly one of which must be enabled.
+
 The minimum required Rust version (MSRV) is specified in the `rust-version` field in this project's [Cargo.toml](Cargo.toml).
 
 ## Algorithms

examples/custom_time.rs

@@ -1,7 +1,8 @@
-use jsonwebtoken::{Algorithm, DecodingKey, EncodingKey, Header, Validation};
 use serde::{Deserialize, Serialize};
 use time::{Duration, OffsetDateTime};
 
+use jsonwebtoken::{Algorithm, DecodingKey, EncodingKey, Header, Validation};
+
 const SECRET: &str = "some-secret";
 
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
@@ -60,13 +61,15 @@ mod jwt_numeric_date {
 
     #[cfg(test)]
     mod tests {
-        const EXPECTED_TOKEN: &str = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJDdXN0b20gT2Zmc2V0RGF0ZVRpbWUgc2VyL2RlIiwiaWF0IjowLCJleHAiOjMyNTAzNjgwMDAwfQ.BcPipupP9oIV6uFRI6Acn7FMLws_wA3oo6CrfeFF3Gg";
+        use time::{Duration, OffsetDateTime};
 
-        use super::super::{Claims, SECRET};
         use jsonwebtoken::{
             decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation,
         };
-        use time::{Duration, OffsetDateTime};
+
+        use super::super::{Claims, SECRET};
+
+        const EXPECTED_TOKEN: &str = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJDdXN0b20gT2Zmc2V0RGF0ZVRpbWUgc2VyL2RlIiwiaWF0IjowLCJleHAiOjMyNTAzNjgwMDAwfQ.BcPipupP9oIV6uFRI6Acn7FMLws_wA3oo6CrfeFF3Gg";
 
         #[test]
         fn round_trip() {

examples/ed25519.rs

@@ -1,8 +1,11 @@
+use ed25519_dalek::pkcs8::EncodePrivateKey;
+use ed25519_dalek::SigningKey;
+use rand_core::OsRng;
+use serde::{Deserialize, Serialize};
+
 use jsonwebtoken::{
     decode, encode, get_current_timestamp, Algorithm, DecodingKey, EncodingKey, Validation,
 };
-use ring::signature::{Ed25519KeyPair, KeyPair};
-use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Claims {
@@ -11,11 +14,16 @@ pub struct Claims {
 }
 
 fn main() {
-    let doc = Ed25519KeyPair::generate_pkcs8(&ring::rand::SystemRandom::new()).unwrap();
-    let encoding_key = EncodingKey::from_ed_der(doc.as_ref());
+    let signing_key = SigningKey::generate(&mut OsRng);
+    let pkcs8 = signing_key.to_pkcs8_der().unwrap();
+    let pkcs8 = pkcs8.as_bytes();
+    // The `to_pkcs8_der` includes the public key, the first 48 bits are the private key.
+    let pkcs8 = &pkcs8[..48];
+    let encoding_key = EncodingKey::from_ed_der(pkcs8);
 
-    let pair = Ed25519KeyPair::from_pkcs8(doc.as_ref()).unwrap();
-    let decoding_key = DecodingKey::from_ed_der(pair.public_key().as_ref());
+    let verifying_key = signing_key.verifying_key();
+    let public_key = verifying_key.as_bytes();
+    let decoding_key = DecodingKey::from_ed_der(public_key);
 
     let claims = Claims { sub: "test".to_string(), exp: get_current_timestamp() };
 
@@ -37,11 +45,17 @@ mod tests {
 
     impl Jot {
         fn new() -> Jot {
-            let doc = Ed25519KeyPair::generate_pkcs8(&ring::rand::SystemRandom::new()).unwrap();
-            let encoding_key = EncodingKey::from_ed_der(doc.as_ref());
+            let signing_key = SigningKey::generate(&mut OsRng);
+            let pkcs8 = signing_key.to_pkcs8_der().unwrap();
+            let pkcs8 = pkcs8.as_bytes();
+            // The `to_pkcs8_der` includes the public key, the first 48 bits are the private key.
+            let pkcs8 = &pkcs8[..48];
+            let encoding_key = EncodingKey::from_ed_der(&pkcs8);
+
+            let verifying_key = signing_key.verifying_key();
+            let public_key = verifying_key.as_bytes();
+            let decoding_key = DecodingKey::from_ed_der(public_key);
 
-            let pair = Ed25519KeyPair::from_pkcs8(doc.as_ref()).unwrap();
-            let decoding_key = DecodingKey::from_ed_der(pair.public_key().as_ref());
             Jot { encoding_key, decoding_key }
         }
     }

examples/validation.rs

@@ -1,6 +1,7 @@
+use serde::{Deserialize, Serialize};
+
 use jsonwebtoken::errors::ErrorKind;
 use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};
-use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Serialize, Deserialize)]
 struct Claims {

src/algorithms.rs

@@ -1,7 +1,9 @@
-use crate::errors::{Error, ErrorKind, Result};
-use serde::{Deserialize, Serialize};
 use std::str::FromStr;
 
+use serde::{Deserialize, Serialize};
+
+use crate::errors::{Error, ErrorKind, Result};
+
 #[derive(Debug, Eq, PartialEq, Copy, Clone, Serialize, Deserialize)]
 pub(crate) enum AlgorithmFamily {
     Hmac,