jose 0.8.2 · OCaml Package

JSON Web Key

Link to RFC

type use = [

| `Sig
| `Enc
| `Unsupported of string

]

use will default to `Sig in all functions unless supplied

type public =

| Public

type priv =

| Private

type 'key jwk = {

alg : Jwa.alg option;
(*
The algorithm for the key
*)
kty : Jwa.kty;
(*
The key type for the key
*)
use : use option;
kid : string option;
(*
Key ID
*)
key : 'key;
(*
The key implementation
*)

}

type pub_rsa = Mirage_crypto_pk.Rsa.pub jwk

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

type priv_rsa = Mirage_crypto_pk.Rsa.priv jwk

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

type priv_es256 = Mirage_crypto_ec.P256.Dsa.priv jwk

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

type pub_es256 = Mirage_crypto_ec.P256.Dsa.pub jwk

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

type priv_es512 = Mirage_crypto_ec.P521.Dsa.priv jwk

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

type pub_es512 = Mirage_crypto_ec.P521.Dsa.pub jwk

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

type 'a t =

| Oct : oct -> 'a t
| Rsa_priv : priv_rsa -> priv t
| Rsa_pub : pub_rsa -> public t
| Es256_priv : priv_es256 -> priv t
| Es256_pub : pub_es256 -> public t
| Es512_priv : priv_es512 -> priv t
| 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

package jose

JSON Web Key

Public keys

Private keys

Utils