Base64 Encoding

How Base64 works

Computers store data as bytes — 8-bit values from 0 to 255. Most of those byte values are not printable: 0x00 is the null terminator, 0x01-0x1F are control codes, 0x7F is DEL, anything above 0x7F is non-ASCII. A surprising number of channels still refuse to transport arbitrary bytes: SMTP mail historically required 7-bit clean, URLs reserve syntactic characters, HTML attributes can't contain unescaped quotes. Whenever binary data needs to ride through a text-only pipe, you encode.

Base64 is the canonical choice. It takes any byte sequence and produces an output drawn from a 64-character alphabet that is universally safe: A-Z (values 0-25), a-z (26-51), 0-9 (52-61), + (62), and / (63). All 64 characters are ASCII and most are even URL-safe in their alphanumeric form.

The encoding rule:

1. Group input into 3-byte chunks. Each chunk is 24 bits.
2. Re-slice into 6-bit groups. 24 bits ÷ 6 = 4 groups. Each group is a value 0-63.
3. Map each 6-bit value to the alphabet. Look up the character at that index.
4. Pad the final chunk if needed. If the last group has only 1 or 2 bytes, fill the unused 6-bit slots with zero bits and emit = characters to mark the padding.

Worked example — "Man" → "TWFu"

The string Man is three ASCII bytes: M=0x4D=77, a=0x61=97, n=0x6E=110. Concatenated as 24 bits:

M        a        n
01001101 01100001 01101110

Re-group as four 6-bit values:

010011 010110 000101 101110
   19     22      5     46

Map through the alphabet: 19→T, 22→W, 5→F, 46→u. The output is TWFu — four characters from three input bytes, a precise 4/3 expansion. This is the example RFC 4648 itself uses, and it's worth memorizing as a sanity check.

Now imagine the input is just Ma (two bytes, 16 bits). The encoder pads with zero bits to fill the third 6-bit group, then emits one =:

M        a        (no n)
01001101 01100001 0000(pad)
010011 010110 0001 00     →  T W E =
                              (4 chars including =)

And for one byte (M alone): two = characters trail the encoded prefix TQ==.

Alphabet variants

Variant	Char 62	Char 63	Padding	Used by
Standard (RFC 4648 §4)	+	/	= required	MIME email, PEM, basic auth
URL-safe (RFC 4648 §5)	-	_	= optional	URL params, filenames
base64url (JWT/JOSE)	-	_	= omitted	JWT, OAuth2, JOSE specs
MIME quoted (RFC 2045)	+	/	= required; CRLF every 76 chars	SMTP message bodies
YUI/y64 (custom)	.	_	varies	Yahoo cookies, legacy systems
Base64 with whitespace ignored	+	/	= required	OpenSSL CLI, lenient parsers

The two consequential decisions are whether +// or -/_ appears in the alphabet, and whether padding is required. JWT chose URL-safe-nopad because tokens often appear in URL fragments where = needs to be percent-encoded — annoying enough that the standard drops it.

When to use Base64

• Embedding binary in a text format. JSON doesn't have a binary type; SVG/HTML attributes can't carry raw bytes; YAML and TOML are text-only. Base64 (or hex) is the bridge.
• HTTP Basic auth. Authorization: Basic dXNlcjpwYXNz — Base64 of user:pass. Not encryption, just transit-safe encoding of the credential pair.
• Inline images and small assets. A data:image/png;base64,... URI inlines a small image into HTML/CSS. Saves a round trip; the 33% penalty doesn't matter for small files.
• PEM certificates and keys. X.509 certs, RSA keys, and SSH public keys are stored as Base64 with header/footer lines for human-readable diffs and easy copy-paste.
• JWT tokens. The three dot-separated segments of a JWT are each base64url-encoded JSON or signature bytes. Compact, URL-safe, parseable in one regex.

Skip Base64 when bandwidth or storage is tight and the channel can carry binary directly (binary HTTP/2 frames, BSON, MessagePack). Skip it when you actually need encryption — Base64 is not a cipher.

Base64 vs other binary-to-text encodings

Encoding	Alphabet size	Expansion	Notes
Hex (Base16)	16	2× (100%)	Trivial to read; doubles the size
Base32	32	1.6× (60%)	Case-insensitive; used in DNS-based TXT records
Base64	64	1.33× (33%)	Universal; default for MIME
Base85 (Ascii85)	85	1.25× (25%)	Adobe PDF; trickier alphabet
Base91	91	1.23× (23%)	Niche; needs full ASCII printable range
Quoted-printable	variable	~1.05× (if mostly ASCII)	MIME's other encoding; degrades on binary

Base64 wins on universality. Higher-base encodings give better ratios but use characters that aren't safe in every channel. Base32 wins when the channel is case-insensitive (DNS, voice-readout, OCR). Hex wins on debuggability — you can read it at a glance.

Pseudo-code

// Base64 encode.
ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

function base64Encode(bytes):
    out = []
    for i = 0; i < bytes.length; i += 3:
        b1 = bytes[i]
        b2 = bytes[i+1] if i+1 < bytes.length else 0
        b3 = bytes[i+2] if i+2 < bytes.length else 0
        triple = (b1 << 16) | (b2 << 8) | b3
        out.append(ALPHA[(triple >> 18) & 0x3F])
        out.append(ALPHA[(triple >> 12) & 0x3F])
        out.append(ALPHA[(triple >>  6) & 0x3F] if i+1 < bytes.length else '=')
        out.append(ALPHA[triple & 0x3F]              if i+2 < bytes.length else '=')
    return join(out)

