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
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 calledRandom
.self_init.
Authenticatable
type t
= string
The type for authenticatable bytes. The encoding scheme for bytes
data
and an optional expiration timestampexpire
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 datadata
expire atexpire
(if any and truncated to seconds) and authenticatable via the private keykey
. Ifbase64url
istrue
(defaults tofalse
) thebase64url
encoding scheme is used instead ofbase64
.
val decode : ?base64url:bool -> key:key -> now:ptime -> t -> (ptime option * string, [ `Expired | `Decode | `Authentication ]) Stdlib.result
decode ~key ~now s
authenticates datas
with the private keykey
and makes it expire (if applicable) according tonow
. The result is:Ok (expire, data)
withdata
authenticated bykey
andnow
stricly smaller thanexpire
(if any).Error `Expired
if the data could be authenticated butnow
is larger or equal toexpire
(if any).Error `Authentication
ifs
cannot be authenticated bykey
.Error `Decode
if any other decoding error occurs.
If
base64url
istrue
(defaults tofalse
) thebase64url
encoding scheme is used instead ofbase64
.