2026-08-31 · 8 min read
- base64
- encoding
- interoperability
Base64 converts each group of three input bytes into four symbols. When the final group contains one or two bytes, only part of the last symbol carries data; the remaining pad bits should be zero, and the standard alphabet uses equals signs to mark the shortened group.
Permissive decoders may ignore whitespace, accept mixed alphabets, infer missing padding, or discard non-zero pad bits. That tolerance creates multiple textual representations and can hide corruption, break signatures, or produce inconsistent validation across services.
Choose one protocol profile
Standard Base64 uses plus and slash, while Base64url uses hyphen and underscore. MIME commonly permits wrapped lines; compact tokens and JSON API fields usually do not. Padding requirements also vary by protocol.
- Name the exact alphabet in the API contract.
- State whether terminal padding is required, optional, or forbidden.
- State whether any ASCII whitespace is accepted.
- Set encoded and decoded length limits before allocation.
Validate canonical form
Check characters, length, padding position, and unused pad bits before or during decoding. For unsigned data, decode and re-encode with the selected profile, then require the canonical output to match the accepted textual form.
Canonicalization reduces cache-key ambiguity and makes textual equality meaningful. If backward compatibility requires legacy variants, normalize once at the edge and record the exception rather than allowing lenient behavior throughout the system.
Preserve signed representations
Some protocols sign the encoded characters, not only the decoded bytes. Adding padding, changing alphabets, removing line breaks, or re-encoding before signature verification can invalidate a legitimate message or accidentally verify a different representation.
- Follow the signature specification's exact input construction.
- Keep raw signed segments available until verification completes.
- Compare decoded-byte hashes only as a diagnostic aid.
- Never treat Base64 decoding as authenticity or confidentiality.
Build interoperability tests
Use Flashman's Base64 tool for public fixtures, diff tool for textual variants, hash tool for byte-level comparisons, JSON formatter for escaped wrappers, and URL tool to expose query-string alphabet problems.
Cover zero-, one-, and two-byte remainders, both alphabets, omitted and extra padding, mixed alphabets, non-zero pad bits, line wrapping, Unicode-to-byte conversion, invalid characters, large inputs, and representations covered by signatures.