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.

TODOs.

ptime, maybe use positive ints in the API and be more stringent about data checking. Note that fundamentally we don't need that to be POSIX time, a client could use it's own definition of a clock. We could also leave the expiration mechanism out but it feels convenient.
decode, are we happy about the erroring structure ?
encode/decode, provide primed version which compose with {to,of}_string funs ?

Time

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

Keys

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.

Authenticatable

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.