Branca v0.1.0 Branca View Source

Branca allows you to generate and verify encrypted API tokens (IETF XChaCha20-Poly1305 AEAD). Branca specification defines the external format and encryption scheme of the token to help interoperability between userland implementations. Branca is closely based on Fernet.

Payload in Branca token is an arbitrary sequence of bytes. This means payload can be for example a JSON object, plain text string or even binary data serialized by MessagePack or Protocol Buffers.

Link to this section Summary

Functions

decode(encoded)

Decrypts and verifies the token and returns the payload

decode(encoded, ttl)

Decrypts, verifies and checks the timestamp of the token and returns the payload

encode(payload)

Returns base62 encoded encrypted token with given payload

encode(payload, timestamp)

Returns base62 encoded encrypted token with given payload and timestamp

encode(payload, timestamp, nonce)

Returns base62 encoded encrypted token with given payload, timestamp and nonce

Link to this section Functions

decode(encoded)

Decrypts and verifies the token and returns the payload.

iex> token = Branca.encode("Hello world!");
iex> Branca.decode(token)
{:ok, "Hello world!"}

decode(encoded, ttl)

Decrypts, verifies and checks the timestamp of the token and returns the payload.

iex> token = Branca.encode("Hello world!", 123206400);
iex> Branca.decode(token)
{:ok, "Hello world!"}
iex> Branca.decode(token, 60)
{:error, :expired}

encode(payload)

Returns base62 encoded encrypted token with given payload.

Token will use current timestamp and generated random nonce. This is what you almost always want to use.

iex> token = Branca.encode("Hello world!")
875GH233T7IYrxtgXxlQBYiFobZMQdHAT51vChKsAIYCFxZtL1evV54vYqLyZtQ0ekPHt8kJHQp0a

encode(payload, timestamp)

Returns base62 encoded encrypted token with given payload and timestamp

Token will use generated random nonce. You can for example opt-out from timestamp by setting it to 0. You can also adjust for clock skew by setting the timestamp few seconds to future.

iex> token = Branca.encode("Hello world!", 123206400)
87x85fHpKCLTmXrRJUcPiOiNTBTpG5MpvUg87fbcaqv2uK68iFK3ocTIVIdlrvXTkhA6jvCf3HiW1

encode(payload, timestamp, nonce)

Returns base62 encoded encrypted token with given payload, timestamp and nonce.

This is mostly used for unit testing. If you use this function make sure not to reuse the nonce between tokens.

iex> nonce = Salty.Random.buf(24)
iex> token = Branca.encode("Hello world!", 123206400, nonce)
87x85fNayA1e3Zd0mv0nJao0QE3oNUGTuj9gVdEcrX4RKMQ7a9VGziHec52jgMWYobXwsc4mrRM0A