#18

These test vectors combine what I've found in the PHP implementation, with some extra tests. As mentioned, these include the nonces, but can be removed depending on your conclusion @tuupola.

The extra tests add more edge-cases, related to empty input, non-UTF8, etc.

TODO:

• [X] Figure out if nonces should be included
• [X] Cross-verify against other implementations (any specific ones?) (so far, Rust and PHP)
• [X] Prettify nonces to be strings instead of hexadecimal ("beefbeefbeefbeefbeefbeef")
• [X] Remove TC12 and TC7
• [X] Separate encoding-only and decoding-only tests (separate groups or separate files)

Test 18, when run with pybranca, fails. This is because it allows the timestamp to overflow the spec 0..4294967295 range, when checking for expiration with a TTL. I assume this is not intended and I would like to restrict the TTL not to overflow the timestamp in the spec, @tuupola? I'd be happy to add it to the spec myself.

from branca import Branca
import json
from binascii import unhexlify, hexlify
import calendar
from datetime import datetime


with open('test_vectors.json', "r") as test_vectors:
    data = json.load(test_vectors)

for test_vector in data:
    print("Testing:", test_vector['test_vector_id'])
    print("Comment:", test_vector['comment'])

    try:
        ctx = Branca(test_vector['key'])
        ctx._nonce = unhexlify(test_vector['nonce'])
        token_actual = ctx.encode(unhexlify(test_vector['msg']), timestamp=test_vector['timestamp'])

        try:
            message_actual = ctx.decode(test_vector['token'], ttl=test_vector['ttl'])
        except:
            if test_vector['is_valid'] is False:
                print("Pass: TRUE")
            else:
                message_actual = ctx.decode(test_vector['token'])

        # Define passing test
        if test_vector['is_valid'] is True:
            if token_actual == test_vector['token'] and message_actual == unhexlify(test_vector['msg']):
                print("Pass: TRUE")
            else:
                print("Pass: FALSE")
        else:
            if token_actual != test_vector['token']:
                print("Pass: TRUE")
            elif message_actual != unhexlify(test_vector['msg']):
                print("Pass: TRUE")
            else:
                print("Pass: FALSE")
    except:
        if test_vector['is_valid'] is False:
            print("Pass: TRUE")
        else:
            print("Pass: FALSE")

Rust implementation would be welcome. Something similar as frank_jwt by @GildedHonour. Anyone interested in implementing it write me a note here and I will add it to the docs.

Go implementation is missing. Something similar as fernet-go by @kr. Anyone interested in implementing it write me a note here and I will add it to the docs.

$size = CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES; $random = random_bytes($size); $nonce = sodium_crypto_generichash($payload, $random, $size);

I think it would be good to concretize this a bit to make it clearer, by specifically stating the algorithm this example uses (BLAKE2b IIRC). Also, what if sodium_crypto_generichash changes at some point? If we specifically state the algorithm tied to hashing for the nonce, we can tie that to the version and change it in the far future if need be. The last part is not too important, I'm more into specifying it to make it clear what algorithm is considered secure. In case a user might try to use something else, if libsodium is not accessible to them.

Erlang implementation is missing. Something similar as fernet-erl by @bigkevmcd. Anyone interested in implementing it write me a note here and I will add it to the docs.

Python implementation is badly needed. Something similar as pyjwt by @jpadilla. Anyone interested in implementing it write me a note here and I will add it to the docs.

If I understood the Branca specs correctly, the timestamp field seems to be unprotected.

Let's say a website uses Branca tokens as session cookies and relies on the timestamp field in order to check if the token is still valid. An attacker might get access to a valid or expired token and manipulate the timestamp field whenever needed in order to make the expired token valid again. This applies not only to the context of websites and session cookies but to every possibly untrusted environment in which Branca tokens could be used.

As far as I can tell, the timestamp field doesn't provide any reliable information in an untrusted environment.

I'm writing this because not everyone using Branca tokens might be aware of that. I suggest to either make this very clear in the documentation or to change the spec so that tampering with the timestamp field can be detected.

The character set provided in the spec:

0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxy

Only contains 61 characters, and is thus a base61 encoding. Looking at the implementations listed on the document, it seems that most of them (if not all) include a z to the character set as I would expect.

Is this the intended behaviour? Or should the character set not include the character z?

Hi! We have been released our high-grade quality package with Branca implementation - https://github.com/essentialkaos/branca

Features:

• Pure Go implementation;
• No third-party dependencies at all;
• 100% code coverage;
• Fuzz tests.

I think it will be great to add information about this package to the branca website.

I think it would make sense to specifically state, that the expiration check for a token using a ttl should happen after authenticating and decrypting. If it happens before, a user would never know if an expired token they received was tampered into expiring, or actually did expire.

Note that this is Authenticated Encryption with Additional Data (AEAD) where the he header part of the token is the additional data.

The word ‘he’ should be removed.

This introduces several changes as part of #37.

• We put a disclaimer at the beginning of the list of known implementations. This way, it's clear that this list does is not to be interpreted as an official endorsement.

• Another separate list is added in the beginning. It's purpose is, that libraries that have been tested previously to be correct, can be added here. We still don't guarantee this list is updated, but can still provide a better starting point compared to some of the libraries listed later, that may not be compliant at all.

I'd like your take on this additional section @tuupola. The intention is not to provide an endorsement list, just one that contains libraries that have been tested successfully at least once. I think the idea with a checkmark, indicating compliance, as implemented by PASETO suggested in #37 is not the right approach. We don't expect people working on this specification to set aside time to audit a new library, each time a new author wants to add theirs. (The list in this PR are just the ones I'm familiar with)

With PASETO, I've myself added a library to their list, where I myself indicated that it passed test vectors. I have no idea if this was verified by a third-party at any time. If not, the end result seem equal to simply a author adding their new library - the same level of confidence can be derived from that.

The new list can be updated on an ad-hoc basis. If someone wanting to use a library verifies it and reports here that it can be moved up the "known to comply at some point" library, we can do so. This was an alternative to a "Recommended libraries" section, but if this that seems better to you @tuupola, we can make that instead.

The last point I want to address, is that: As I've written about here, some libraries listed suffer security problems in addition to non-compliance. Do we wish to remove these entirely?

The Javascript reference implementation has recently changed to enforce the use of more secure 32 byte hex keys, or a 32 byte Buffer. This change is to require the use of cryptographic keys of the proper length and construction as expected by the underlying encryption algorithm.

https://github.com/tuupola/branca-js

The spec should be modified to:

• add additional context to the spec README about why this change was made
• note that it is likely a breaking change and thus might require version bumping the spec
• modify the test vectors so they will work with the new key mechanism

Other downstream implementations should also be encouraged to adopt the new spec to maintain cross library interoperability.

Laravel and Lumen support would be awesome. Something similar as jwt-auth by @tymondesigns. You could also check branca-middleware for inspiration. PHP library for encoding and decoding tokens already exists.

Anyone interested in implementing it write me a note here and I will add it to the docs.