package jose

  1. Overview
  2. Docs
package jose
Legend:
Library
Module
Module type
Parameter
Class
Class type

JSON Web Key

Link to RFC

type use = [
  1. | `Sig
  2. | `Enc
  3. | `Unsupported of string
]

use will default to `Sig in all functions unless supplied

type public =
  1. | Public
type priv =
  1. | Private
type 'key jwk = {
  1. alg : Jwa.alg option;
    (*

    The algorithm for the key

    *)
  2. kty : Jwa.kty;
    (*

    The key type for the key

    *)
  3. use : use option;
  4. kid : string option;
    (*

    Key ID

    *)
  5. key : 'key;
    (*

    The key implementation

    *)
}

rsa represents a public JWK with kty `RSA and a Rsa.pub key

rsa represents a private JWK with kty `RSA and a Rsa.priv key

type oct = string jwk

oct represents a JWK with kty `OCT and a string key.

oct will in most cases be a private key but there are some cases where it will be considered public, eg. if you parse a public JSON

es256 represents a public JWK with kty `EC and a P256.pub key

es256 represents a private JWK with kty `EC and a P256.priv key

es512 represents a public JWK with kty `EC and a P512.pub key

es512 represents a private JWK with kty `EC and a P512.priv key

type 'a t =
  1. | Oct : oct -> 'a t
  2. | Rsa_priv : priv_rsa -> priv t
  3. | Rsa_pub : pub_rsa -> public t
  4. | Es256_priv : priv_es256 -> priv t
  5. | Es256_pub : pub_es256 -> public t
  6. | Es512_priv : priv_es512 -> priv t
  7. | Es512_pub : pub_es512 -> public t

t describes a JSON Web Key which can be either public or private

Public keys

These keys are safe to show and should be used to verify signed content.

val make_pub_rsa : ?use:use -> Mirage_crypto_pk.Rsa.pub -> public t

rsa_of_pub use pub takes a public key generated by Nocrypto and returns a result t or a message of what went wrong.

val of_pub_pem : ?use:use -> string -> (public t, [> `Msg of string | `Not_rsa ]) Stdlib.result

of_pub_pem use pem takes a PEM as a string and returns a public t or a message of what went wrong.

val to_pub_pem : 'a t -> (string, [> `Msg of string | `Not_rsa ]) Stdlib.result

to_pub_pem t takes a JWK and returns a result PEM string or a message of what went wrong.

val of_pub_json : Yojson.Safe.t -> (public t, [> `Json_parse_failed of string | `Msg of string | `Unsupported_kty ]) Stdlib.result

of_pub_json t takes a Yojson.Safe.t and tries to return a public t

val of_pub_json_string : string -> (public t, [> `Json_parse_failed of string | `Msg of string | `Unsupported_kty ]) Stdlib.result

of_pub_json_string json_string takes a JSON string representation and tries to return a public t

val to_pub_json : 'a t -> Yojson.Safe.t

to_pub_json t takes a priv t and returns a JSON representation

val to_pub_json_string : 'a t -> string

to_pub_json_string t takes a priv t and returns a JSON string representation

Private keys

These keys are not safe to show and should be used to sign content.

val make_priv_rsa : ?use:use -> Mirage_crypto_pk.Rsa.priv -> priv t

make_priv_rsa use priv takes a private key generated by Nocrypto and returns a priv t or a message of what went wrong.

val of_priv_pem : ?use:use -> string -> (priv t, [> `Msg of string | `Not_rsa ]) Stdlib.result

of_priv_pem use pem takes a PEM as a string and returns a priv t or a message of what went wrong.

val make_oct : ?use:use -> string -> priv t

make_oct use secret creates a priv t from a shared secret

val to_priv_pem : priv t -> (string, [> `Msg of string | `Not_rsa ]) Stdlib.result

to_priv_pem t takes a JWK and returns a result PEM string or a message of what went wrong.

val of_priv_json : Yojson.Safe.t -> (priv t, [> `Json_parse_failed of string | `Msg of string | `Unsupported_kty ]) Stdlib.result

of_json json takes a Yojson.Safe.t and returns a priv t

val of_priv_json_string : string -> (priv t, [> `Json_parse_failed of string | `Msg of string | `Unsupported_kty ]) Stdlib.result

of_priv_json_string json_string takes a JSON string representation and tries to return a private t

val to_priv_json : priv t -> Yojson.Safe.t

to_json t takes a t and returns a Yojson.Safe.t

val to_priv_json_string : priv t -> string

to_priv_json_string t takes a priv t and returns a JSON string representation

val pub_of_priv : priv t -> public t

pub_of_priv t takes a priv t and returns the coresponding public key.

When using it on Oct keys it will just return the same as it's a symetric key.

Utils

Utils to get different data from a JWK

val get_kid : 'a t -> string option

get_kid jwk is a convencience function to get the kid string

val get_kty : 'a t -> Jwa.kty

get_kty jwk is a convencience function to get the key type

val get_alg : 'a t -> Jwa.alg option

get_alg jwk is a convencience function to get the algorithm

val get_thumbprint : Mirage_crypto.Hash.hash -> 'a t -> (Cstruct.t, [> `Unsafe ]) Stdlib.result

get_thumbprint hash jwk calculates the thumbprint of jwk with hash, following RFC 7638.

Returns an error for symmetric keys: sharing the hash may leak information about the key itself ans it's deemed unsafe.

val use_to_string : use -> string
val use_of_string : string -> use