Encodings

Base32

Base32 in four alphabets. RFC 4648 with A to Z and 2 to 7 or its hex alphabet plus Crockford's and z-base-32 for people
IDbase3206 / 20base32 · 32 characters
Encoding / 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
family 1 / 20

Sample

Out
NBSWY3DPEB3W64TMMQQQ====
Back
"hello world!"

Options

alphabetstring
default standard
standard A-Z 2-7 (RFC 4648 §6), hex 0-9 A-V (§7), crockford (no I, L, O, U; reads its look-alikes and hyphens) or z (z-base-32)
paddingboolean
default true
Pad the last block with = to eight characters; standard and hex only
canonicalboolean
default false
Refuse non-zero spare bits in the last character; case, whitespace and padding read as usual

Access

Importimport { base32 } from "@agntn/encodings/base32"
CLIencodings 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.

ts
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:

ts
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:

ts
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.

ts
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.

ts
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.

ts
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.