Branca Tokens for Ruby

Authenticated and encrypted API tokens using modern crypto.

What?

Branca is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. Payload itself is an arbitrary sequence of bytes. You can use for example a JSON object, plain text string or even binary data serialized by MessagePack or Protocol Buffers.

It is possible to use Branca as an alternative to JWT.

Install

Add this line to your application's Gemfile, Note that you also must have libsodium installed.

gem 'branca-ruby', '~> 1.0.0'

Configure

You must be configure secret_key and ttl using this.

Branca.configure do |config|
  config.secret_key = 'supersecretkeyyoushouldnotcommit'.b
  config.ttl = 86_400 # in seconds
end

Usage

The payload of the token can be anything, like a simple string.

Encode

Branca.encode('with string')

# 1y48BiLKOcB4N8xjazwFpas3DwOovXzu6vtbiUr4bDAGLaVyFjIN5Xwz5p3qvNYsi5kWjk7ilgnS

or JSON stringified

Branca.encode(JSON.generate({ permissions: [] }))

# ATkzLjriA1ijbBcuZOJ1zMR0z5oVXDGDVjUWwrqJWszynAM4GLGiTwZnC6nUvtVIuavAVCMbwcsYqlYKejOI4

You can also pass timestamp to encode

Branca.encode('with string', Time.now.utc)

# 1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5

Decode

If you branca token isnt expired. You will receive something like this

decode = Branca.decode('1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5')

# <Branca::Decoder:0x00007fde4e3e6398 @message="with string", @timestamp=2020-10-27 03:44:03 UTC>

decode.message
# "with string"

Exceptions

Token is expired, will receive exception Branca::ExpiredTokenError

Invalid Version, will receive exception Branca::VersionError