package macaroons

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

Macaroons that use C for their cryptographic needs.

Parameters

module C : CRYPTO

Signature

type t

The type of macaroons.

val create : location:string -> key:string -> id:string -> t
val location : t -> string

location m is the location of m (if any).

val identifier : t -> string

identifier m is the identifier of m.

val signature : t -> string

signature m is the signature of m.

val add_first_party_caveat : t -> string -> t

add_first_party_caveat m cid adds a caveat which will be discharged by the target service. See verify.

val add_third_party_caveat : t -> key:string -> ?location:string -> string -> t

add_third_party_caveat m ~key ~location cid adds a caveat that will be discharged by a third-party. The third party is to produce, upon request, a macaroon proving that the caveat has been discharged. This hypothetical macaroon must be minted with root key key. See verify.

val prepare_for_request : t -> t -> t

prepare_for_request m d should be invoke for each discharge macaroon d associated to the main authorizing macaroon m before sending them off the target service for verification. It binds the the signatures of d and m together making it impossible for a malicious third party to maliciously re-use d to discharge third-party caveats of m.

val equal : t -> t -> bool

Whether two macaroons are equal.

val serialize : t -> string

serialize m converts the macaroon m into a base64-string suitable for transmission over the network. Its inverse is deserialize.

type deserialize_error = [
  1. | `Unexpected_char of char * char
  2. | `Not_enough_data of int
  3. | `Unexpected_packet_id of string
  4. | `Character_not_found of char
]
val deserialize : string -> [ `Ok of t | `Error of int * deserialize_error ]

deserialize m is the inverse of serialize.

val pp : Stdlib.Format.formatter -> t -> unit

pp ppf m prints a user-readable description of the macaroon m for debugging purposes.

val verify : t -> key:string -> check:(string -> bool) -> t list -> bool

verify m ~key ~check d verifies whether all the caveats of m hold. key must be the key used with create. check is called to verify all first-party caveats. d is a list of discharge macaroons used to verify third-party cavests. Each element of d must have been previously bound with m using prepare_for_request.