JOSE - JavaScript Object Signing and Encryption

JOSE implementation in OCaml.

Goals

This package aims to implement the JOSE specification. The main usecase for JOSE is probably JWT signing and verification via JWKs.

Installation

Install jose using opam:

opam install jose

Examples

Make sure to initialize the random number generator (required by mirage-crypto) before performing cryptographic operations:

let () = Mirage_crypto_rng_unix.use_default ()

JWS (JSON Web Signature)

Sign and verify arbitrary payload with a key (symmetric oct or asymmetric RSA, EC, OKP):

(* 1. Create or load a key *)
let jwk = Jose.Jwk.make_oct "a-secret-key-that-is-at-least-32-bytes"

(* 2. Sign a payload *)
let jws = Jose.Jws.sign ~payload:"Hello, JWS!" jwk |> Result.get_ok

(* 3. Serialize to compact representation ("<header>.<payload>.<signature>") *)
let token = Jose.Jws.to_string jws

(* 4. Parse and validate signature *)
let parsed_jws = Jose.Jws.of_string token |> Result.get_ok
let validated_jws = Jose.Jws.validate ~jwk parsed_jws |> Result.get_ok
let payload = validated_jws.payload (* "Hello, JWS!" *)

JWE (JSON Web Encryption)

Encrypt and decrypt plaintext payloads:

(* 1. Create or load an encryption key *)
let jwk = Jose.Jwk.make_oct ~use:`Enc "a-secret-key-that-is-at-least-32-bytes"

(* 2. Create a JWE header with key management and content encryption algorithms *)
let header = Jose.Header.make_header ~alg:`Dir ~enc:`A256GCM jwk

(* 3. Encrypt the plaintext into compact representation *)
let jwe = Jose.Jwe.make ~header "Secret payload data" |> Result.get_ok
let encrypted_token = Jose.Jwe.encrypt ~jwk jwe |> Result.get_ok

(* 4. Decrypt using the key *)
let decrypted_jwe = Jose.Jwe.decrypt ~jwk encrypted_token |> Result.get_ok
let payload = decrypted_jwe.payload (* "Secret payload data" *)

JWT (JSON Web Token)

Create, sign, and validate tokens with claim and expiration verification:

(* 1. Create or load a key *)
let jwk = Jose.Jwk.make_oct "a-secret-key-that-is-at-least-32-bytes"

(* 2. Build payload with claims *)
let now = Ptime.of_float_s (Unix.time ()) |> Option.get
let exp =
  Ptime.add_span now (Ptime.Span.v (0, 3600L * 1_000_000_000_000L))
  |> Option.get

let payload =
  Jose.Jwt.empty_payload
  |> Jose.Jwt.add_claim "sub" (`String "user_123")
  |> Jose.Jwt.add_claim "exp" (`Int (Ptime.to_span exp |> Ptime.Span.to_int_s |> Option.get))

(* 3. Sign the token *)
let jwt = Jose.Jwt.sign ~payload jwk |> Result.get_ok
let token_string = Jose.Jwt.to_string jwt

(* 4. Parse and validate signature and expiration *)
let validated_jwt = Jose.Jwt.of_string ~jwk ~now token_string |> Result.get_ok
let user_id = Jose.Jwt.get_string_claim validated_jwt "sub" (* Some "user_123" *)

Algorithm Compatibility

The compatibility tables below are automatically extracted from the codebase using scripts/extract_compatibility.py.

JWS Digital Signature and MAC Algorithms (alg)

JWE Key Management Algorithms (alg)

JWE Content Encryption Algorithms (enc)

JSON Web Key Types (kty)

To update or check the compatibility tables:

# Update README.md in-place
python3 scripts/extract_compatibility.py --update-readme

# Check if README.md is in sync (e.g. in CI)
python3 scripts/extract_compatibility.py --check

pre 1.0.0

Expect breaking changes on minor releases but patch should not be breaking.

I want to get feedback on both the API and implementation. Issues and PRs are more than welcome.