Base32
Base32
Five bits a character, in four alphabets. Survives a case-blind file system.
- Overhead
- +60% on random bytes
- Padding
- = to a whole block
- Standard
- RFC 4648 §6 and §7, Crockford's Base32, z-base-32
- Used by
- TOTP secrets, Onion v3, ULID, Lightning
Sample
- Out
- NBSWY3DPEB3W64TMMQQQ====
- Back
- "hello world!"
Options
Access
- Import
import { base32 } from "@agntn/encodings/base32" - CLI
encodings encode base32 'hello world!' - Tryplayground with the sample above
Letters and the digits 2 to 7. It survives a file system that ignores case. It survives a person who confuses 0 with O, too. The secret behind your authenticator app? Base32. Onion v3 addresses as well.
encode("base32", "foobar"); // "MZXW6YTBOI======"
That's the RFC 4648 test vector. Five bytes become eight characters, and the last block pads with =. Decoding takes lowercase and the text with or without padding. Wrong padding is an error, though. Six = where the length needs four means something got mangled on the way.
And who pads anyway? Stellar addresses don't. TOTP secrets don't either. Pass padding: false and you don't have to:
encode("base32", "foobar", { padding: false }); // "MZXW6YTBOI"
Five bits a character leaves room for taste. Four alphabets made it into real use, and alphabet picks one. Decoding takes it too.
Why do MY and MZ decode the same?
One byte is eight bits. Two base32 characters are ten. The two spare bits go out as zero, and decoding doesn't look at them. So MY====== is f, and MZ====== is f too.
Text copied by hand doesn't care. A key or an address might. A stray bit there is a bug waiting for its turn, and canonical: true wants those bits zero:
decode("base32", "MZ======", { canonical: true });
// DecodeError: "Z" (U+005A) at index 1 leaves non-zero bits after the last byte
Only the spare bits, mind. Lowercase, spaces and a missing = still read fine. Every alphabet takes it, and only decode does, since encode writes zeros anyway.
The hex alphabet
The same RFC has a second alphabet, 0 to 9 and A to V. Why bother? Order. Sort the encoded strings and they line up exactly like the bytes. Plain base32 can't do that.
encode("base32", "foobar", { alphabet: "hex" }); // "CPNMUOJ1E8======"
decode("base32", "CPNMUOG=", { alphabet: "hex" }).bytes; // "foob"
Decoding needs the alphabet too. CPNMUOG= fits both, and without it that's four other bytes. No error, just wrong. DNSSEC writes NSEC3 owner names in this alphabet, unpadded, so DNS wants padding: false as well.
The crockford alphabet
Douglas Crockford's take. No I, L, O or U. Nothing reads as something else. And nothing spells a rude word by accident, which is why U had to go. ULIDs use this alphabet.
encode("base32", "foobar", { alphabet: "crockford" }); // "CSQPYRK1E8"
decode("base32", "csqp-yrki-e8", { alphabet: "crockford" });
// the same six bytes: lowercase, hyphens, and i read as 1
Decoding ignores case and hyphens. It reads O as 0 and I or L as 1. Lenient? No, that's the spec. It never pads, so padding does nothing here. This is the byte encoding. Crockford also defines a number encoding with a check symbol, which isn't here.
The z alphabet
z-base-32. Zooko O'Whielacronx reordered the alphabet in 2002, so the characters that show up most are the easiest to read, write and say. Lowercase only, no padding. Ever read a key out loud over a call? That's who this is for.
base32.encode(new Uint8Array([0xf0, 0xbf, 0xc7]), { alphabet: "z" }); // "6n9hq"
encode("base32", "hello", { alphabet: "z" }); // "pb1sa5dx"
6n9hq is the example from the original paper. Zooko wrote it for Mnet. These days you meet it in Lightning, where node message signatures come out as z-base-32.