branca

Crate	Documentation	License	Travis

Branca is a secure alternative token format to JWT. This implementation of the branca token specification is written in Rust and uses a fork of sodiumoxide for the XChaCha20-IETF-Poly1305 AEAD (Authenticated Encryption with Associated Data) stream cipher for generating encrypted tokens. More about the branca token specification can be found here in branca-spec.

Requirements

• Rust 1.18+
• Cargo

Installation

Add this line to your Cargo.toml under the dependencies section:

[dependencies]
branca = "^0.1.1"

Then you can import the crate into your project with these lines:

extern crate branca
use branca::{Branca, encode, decode};

Example Usage

Encoding

let key = b"supersecretkeyyoushouldnotcommit".to_vec();
let nonce = *b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c";

let message = "Hello world!".to_string();
let timestamp = 123206400;
let branca_token = encode(message,key,nonce,timestamp).unwrap();

// branca_token = 875GH233T7IYrxtgXxlQBYiFobZMQdHAT51vChKsAIYCFxZtL1evV54vYqLyZtQ0ekPHt8kJHQp0a

Decoding

let ciphertext = branca_token.to_string();
let key = b"supersecretkeyyoushouldnotcommit".to_vec();
let ttl = 0; // The ttl can be used to determine if the supplied token has expired or not. //
let decoded = decode(ciphertext, key, ttl);

if decoded.is_err() {
    // Error
} else {
    let msg = decoded.unwrap(); 
    // msg = "Hello world!"
}

You can use either Ring's SecureRandom or sodiumoxide's aead gen_nonce() or gen_key() for generating secure nonces and keys for example.

But do note that the nonce must be 24 bytes in length. Keys must be 32 bytes in length.

Building

cargo build

Testing

cargo test --examples

Contributing

Contributions and patches are welcome! Fork this repository, add your changes and send a PR.

Before you send a PR, make sure you run cargo test --examples first to check if your changes pass the tests.

If you would like to fix a bug or add a enhancement, please do so in the issues section and provide a short description about your changes.

License

MIT