Ferramentas de desenvolvedor · Codificador e decodificador Base64
Por que o Base64 colado não consegue decodificar: quebras de linha, novas linhas e aspas inteligentes
· Por que é importante
base64 codificação
Base64 raramente quebra em trânsito; ele quebra na área de transferência. Esta postagem cataloga as falhas de copiar e colar que produzem erros de caracteres e comprimento inválidos e como identificar cada uma delas rapidamente.
A chave que funcionou no terminal e falhou no navegador — um caractere invisível e uma pesquisa de duas horas
Um engenheiro copiou uma chave API de um terminal para testá-la em um script. A chave funcionou bem no terminal, mas falhou com caracteres inválidos quando colada na ferramenta do navegador. Duas horas depois, após pesquisar código, configuração e documentação, eles descobriram um caractere invisível. Uma nova linha no final da chave, adicionada por echo ou copiada de uma linha de prompt do terminal, tornou-se um caractere extra que quebrou o decodificador Base64. A chave estava correta; a área de transferência não era. Os dados Base64 são confiáveis quando transmitidos eletronicamente, somados e verificados. Ele quebra quase exclusivamente durante a cópia e colagem manual.
Quebra de linha em terminais, novas linhas finais da saída de comando, substituição de aspas inteligentes em editores de rich text e caracteres Unicode ocultos de copiar e colar entre aplicativos diferentes, todos introduzem erros que parecem que Base64 está quebrado quando o problema real está na forma como foi copiado. Esta postagem cataloga as falhas mais comuns e mostra como identificar e corrigir cada uma delas rapidamente. O alfabeto Base64 consiste em letras maiúsculas e minúsculas, dígitos, sinais de adição, barras e caracteres de preenchimento (sinal de igual). RFC 4648 é específico: uma string Base64 padrão contém apenas esses caracteres mais espaços em branco opcionais se as linhas forem quebradas.
Quebra de linha de terminais, clientes de e-mail e formatação PEM — por que uma quebra de coluna 76 é boa para alguns decodificadores e fatal para outros
Muitas ferramentas toleram desvios: elas aceitam variantes seguras para URL usando travessões e sublinhados em vez de mais e barra, ou ignoram novas linhas. Um decodificador estrito que segue RFC rejeita qualquer coisa fora do conjunto de caracteres esperado e falha com um erro de caractere inválido. A mensagem de erro geralmente nomeia o caractere incorreto ou indica que a string não pode ser decodificada. Ao colar Base64 de um e-mail, terminal, histórico de bate-papo ou documento formatado, caracteres invisíveis ou substituições de caracteres geralmente aparecem e causam falha na decodificação. Os dados em si estão bons; a transferência da área de transferência o corrompeu.
A quebra de linha é a fonte mais comum de falhas de Base64 coladas e também a mais facilmente corrigida. As ferramentas de terminal agrupam a saída em 76 caracteres por linha ou às vezes 80, inserindo uma nova linha e continuando na próxima linha. Muitos codificadores, incluindo algumas bibliotecas de codificação Base64, agrupam sua saída no mesmo limite de 76 caracteres para compatibilidade com e-mail MIME. Quando você copia uma string Base64 agrupada de um terminal, as novas linhas aparecem.
Trilhando novas linhas das ferramentas de eco e área de transferência – o byte extra que se torna um caractere extra
Alguns decodificadores aceitam e ignoram novas linhas automaticamente. Outros os rejeitam como caracteres inválidos. A correção é remover todas as novas linhas e espaços em branco. Se uma string Base64 estiver agrupada em várias linhas no terminal, selecione todas as linhas, copie-as em um editor e exclua todas as novas linhas.
Copie a string de linha única resultante e cole-a no decodificador. Esta é a primeira coisa a tentar quando uma colagem falha. As novas linhas dos utilitários de eco e área de transferência são outro culpado comum. O comando echo $API_KEY imprime a chave seguida por uma nova linha, que é o comportamento padrão do comando. Se você copiar essa saída diretamente, a nova linha será incluída na cópia. Alguns terminais adicionam uma nova linha extra quando você copia, e alguns gerenciadores de área de transferência preservam ou duplicam novas linhas. O sintoma é o mesmo da quebra de linha: um caractere extra no final da string que não pertence ao Base64.
Citações inteligentes, espaços inseparáveis e caracteres de largura zero – como os editores de rich text reescrevem o texto simples
A correção é igualmente simples: apare as pontas da string colada em seu editor antes de tentar decodificar. Remova os espaços em branco iniciais e finais e quaisquer caracteres que se pareçam com novas linhas. Se a string for curta o suficiente, você poderá digitá-la manualmente novamente, mas para teclas longas, o corte manual cuidadoso é mais rápido. Aspas inteligentes, espaços inseparáveis e outras substituições Unicode são armadilhas sutis. Editores de rich text como o Word convertem automaticamente aspas retas em aspas curvas, convertem três hífens em um travessão e convertem certas sequências de espaços em espaços inseparáveis. Se alguém colar uma string Base64 em um documento e você copiá-la do documento formatado para uma ferramenta, essas substituições ocorrerão.
Uma aspa dupla direta (") torna-se um par curvado à esquerda e à direita, nenhum dos quais é Base64 válido. Um espaço inseparável (U + 00A0) parece idêntico a um espaço normal, mas tem um código de caractere diferente e não é reconhecido como espaço em branco por todos os analisadores. A solução é colar primeiro em um editor de texto simples, que descarta toda a formatação. Se você colar de um documento do Word ou de um bate-papo formatado, primeiro cole em um editor de texto simples ou em uma área de texto HTML e verifique se há caracteres estranhos. Em seguida, copie da versão em texto simples para usar em sua ferramenta.
Perda de truncamento e preenchimento — a verificação length-modulo-4 que informa que faltam caracteres
O truncamento acontece quando uma string é cortada durante a cópia ou colagem. Uma string Base64 muito longa pode exceder os limites da área de transferência em alguns sistemas ou falhar na cópia devido a bugs no aplicativo. O resultado é uma string mais curta e incompleta. Uma string Base64 deve ter um comprimento múltiplo de quatro após a aplicação do preenchimento. Se um comprimento não for múltiplo de quatro, ele será truncado ou corrompido. A mensagem de erro geralmente indica que o comprimento da string é inválido ou que falta um caractere. A correção requer saber o que foi copiado originalmente.
Se você puder verificar a fonte novamente, copie-a novamente com cuidado. Caso contrário, o truncamento será irrecuperável. A perda de preenchimento é um problema relacionado: o preenchimento Base64 com sinais de igual às vezes é removido para economizar alguns bytes. Alguns aplicativos omitem o preenchimento e outros exigem isso. Se uma string foi originalmente preenchida e o preenchimento foi perdido, adicione-a novamente. Uma string Base64 deve ter sinais de igual à direita 0, 1 ou 2 de modo que o comprimento total seja um múltiplo de quatro. Se não tiver nenhum e o comprimento não for múltiplo de quatro, o preenchimento pode ter sido perdido.
Exemplo resolvido: reparando uma string enrolada e truncada — limpando-a passo a passo até que ela seja decodificada
Um exemplo prático mostra esses reparos passo a passo. Suponha que uma chave API copiada apareça como esta em seu editor: VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0Cg==. Comece identificando problemas. O final Cg== é ímpar; Cg é base64 para um caractere de nova linha (hex 0A), e o == extra sugere que algo foi adicionado. Remova o Cg== final e tente apenas VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0. Isso ainda não está certo; o comprimento é de 37 caracteres, não um múltiplo de quatro. Corte novamente: VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0 (35 caracteres, ainda errado). Verifique a fonte original. A string correta é VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0 (32 caracteres) com preenchimento adequado: VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0. Adicione: VGhpcyBpcyBub3QgcmVhbGx5IGEgc2VjcmV0=.
Teste no decodificador. Isso é decodificado para Isso não é realmente um segredo. Em cada etapa, use o codificador e decodificador Base64 para testar a string atual, corrigir o problema identificado e testar novamente até que seja decodificado. A corrupção dentro dos próprios bytes Base64 não pode ser corrigida pelo decodificador. Se os bytes estiverem realmente corrompidos em trânsito, transmissão ou armazenamento, o próprio Base64 não poderá detectá-los. O RFC especifica caracteres válidos; qualquer caractere fora desse conjunto é o trabalho do decodificador a ser capturado. Qualquer corrupção de byte, como um 0 se tornando um 1 no meio de um caractere Base64, produz um código de caractere totalmente diferente e é indetectável apenas pelo Base64.
O que isso não cobre – corrupção dentro dos bytes codificados, que o próprio Base64 não consegue detectar
Somas de verificação ou assinaturas digitais são usadas para detectar esse tipo de corrupção e devem ser calculadas nos dados binários originais antes da codificação Base64. Se você decodificar uma string Base64 e o resultado for lixo ou diferente do esperado, a corrupção ocorreu antes da codificação ou durante a transmissão, não durante a etapa de copiar e colar. Isso é raro na prática. A maioria das falhas são problemas de copiar e colar como os acima. Uma abordagem sistemática para depurar falhas de copiar e colar Base64 é testar cada problema potencial em ordem. Primeiro, remova todos os espaços em branco e novas linhas. Em seguida, corte os espaços iniciais e finais e quaisquer caracteres perdidos.
Em seguida, verifique o comprimento módulo quatro e adicione preenchimento, se necessário. Cole cada versão no codificador e decodificador Base64 e veja se ela decodifica. Se a verificação do comprimento falhar, pergunte se a string foi truncada e recupere-a da fonte original. Se a verificação do alfabeto falhar e você vir caracteres incomuns, procure aspas inteligentes ou substituições Unicode e substitua-as por equivalentes ASCII. Use uma ferramenta online que mostre caracteres inválidos por nome para que você possa identificá-los e removê-los. O codificador e decodificador Base64 faz isso para cada caractere inválido, informando exatamente qual caractere não está no alfabeto.
Conclusão: verifique o comprimento e o alfabeto antes de culpar os dados – como o codificador e decodificador Base64 oferece um local rápido para testar cada reparo
Use esse feedback para corrigir cada caractere e continue até que a string seja decodificada. A prevenção é mais fácil do que a depuração. Quando você souber que precisará de uma string Base64 novamente, copie-a de uma forma que preserve a formatação. Não cole-o em um documento rich text. Armazene-o em um arquivo de texto simples ou em uma área de texto designada que não faça substituições. Se alguém lhe enviar uma string Base64 em uma mensagem formatada, peça para reenviá-la em formatação de código ou texto simples. Se você precisar copiar de uma fonte formatada, cole primeiro em um editor de texto simples e verifique a string antes de usá-la.
Teste a string no codificador e decodificador Base64 assim que a tiver, antes de confiar nela. Se falhar, você pode solicitar uma nova cópia enquanto a fonte ainda estiver acessível. Se você esperar até que a string fique antiga ou a fonte desapareça, consertar o truncamento ou a corrupção se tornará impossível. O codificador e decodificador Base64 oferece um local local rápido para testar qualquer string antes de usá-la. Teste com antecedência e com frequência para que as falhas de copiar e colar sejam detectadas imediatamente.