Google GitGoogle Git
Sign in
third-party-mirror/benmcollins/libjwt/f4a536fe70aa37e454e4b2ead3b01281f1fe0f40
commit
f4a536fe70aa37e454e4b2ead3b01281f1fe0f40
[log]
author
Ben Collins <bcollins@libjwt.io>
Thu Jun 18 03:51:15 2026 -0400
committer
Ben Collins <bcollins@libjwt.io>
Thu Jun 18 03:51:15 2026 -0400
tree
8929f5f8d0a2c745224dfc18bae0817715167f99
parent
86cedec34cdfd10068ed5608b367985902259158 [diff]
jwt: route key operations to the backend that parsed the key

A jwk_item is bound to the crypto backend active when its JWK was parsed
(item->provider). Previously, signing/verifying or JWE-encrypting with that
key under a DIFFERENT active backend failed ("Key is not compatible" on
OpenSSL/MbedTLS; GnuTLS silently re-imported from the JWK JSON).

Add jwt_item_ops(), which resolves a key's origin backend from the ops
registry, and dispatch the asymmetric key operations through it: sign/verify
(jwt.c) and the JWE ECDH-ES and RSA key-management paths (jwe.c). Keys with no
backend-specific material ("oct" / JWT_CRYPTO_OPS_ANY) and key-free operations
(content encryption on a raw CEK, the CSPRNG, the RFC 7638 thumbprint digest,
JWK JSON export) continue to use the active backend.

