radbas/branca.cr

Authenticated encrypted API tokens for Crystal. A secure JWT alternative.

Branca.cr

Authenticated encrypted API tokens for Crystal. A secure JWT alternative.

This implementation uses Monocypher 4.0.1 to securely encrypt tokens.

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.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     branca:
       github: radbas/branca.cr

2. Run shards install

Usage

require "branca"

key = Bytes.new(32)
Random::Secure.random_bytes(key)
branca = Branca.new key

token = branca.encode("Hello world!", 123206400)
p token # e.g. 870S4BYxgHw0KnP3W9fgVUHEhT5g86vJ17etaC5Kh5uIraWHCI1psNQGv298ZmjPwoYbjDQ9chy2z

decoded = branca.decode(token)

p String.new(decoded.payload) == "Hello world!" # true
p decoded.timestamp == 123206400 # true

Make sure you use a secure encryption key generated by Random::Secure.random_bytes

key = Bytes.new(32)
Random::Secure.random_bytes(key)

# store the key somewhere as a hex string
hex = key.hexstring

# convert hex string back to bytes
key = hex.hexbytes

Contributing

1. Fork it (https://github.com/radbas/branca.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Johannes Rabausch - creator and maintainer