armor64: safe, strict and stable textual encoding of byte streams

Safety

Encoded streams rely only on ASCII printable characters and can be used unescaped in:

• URLs (paths, query strings, fragments, etc.);
• JSON with ASCII-based encoding, including UTF-8;
• Web form data over GET and POST;
• Strings in C, shell, etc.

Strictness

There is only one armor64 encoding for a given byte stream.
If streams are equal, encoded streams are equal, and vice-versa.
Encoders and decoders are required to enforce this rule.
An encoded stream can be validated during decoding or in one pass.

Stability

armor64 is stable in two ways:

• Encoding preserves natural byte order, regardless of signedness.
• There are no variants and the specification will not be revised.

FAQ

Why not base64?

base64 is effectively not a specific encoding but rather a family of encodings.
=-padding is often possible, sometimes required. Many libraries do not offer unpadded variants.
Some variants allow newlines, some don't.
Some variants use a URL-safe alphabet, some don't.
Few variants specify a canonical encoding, fewer mandate that it be used.
None of the variants use an alphabet that preserves natural byte order.

This can lead to ambiguity and confusion for developers, for example when picking implementations or documenting formats.

armor64 uniquely identifies a specification for encoding and decoding bounded byte streams.
armor64.org provides test cases and links to community implementations.

What about Postel's law?

In general, an implementation should be conservative in its sending behavior, and liberal in its receiving behavior.

We could not better Martin Thomson's 2015 Internet-Draft on the topic.

Why reorder the base64url alphabet?

We want byte streams to be ordered like their encoding in the natural byte order.

As a result, situations where one side uses armor64, the other base64 are very unlikely to go unnoticed.
Had the alphabets been shared, problems could have arisen too late.

Why are newlines forbidden?

We want the encoding of byte streams to be unique, and we want to avoid escaping in URLs, JSON-based protocols, etc.

Too often, most byte streams remain comparatively short during development and in test cases.
In base64, only long byte streams involve newlines.
As a result, mishandling of newlines in transport or decoders can be discovered too late.

Specification

Encoding

Input streams are consumed from left to right in blocks of 6 bits.
If fewer than 6 bits are left at the end of the input stream, they are right-padded with 0 bits to form the last block.
Each block is converted to output a single byte according to the following table:

Decoding

Input streams are consumed from left to right and each byte is turned into a block of 6 bits according to the previous table.
When encountering a byte that do not appear in the conversion table, the input stream is rejected.
Those blocks form a stream consumed from left to right to output a byte every 8 bits.
At the end of the input stream, if any of the remaining bits are not 0, the input stream is rejected.

Implementations

• Go;
• Add yours through GitHub or E-mail.

Test cases

The following should encode and decode back to itself:

The following should fail to decode: