Jws (p.jws.0.0.1.doc.jws.Jws)

JWS - JSON Web Signature (RFC 7515)

A straightforward implementation of JWS in OCaml using mirage-crypto and Jsont.

This library uses polymorphic variants that are compatible with X509.Public_key.t and X509.Private_key.t. For instance, given a private key obtained from x509:

  let pk : X509.Private_key.t = ... in
  let jws = Jws.encode (Pk.of_private_key_exn pk) ~nonce "payload"

Protected header fields beyond alg and nonce can be read back via value using any Jsont.t decoder:

  let url = Jws.value jws ~key:"url" Jsont.string

Base64url

Sourcemodule Base64u : sig ... end

JWA - JSON Web Algorithms (RFC 7518)

Sourcemodule Jwa : sig ... end

JWK - JSON Web Key (RFC 7517)

Sourcemodule Jwk : sig ... end

A Key-Value map to represent a JSON object

Sourcemodule S : sig ... end

Private keys and signing

Sourcemodule Pk : sig ... end

JWS values

Sourcetype t

A decoded JWS value.

Sourceval nonce : t -> string option

nonce jws is the nonce protected header field, if present.

Sourceval data : t -> string

data jws is the payload carried by jws.

Sourceval value : t -> key:string -> 'a Jsont.t -> 'a option

value jws ~key codec decodes the protected header field key using the Jsont.t codec. Returns None when the field is absent or cannot be decoded.

For example, to read the "url" field added by ACME (RFC 8555):

  Jws.protected jws ~key:"url" Jsont.string

Source

val validate_crit : 
  ?understood:string list ->
  Jsont.json S.t ->
  (unit, [> `Msg of string ]) result

validate_crit ?understood props validates the "crit" header parameter according to RFC 7515, 4.1.11. understood is the list of extension header names the application recognizes.

Flattened JSON Serialization (RFC 7515, 7.2.2)

Source

val encode : 
  ?kid:string ->
  ?extra:Jsont.json S.t ->
  Pk.t ->
  ?nonce:string ->
  string ->
  string

encode ?kid ?extra pk ?nonce data produces a JWS Flattened JSON Serialization that signs (or MACs) data with pk. The algorithm is derived from pk.

When kid is provided, a "kid" header field is set and no JWK is embedded. Otherwise the public key is embedded as a "jwk" header field (this is the typical ACME workflow).

extra carries additional protected header members as a Jsont.json string map. For instance, to set the "url" field required by ACME:

  let extra = S.singleton "url" (Jsont.Json.string url) in
  Jws.encode ~extra pk ~nonce payload

Source

val encode_exn : 
  ?alg:Jwa.t ->
  ?kid:string ->
  ?extra:Jsont.json S.t ->
  Pk.t ->
  ?nonce:string ->
  string ->
  string

encode_exn ?alg ?kid ?extra pk ?nonce data is like encode but allows overriding the algorithm via ?alg.

raises Invalid_argument
if the given algorithm alg does not match the given private key pk.

Source

val decode : 
  ?understood:string list ->
  ?public:Jwk.t ->
  string ->
  (t, [> `Msg of string ]) result

decode ?understood ?public str decodes and verifies a JWS Flattened JSON Serialization. The public key is taken from public if provided, otherwise from the embedded "jwk" header field. Returns a descriptive error when the JSON is malformed, no public key is available, the signature is invalid, or a critical header extension is not understood.

understood lists the critical header extensions the application recognizes (see validate_crit).

Sourceval decode_exn : ?understood:string list -> ?public:Jwk.t -> string -> t

decode_exn is like decode but raises Failure on error.

Compact Serialization (RFC 7515, 7.1)

Sourcemodule Compact : sig ... end