Liking cljdoc? Tell your friends :D

User Guide

Branca homepage describes Branca as follows:

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. The encrypted token is base62 encoded which makes it URL safe. Payload itself is an arbitrary sequence of bytes.

clj-branca is a Clojure implementation of encoding and decoding Branca tokens. It is built on Lazysodium cryptography library.

Installation

Add clj-branca to your project’s dependencies:

deps.edn
{miikka/clj-branca {:mvn/version "0.1.0"}}
Leiningen
[miikka/clj-branca "0.1.0"]

Basic usage

The main namespace of clj-branca is clj-branca.core. It is recommended to be required with the alias branca.

(require '[clj-branca.core :as branca])

You can encode payload into a token with branca/encode. The payload can be a byte array, a string, or anything else that can be converted into a byte array by the byte-streams library. The tokens is returned as a string.

(def secret-key "supersecretkeyyoushouldnotcommit")
(def message "Hello, world!")

(branca/encode secret-key message)
;; "XZ69WpRTqZgEOqCJqaOK4iOKGLkg505VSASQ8MMGWs3mn1p6U81FvB5rSLpKlIjkZTUIBC6KiHIboz"

To decode the token, use branca/decode. It takes the token as a string and returns the payload as a byte array.

(String. (branca/decode secret-key "XZ69WpRTqZgEOqCJqaOK4iOKGLkg505VSASQ8MMGWs3mn1p6U81FvB5rSLpKlIjkZTUIBC6KiHIboz"))
;; "Hello, world!"

The encryption key used is 32 bytes. It can be a byte array or anything that can be converted into a byte array. You can generate a new key with clj-branca.crypto/generate-key.

(require '[clj-branca.crypto])
(clj-branca.crypto/generate-key)
;; #object["[B" 0x7e00ed0f "[B@7e00ed0f"]

Token timestamp and time to live

Branca tokens contain a timestamp that indicates when the token was issued. To limit token lifetime, you can give :ttl in seconds in the options map when calling branca/decode. For example, to limit token lifetime to an hour:

(branca/decode secret-key token {:ttl 3600})

If the token is expired, branca/decode throws an exception. If you need to implement more complex TTL logic, you can get the token timestamp along the payload by calling branca/decode*.

(branca/decode* secret-key "XZ69WpRTqZgEOqCJqaOK4iOKGLkg505VSASQ8MMGWs3mn1p6U81FvB5rSLpKlIjkZTUIBC6KiHIboz")
;; {:version -70,
;;  :timestamp 1602348074,
;;  :nonce #object["[B" 0x37d81587 "[B@37d81587"],
;;  :payload #object["[B" 0x7f3e9acc "[B@7f3e9acc"]}

The return value includes the token version and the nonce as well. You probably won’t need them for anything, but they’re included for the sake of completeness.

Tip
There is only one Branca version, 0xBA. This is represented as a single-byte value. Because JVM bytes are signed, the value is printed as -70 and not as 186 as you might expect.

Error handling

Whenever clj-branca encouters an error, such as a malformed or a tampered token, it throws a clojure.lang.ExceptionInfo exception. The exception data contains the key :type to indicate that the exception was thrown by clj-branca.

:type explanation

:clj-branca.core/invalid-key

The key must be a 32-byte byte array.

:clj-branca.core/encode-failure

Encryption failed.

:clj-branca.core/invalid-token

Decoding token failed.

Can you improve this documentation?Edit on sourcehut

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close