// Base64 decode (reverse mapping).
function base64Decode(text):
    text = text.strip("=")
    out = bytes()
    for i = 0; i < text.length; i += 4:
        v1 = ALPHA.index(text[i])
        v2 = ALPHA.index(text[i+1])
        v3 = ALPHA.index(text[i+2]) if i+2 < text.length else 0
        v4 = ALPHA.index(text[i+3]) if i+3 < text.length else 0
        triple = (v1 << 18) | (v2 << 12) | (v3 << 6) | v4
        out.append((triple >> 16) & 0xFF)
        if i+2 < text.length: out.append((triple >> 8) & 0xFF)
        if i+3 < text.length: out.append(triple & 0xFF)
    return out

JavaScript implementation

const ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';

function base64Encode(bytes) {
  let out = '';
  for (let i = 0; i < bytes.length; i += 3) {
    const b1 = bytes[i];
    const b2 = i + 1 < bytes.length ? bytes[i + 1] : 0;
    const b3 = i + 2 < bytes.length ? bytes[i + 2] : 0;
    const t = (b1 << 16) | (b2 << 8) | b3;
    out += ALPHA[(t >> 18) & 0x3F];
    out += ALPHA[(t >> 12) & 0x3F];
    out += i + 1 < bytes.length ? ALPHA[(t >> 6) & 0x3F] : '=';
    out += i + 2 < bytes.length ? ALPHA[t & 0x3F]        : '=';
  }
  return out;
}

function base64Decode(s) {
  s = s.replace(/=+$/, '');
  const out = [];
  for (let i = 0; i < s.length; i += 4) {
    const v1 = ALPHA.indexOf(s[i]);
    const v2 = ALPHA.indexOf(s[i + 1]);
    const v3 = i + 2 < s.length ? ALPHA.indexOf(s[i + 2]) : 0;
    const v4 = i + 3 < s.length ? ALPHA.indexOf(s[i + 3]) : 0;
    const t = (v1 << 18) | (v2 << 12) | (v3 << 6) | v4;
    out.push((t >> 16) & 0xFF);
    if (i + 2 < s.length) out.push((t >> 8) & 0xFF);
    if (i + 3 < s.length) out.push(t & 0xFF);
  }
  return new Uint8Array(out);
}

const msg = new TextEncoder().encode('Man');
console.log(base64Encode(msg));            // "TWFu"
console.log(new TextDecoder().decode(base64Decode('TWFu')));  // "Man"

// Built-in alternative for browsers:
console.log(btoa('Man'));   // "TWFu"
console.log(atob('TWFu'));  // "Man"

Python implementation

import base64

# Standard
encoded = base64.b64encode(b'Man')
print(encoded)               # b'TWFu'
print(base64.b64decode(encoded))  # b'Man'

# URL-safe variant (replaces + with -, / with _)
print(base64.urlsafe_b64encode(b'\xff\xfb'))  # b'__s='

# Manual implementation, for instruction:
ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'

def b64_encode(data: bytes) -> str:
    out = []
    for i in range(0, len(data), 3):
        chunk = data[i:i+3]
        n = len(chunk)
        b1 = chunk[0]
        b2 = chunk[1] if n > 1 else 0
        b3 = chunk[2] if n > 2 else 0
        t = (b1 << 16) | (b2 << 8) | b3
        out.append(ALPHA[(t >> 18) & 0x3F])
        out.append(ALPHA[(t >> 12) & 0x3F])
        out.append(ALPHA[(t >>  6) & 0x3F] if n > 1 else '=')
        out.append(ALPHA[t & 0x3F]          if n > 2 else '=')
    return ''.join(out)

print(b64_encode(b'Man'))    # TWFu
print(b64_encode(b'Ma'))     # TWE=
print(b64_encode(b'M'))      # TQ==

Common Base64 bugs and edge cases

• Forgetting URL-safe substitution. Base64 output sent into a URL query string corrupts on parsers that interpret + as space. Decoder receives garbage. Use base64url any time the output might enter a URL.
• Stripping padding when decoder requires it. Some strict decoders reject inputs that aren't a multiple of 4 characters. JWT decoders typically tolerate missing =; Java's Base64.getDecoder() does not. Always know your decoder's padding policy.
• Whitespace in the input. MIME mandates CRLF every 76 characters. A naive decoder that doesn't skip whitespace will reject these inputs. Use a lenient decoder or pre-strip whitespace.
• Treating Base64 as encryption. Beginners sometimes obscure passwords by Base64-encoding them. This protects against literally nothing — any browser console decodes it instantly. Use real cryptography for secrecy.
• UTF-8 round-trip mistakes. Base64 operates on bytes, not characters. Encoding "héllo" in JavaScript with btoa throws on non-Latin-1 characters; you must first UTF-8 encode to bytes.
• Mismatched alphabets. A token encoded with base64url cannot be decoded with the standard alphabet — the - and _ characters are unknown. Most libraries default to standard; JWT libraries default to url. Mixing them silently produces invalid output.

Performance in real systems

• Browser btoa/atob: ~500 MB/s on modern V8; runs in main-thread JS, can block on large inputs > 1 MB.
• Node Buffer.from(...).toString('base64'): ~2 GB/s with native code; preferred over btoa in Node.
• SIMD libraries (base64-simd, fastbase64): 10-15 GB/s on AVX-512; used in JSON parsers (simdjson) for big inline binary fields.
• JWT signing roundtrip: <1 ms total for typical 500-byte tokens; Base64 is a fraction of that.
• MIME email decode: Negligible — even on 1990s hardware Base64 was never the bottleneck of email transport.

Base64 is the encoding that has long since stopped being interesting to optimize — fast enough on any modern hardware that the only reason to think about it is correctness. Get the alphabet right, get the padding right, and ship.