Skip to content

Tools for manipulating JSON Web Tokens, JWS, JWE, and JWK in Rust

License

Notifications You must be signed in to change notification settings

wireapp/rusty-jwt-tools

Repository files navigation

Rusty JWT Tools

A collection of JWT utilities.

Wire logo

This repository is part of the source code of Wire. You can find more information at wire.com or by contacting [email protected].

You can find the published source code at github.com/wireapp/wire.

For licensing information, see the attached LICENSE file and the list of third-party licenses at wire.com/legal/licenses/.

No license is granted to the Wire trademark and its associated logos, all of which will continue to be owned exclusively by Wire Swiss GmbH. Any use of the Wire trademark and/or its associated logos is expressly prohibited without the express prior written consent of Wire Swiss GmbH.

Parts

  • acme: types that deal with ACME certificate enrollment
  • e2e-identity: implementation of the Wire end-to-end identity workflow, built on top of acme and jwt
  • ffi: Haskell bindings for rusty-jwt-tools, only used by wire-server
  • jwt: a collection of JWT utilities
  • x509-check: helpers for X509 certificate validation, only used by acme

Building

For the build requirements, look at the information in core-crypto repo.

Note

Building rusty-jwt-tools independently of core-crypto for Android targets is currently not supported due to missing configuration bits. However, the necessary bits are in core-crypto so one can build rusty-jwt-tools for Android targets as part of a core-crypto build.

Building is as simple as

cargo build

Testing

Install cargo-nextest if you haven't done so, it yields some substantial speedup. Also, it allows us to group tests easily and have custom settings for those groups (see .config/nextest.toml).

cargo install cargo-nextest

Make sure the docker daemon is running (this is needed because the test suite runs an OIDC provider inside a container).

Run tests:

cargo nextest run

Testing the Haskell FFI

Make sure you have Nix installed.

Enter the nix shell that should have all the Haskell tooling necessary for the test:

cd ffi
nix-shell

Then within the shell run:

cargo make hs-test

Git workflow

See core-crypto git workflow.

Publishing

No crates are published on crates.io or any other Rust crate registry. The only release artifacts are source archives on github.

Versioning

The versioning scheme used is SemVer AKA Semantic Versioning.

Making a new release

  1. Make a branch based on main to prepare for release (git checkout -b prepare-release/X.Y.Z)
  2. Update the version of all workspace members to X.Y.Z, including places that refer to them.
  3. Generate a fresh e2e-identity/README.md.test:
     cargo test --package wire-e2e-identity --test e2e demo_should_succeed
    
    If there are non-trivial differences between e2e-identity/README.md and the generated file, update e2e-identity/README.md and commit the changes.
  4. Generate the relevant changelog section:
    git cliff --bump --unreleased
    
    and add it to the top of CHANGELOG.md. Make sure the version number generated by git cliff matches the release version.
  5. If there are any release highlights, add them as the first subsection below release title:
    ## v0.10.0 - 2024-05-02
    
    ### Highlights
    
    - foo
    - bar
    - baz
  6. Push your prepare-release/X.Y.Z branch and create a PR for it
  7. Get it reviewed, then merge it into main and remove the prepare-release/X.Y.Z branch from the remote
  8. Now, pull your local main: git checkout main && git pull
  9. Create the release tag: git tag -s vX.Y.Z
  10. Push the new tag: git push origin tag vX.Y.Z
  11. Create a new release on github, copying the relevant section from CHANGELOG.md
  12. Voilà!