branca-erl

An Erlang implementation of the Branca specification for authenticated and encrypted tokens.

These are symmetrically encrypted, tamper-proof strings of arbitrary contents that can be safely exposed.

Installation

Add this to your rebar.config file to install the library through hex.pm:

{deps, [
    {branca_erl, "0.1.1"}
]}.

Usage

1> Secret = <<"supersecretkeyyoushouldnotcommit">>. % has to be exactly 32 bytes long
<<"supersecretkeyyoushouldnotcommit">>

2> Message = erlang:term_to_binary({foo, bar, baz, [1,2,3]}).
<<131,104,4,100,0,3,102,111,111,100,0,3,98,97,114,100,0,3,
  98,97,122,107,0,3,1,2,3>>

3> Token = branca:encode(Message, Secret).
<<"9GBoip8wFIboItLRutv335YmhKpa4vRX5qXKFoyABy0f8LOw9hk3Zi4I14H2AL9VKk0i6GRentlKXc9qr">>

4> {ok, Message} = branca:decode(Token, Secret).
{ok,<<131,104,4,100,0,3,102,111,111,100,0,3,98,97,114,
      100,0,3,98,97,122,107,0,3,1,2,3>>}

branca:encode/2 should never fail. However, branca:decode/2 has a few different return types:

• {ok, OriginalData} -> successful decryption.
• {error, expired_timestamp, {Timestamp, OriginalData}} -> Successful decryption, but the token expired (not yet implemented).
• {error, bad_encoding} -> CipherText contained at least one non-base62 character (these are [0-9A-Za-z]).
• {error, invalid_token} -> CipherText is base62, but it does not have the layout of a valid Branca token.
• {error, invalid_sig} -> the Secret used to decrypt the token is incorrect, or the token has been tampered.

Testing

The library includes EUnit and PropEr test suites.

These can be run with the usual rebar3 commands (rebar3 eunit and rebar3 proper).

Caveats

• Timestamp expiration has not been implemented yet. The next release will introduce a new branca:encode/3 function that will allow the programmer to specify a timestamp at which the token must be considered as "expired".

• Branca mandates the XChaCha20 variant of the ChaCha20-Poly1305 AEAD construction. However, the libsodium binding for Erlang is currently built for version 1.0.11 of libsodium, and the XChaCha20 variant was not introduced until version 1.0.12. In the meantime branca-erl uses the IETF ChaCha20 variant, that differs in the nonce length (12 bytes instead of 24).

TODO

• Travis CI build
• Timestamp expiration
• Spec annotations for Dialyzer
• Improve all modules documentation