Module Webs_kit.Authenticatable

Authenticatable data.

This module defines a simple US-ASCII compatible encoding scheme to publish non-secret, expirable data bytes authenticatable via a secret private key. Human readability is a non-goal, storing your state in non-trusted environments is.

The data is not encrypted.



type ptime = float

The type for POSIX time as a number of seconds since the epoch 1970-01-01 00:00:00 UTC.


type key = string

The type for keys. This is used with HMAC-SHA-256, so it should be at least 32 bytes long.

val random_key : unit -> key

random_key () are 64 bytes random bytes sourced after having called Random.self_init.


type t = string

The type for authenticatable bytes. The encoding scheme for bytes data and an optional expiration timestamp expire is:

expire = match expire with None -> "" | Some e -> string_of_int e
msg = expire + ":" + data
authenticatable = (base64|base64url)(hmac-sha-256(key, msg) + msg)
val encode : ?⁠base64url:bool -> key:key -> expire:ptime option -> string -> t

encode ~key ~expire data makes data data expire at expire (if any and truncated to seconds) and authenticatable via the private key key. If base64url is true (defaults to false) the base64url encoding scheme is used instead of base64.

val decode : ?⁠base64url:bool -> key:key -> now:ptime -> t -> (ptime option * string, [ `Expired | `Decode | `Authentication ]) Stdlib.result

decode ~key ~now s authenticates data s with the private key key and makes it expire (if applicable) according to now. The result is:

  • Ok (expire, data) with data authenticated by key and now stricly smaller than expire (if any).
  • Error `Expired if the data could be authenticated but now is larger or equal to expire (if any).
  • Error `Authentication if s cannot be authenticated by key.
  • Error `Decode if any other decoding error occurs.

If base64url is true (defaults to false) the base64url encoding scheme is used instead of base64.

Untrusted decode

val untrusted_decode : ?⁠base64url:bool -> t -> ([ `Untrusted of Sha_256.t * ptime option * string ][ `Decode ]) Stdlib.result

untrusted_decode s decodes the encoding structure of s but neither authenticates nor expires the data.