a00c9ddf2c9734c3ea7ff9da2eaa415c47f7f7d3 - benmcollins/libjwt

tree: ab0374747a05ec574d7afef7b4793b106e1b99d9

README.md

:bulb: Supported Standards

Standard	RFC	Description
`JWS`	:page_facing_up: RFC-7515	JSON Web Signature
`JWE`	:page_facing_up: RFC-7516	JSON Web Encryption
`JWK`	:page_facing_up: RFC-7517	JSON Web Keys and Sets
`JWA`	:page_facing_up: RFC-7518	JSON Web Algorithms
`JWT`	:page_facing_up: RFC-7519	JSON Web Token

[!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 `alg`	OpenSSL	GnuTLS	MbedTLS
`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`	:white_check_mark:	:white_check_mark:	:x:
`EdDSA` using `ED448`	: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:

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 serialization	Recipients	Supported
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 `alg`	OpenSSL	GnuTLS	MbedTLS
`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`)	:white_check_mark:	:white_check_mark:	:white_check_mark:

JWE content encryption `enc`	OpenSSL	GnuTLS	MbedTLS
`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

Check Library (>= 0.9.10) for unit testing
Doxygen (>= 1.13.0) for documentation

: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