Mixed-backend usage now "just works", OpenSSL/GnuTLS/MbedTLS behave
consistently, and the "set crypto ops before loading keys" ordering
requirement (the root cause behind #321) is no longer needed.

tests/jwt_xbackend.c exercises the full (parse-backend, use-backend) matrix:
for each pair a key parsed under one backend signs+verifies (EC ES256, RSA
RS256, oct HS256) and round-trips JWE (RSA-OAEP-256, ECDH-ES) under another.
Verified across all three backends under both JSON backends locally
(MbedTLS 4.1) and in the CI image (MbedTLS 3.6.6).

Closes #320

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Ben Collins <bcollins@libjwt.io>
7 files changed
tree: 8929f5f8d0a2c745224dfc18bae0817715167f99
  1. .github/
  2. cmake/
  3. doxygen/
  4. images/
  5. include/
  6. libjwt/
  7. tests/
  8. tools/
  9. .gitignore
  10. CLAUDE.md
  11. CMakeLists.txt
  12. codecov.yml
  13. LICENSE
  14. README.md
  15. SECURITY.md
README.md

LibJWT - The C JWT Library

codecov

maClara

:bulb: Supported Standards

StandardRFCDescription
JWS:page_facing_up: RFC-7515JSON Web Signature
JWE:page_facing_up: RFC-7516JSON Web Encryption
JWK:page_facing_up: RFC-7517JSON Web Keys and Sets
JWA:page_facing_up: RFC-7518JSON Web Algorithms
JWT:page_facing_up: RFC-7519JSON Web Token
JWK Thumbprint:page_facing_up: RFC-7638 / RFC-9278JWK Thumbprint and Thumbprint URI
cnf:page_facing_up: RFC-7800Proof-of-Possession (confirmation) claim helpers

[!NOTE] Throughout this documentation you will see links such as the ones above to RFC documents. These are relevant to that particular part of the library and are helpful to understand some of the specific standards that shaped the development of LibJWT.

:construction: Build Prerequisites

Required

  • A JSON library: either Jansson (>= 2.0, the default) or json-c (>= 0.16, selected with -DWITH_JSON_C=ON). The two are interchangeable.
  • CMake (>= 3.7)

Crypto support

  • OpenSSL (>= 3.0.0)
  • GnuTLS (>= 3.8.8)
  • MbedTLS (>= 3.6.0)

[!NOTE] At least one crypto backend is required, but any non-empty combination works. OpenSSL is enabled by default and can be disabled with -DWITH_OPENSSL=OFF. Each backend parses and converts JWK(S) natively.

Algorithm support matrix

JWS Algorithm algOpenSSLGnuTLSMbedTLS
HS256 HS384 HS512:white_check_mark::white_check_mark::white_check_mark:
ES256 ES384 ES512:white_check_mark::white_check_mark::white_check_mark:
RS256 RS384 RS512:white_check_mark::white_check_mark::white_check_mark:
EdDSA using ED25519 [^okp3813]:white_check_mark::white_check_mark::x:
EdDSA using ED448 [^okp3813]:white_check_mark::white_check_mark::x:
PS256 PS384 PS512:white_check_mark::white_check_mark::white_check_mark:
ES256K:white_check_mark::x::white_check_mark:
ML-DSA-44/65/87 [^mldsa]:white_check_mark::white_check_mark::x:

[^mldsa]: ML-DSA (FIPS 204, registered for JOSE by RFC 9964) is experimental and off by default. Build with -DWITH_ML_DSA=ON; it is only enabled when a backend with ML-DSA support is present: OpenSSL >= 3.5, or GnuTLS >= 3.8.10 built against a PQC provider (e.g. --with-leancrypto). When built in, the public header defines LIBJWT_HAVE_ML_DSA. ML-DSA keys use the "AKP" key type with a "pub" member and a "priv" member holding the 32-byte FIPS-204 seed. MbedTLS has no ML-DSA and rejects AKP keys.

[^okp3813]: On the GnuTLS backend these specific cases need GnuTLS >= 3.8.13: (a) loading an OKP private JWK supplied without its public coordinate x, a “seed-only” Ed25519/Ed448 key (older GnuTLS crashes deriving the public key); and (b) ECDH-ES with the X25519 and X448 curves. Anything that carries x (including every public key and every PEM/DER key) is unaffected, as are the OpenSSL and MbedTLS backends. The version is checked at runtime, so upgrading the shared libgnutls to >= 3.8.13 lifts the restriction without rebuilding LibJWT.

JWE

LibJWT supports JWE (RFC 7516) in both the Compact Serialization and the JSON Serialization (the Flattened form and the General form with one or more recipients). A JWE uses two algorithms: a key management algorithm (alg) and a content encryption algorithm (enc).

JWE serializationRecipientsSupported
Compact (RFC 7516 §7.1)one:white_check_mark:
JSON Flattened (RFC 7516 §7.2.2)one:white_check_mark:
JSON General (RFC 7516 §7.2.1)one or more:white_check_mark:

With the JSON serializations the plaintext is encrypted once with a single CEK; each recipient wraps that CEK independently, so any recipient's key can decrypt the token. They also carry an optional shared unprotected header, per-recipient headers, and an application AAD member.

Legend: :white_check_mark: native implementation  ·  :x: not supported

JWE key management algOpenSSLGnuTLSMbedTLS
dir (Direct Encryption):white_check_mark::white_check_mark::white_check_mark:
A128KW A192KW A256KW:white_check_mark::white_check_mark::white_check_mark:
RSA-OAEP (SHA-1):white_check_mark::x::white_check_mark:
RSA-OAEP-256:white_check_mark::white_check_mark::white_check_mark:
ECDH-ES (+ +A128KW/+A192KW/+A256KW) [^okp3813]:white_check_mark::white_check_mark::white_check_mark:
JWE content encryption encOpenSSLGnuTLSMbedTLS
A128GCM A192GCM A256GCM:white_check_mark::white_check_mark::white_check_mark:
A128CBC-HS256 A192CBC-HS384 A256CBC-HS512:white_check_mark::white_check_mark::white_check_mark:

[!NOTE] ECDH-ES supports both Direct Key Agreement and the +A*KW key wrapping modes, on the EC curves P-256/384/521 and the OKP curves X25519/X448, with optional apu/apv PartyInfo. RSA1_5 and zip (compression) are intentionally not supported. Each backend implements JWE natively. GnuTLS/Nettle cannot perform RSA-OAEP with SHA-1, so the GnuTLS backend does not support plain RSA-OAEP (RSA-OAEP-256 is native).

Optional

:books: Docs and Source

:link: Current Docs

:link: Legacy Docs v2.1.1

:link: GitHub Repo

:package: Pre-built Packages

LibJWT is available in most Linux distributions as well as through Homebrew for Linux, macOS, and Windows.

:hammer: Build Instructions

With CMake:

$ mkdir build
$ cd build
$ cmake ..
$ make