jose

JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT) library

https://github.com/frasertweedale/hs-jose

LTS Haskell 22.14:0.11
Stackage Nightly 2024-03-29:0.11
Latest on Hackage:0.11

See all snapshots jose appears in

Apache-2.0 licensed by Fraser Tweedale
Maintained by [email protected]
This version can be pinned in stack with:jose-0.11@sha256:bb915151f3a824538f346f8cf307a2c4c29909cbb3f35cdb628c490aa6b0d331,3980

jose - JSON Object Signing and Encryption & JWT (JSON Web Token)

jose is a Haskell implementation of JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT).

The JSON Web Signature (JWS; RFC 7515) implementation is complete. JSON Web Encryption (JWE; RFC 7516) is not yet implemented.

EdDSA signatures (RFC 8037) and secp256k1 signatures (RFC 8812) are supported.

JWK Thumbprint (RFC 7638) is supported.

Contributions are welcome.

Security

If you discover a security issue in this library, please email me the details, ideally with a proof of concept (frase @ frase.id.au ; PGP key).

Before reporting an issue, please note the following known vulnerabilities:

  • The ECDSA implementation is vulnerable to timing attacks and should therefore only be used for verification.

and the following known not-vulnerabilities:

Interoperability issues

The following known interoperability issues will not be addressed, so please do not open issues:

  • Some JOSE tools and libraries permit the use of short keys, in violation of the RFCs. This implementation rejects JWS or JWT objects minted with short keys, as required by the RFCs.

  • The Auth0 software produces objects with an invalid "x5t" parameter. The datum should be a base64url-encoded SHA-1 digest, but Auth0 produces a base64url-encoded hex-encoded SHA-1 digest. The object can be repaired (example) so that this library will admit it, unless the offending parameter is part of the JWS Protected Header in which case you are out of luck (until Auth0 bring their implementation into compliance).

  • JWKs with leading null bytes in the RSA "n" parameter (a violation of RFC 7518) have been seen in the wild. This library rejects nonconformant JWKs. If you know which programs/libraries produce such objects, please file bugs against them. It is straightforward to repair these keys: base64url-decode the offending parameter, drop the leading null byte, base64url-encode again then update the JSON object.

Contributing

Bug reports, patches, feature requests, code review, crypto review, examples and documentation are welcome.

If you are wondering about how or whether to implement some feature or fix, please open an issue where it can be discussed. I appreciate your efforts, but I do not wish such efforts to be misplaced.

To submit a patch, please use git send-email or open a pull request. Write a well formed commit message. If your patch is nontrivial, update the copyright notice at the top of the modified files.

Changes

Version 0.11 (2023-10-31)

  • Migrate to the crypton library ecosystem. crypton was a hard fork of cryptonite, which was no longer maintained. With this change, the minimum supported version of GHC increased to 8.8. There are no other notable changes in this release.

  • The v0.10 series is the last release series to support cryptonite. It will continue to receive important bug fixes until the end of 2024.

Version 0.10 (2022-09-01)

  • Introduce newtype JOSE e m a which behaves like ExceptT e m a but also has instance (MonadRandom m) => MonadRandom (JOSE e m). The orphan MonadRandom instances were removed. (#91)

  • Parameterise JWT over the claims data type. This is a cleaner mechanism to support applications that use additional claims beyond those registered by RFC 7519. unregisteredClaims and addClaim are deprecated and will be removed in a future release. (#39)

  • Add Ed448 and X448 support. (#74)

  • Add secp256k1 curve support (RFC 8812).

  • Added checkJWK :: (MonadError e m, AsError e) => JWK -> m (). This action performs some key usability checks. In particular it identifies too-small symmetric keys. (#46)

  • Removed QuickCheck instances. jose no longer depends on QuickCheck. (#106)

  • Removed orphan ToJSON and FromJSON instances for URI.

  • Fail signature verification when curve does not match algorithm. This is an additional defence against curve substitution attacks.

  • Improved error reporting when constructing a JWK from an X.509 certificate with ECDSA key.

  • Make compatible with mtl == 2.3.* (#107)

  • Make compatible with monad-time == 0.4

Older versions

See Git commit history