Base64 vs base64url: dois caracteres que fazem diferença

Resumo. Base64 e base64url são a mesma codificação, exceto por três detalhes definidos no RFC 4648: + vira -, / vira _, e o padding = é removido. Use base64url sempre que o valor codificado viajar em uma URL, JWT ou cookie assinado; use Base64 padrão para anexos de e-mail, HTTP Basic Auth e URIs de dados.

Ambos são definidos no RFC 4648. O Base64 padrão (§4) e o base64url (§5) diferem em exatamente três detalhes: duas substituições de alfabeto e o tratamento do padding. Só isso. Mas misturá-los quebra JWTs, cookies assinados e tudo que viaja em uma URL.

A diferença

A mesma entrada, ambas as codificações

Codificando https://example.com/?q=hello world:

• Padrão: aHR0cHM6Ly9leGFtcGxlLmNvbS8/cT1oZWxsbyB3b3JsZA==
• Base64url: aHR0cHM6Ly9leGFtcGxlLmNvbS8_cT1oZWxsbyB3b3JsZA

Note que o / na forma padrão vira_ em base64url, e o == final é removido.

Por que URLs precisam de sua própria variante

O alfabeto Base64 padrão inclui + e/. Ambos são reservados na sintaxe de URL:

• / é o separador de caminho.
• + é, por convenção em query strings codificadas por formulário, interpretado como espaço.
• = é o delimitador chave-valor em query strings.

Incorporar uma string Base64 padrão em uma URL requer codificação percentual dos três: + vira%2B, / vira %2F,= vira %3D. A string fica maior e mais difícil de ler. O base64url evita a codificação percentual escolhendo caracteres que já são seguros para URL.

Por que o padding é opcional no base64url

O Base64 padrão sempre completa a saída para um múltiplo de 4 caracteres usando =. Isso não é matematicamente necessário — o decodificador pode inferir o comprimento original a partir do comprimento da saída módulo 4. O padding existe para decodificadores de streaming que precisam saber o limite entre blocos concatenados.

O base64url omite o padding porque: (a) é redundante, (b) = precisa de codificação percentual em URLs, e (c) sinais de igual no final de URLs às vezes confundem analisadores de caminho, CDNs e chaves de cache.

Onde cada um é usado

O problema na decodificação

O decodificador Base64 padrão de muitas bibliotecas falha com entradas base64url. O base64.b64decode do Python rejeita - e _; o Buffer.from(s, "base64") do Node.js é permissivo, mas o inverso (.toString("base64")) produz Base64 padrão.

Soluções entre linguagens: substitua antes de decodificar.

// base64url → Base64 padrão
const standard = base64url
  .replace(/-/g, "+")
  .replace(/_/g, "/")
  .padEnd(Math.ceil(base64url.length / 4) * 4, "=");

Melhor: use uma biblioteca que suporte explicitamente base64url (Node 16+ tem Buffer.from(s, "base64url"); Python tem base64.urlsafe_b64decode).

A regra prática

Se o valor codificado aparecer em uma URL, em um JWT, em um cookie assinado ou como segmento de caminho — use base64url. Se for para um anexo de e-mail, cabeçalho HTTP (exceto cookies) ou URI de dados JSON — use Base64 padrão.

Nosso codificador Base64 suporta ambas as variantes, com alternância de alfabeto. O decodificador JWT assume base64url porque o padrão exige isso.

Fatos numéricos

• Comprimento codificado: ambas as variantes expandem binário exatamente 4/3 (ceil(n/3)*4). 100 bytes de entrada → 136 chars de saída em Base64 padrão, ou 134 chars sem padding em base64url.
• Overhead de padding: o Base64 padrão adiciona 0, 1 ou 2 chars = por string codificada — no máximo 1,5% de penalidade de tamanho para payloads curtos, negligível para longos.
• Custo de codificação percentual em URLs: cada + / = no Base64 padrão se expande para 3 bytes (%2B %2F %3D) quando codificado em URL. Para um JWT de 512 chars, isso são tipicamente 30 a 60 bytes desperdiçados — o base64url evita completamente.
• Tamanho do alfabeto: 64 caracteres em ambos, então cada caractere de saída carrega exatamente 6 bits de entrada.
• Tamanhos dos segmentos JWT (RFC 7519): cabeçalho típico 40-50 chars, payload 100-400 chars, assinatura HS256 43 chars (exatamente 32 bytes / 6 = 43 chars base64url, sem padding).
• Throughput: o Buffer.from(s, "base64") do Node 20 decodifica a ~2 GB/s; o base64.b64decode do Python a ~600 MB/s em laptop de 2024.

Matriz de decisão

Fontes

• RFC 4648 — The Base16, Base32, and Base64 Data Encodings — rfc-editor.org/rfc/rfc4648 (§4 padrão, §5 seguro para URL).
• RFC 7519 — JSON Web Token (JWT), exige base64url sem padding — rfc-editor.org/rfc/rfc7519.
• RFC 7636 — OAuth 2.0 PKCE, §4.1 especifica desafio SHA-256 codificado em base64url — rfc-editor.org/rfc/rfc7636.