Codificación Base64 en Bash: una guía completa

Tienes bytes y necesitas una cadena. Un archivo de texto que debe vivir dentro de un cuerpo JSON. Una imagen que tiene que caber en una línea de configuración. Un token que va a viajar por una URL, una variable de entorno o un encabezado HTTP. Una clave privada que le toca vivir en un almacén de certificados. Este es el trabajo de todos los días de la codificación Base64 en la shell, y la respuesta de la shell es un único comando, pequeño y notablemente portable.

El trueque en una respiración: Base64 reescribe cada tres bytes de datos crudos como cuatro caracteres de un alfabeto de 64 letras (A-Z, a-z, 0-9, más + y /), rellenando la cola con uno o dos signos = cuando el número de bytes no es un múltiplo de tres. La página de inicio de este sitio explica el formato por completo; aquí dedicamos nuestro tiempo a producir el texto, a elegir el dialecto correcto para el destino, y a pagar la factura del tamaño con los ojos bien abiertos. Un número que conviene guardar en el bolsillo: la forma codificada normalmente es un tercio más grande que el original, cuatro caracteres por cada tres bytes, y ese número vuelve a aparecer sin parar.

El reparto es pequeño. El comando base64 de coreutils (GNU o la familia Rust uutils más reciente), basenc de la misma familia para el dialecto seguro para URL, openssl base64 para las máquinas sin coreutils, el applet de BusyBox para los sistemas embebidos, y el sabor BSD en macOS. Cinco herramientas, un trabajo, unos pocos flags que valen la pena conocer.

Elige tu codificador

Todas estas herramientas leen bytes de la entrada estándar o de un archivo y escriben texto a la salida estándar, así que todas encajan en las mismas tuberías. Las diferencias son el envolvimiento de líneas por defecto y los dialectos disponibles:

Lee esa columna de envolvimiento dos veces, porque es la diferencia silenciosa entre las familias. Coreutils y BusyBox envuelven a 76 por defecto, OpenSSL envuelve a 64, y la herramienta BSD no envuelve en absoluto. Ninguna se equivoca; simplemente heredaron convenciones distintas (MIME dice 76, PEM dice 64, y la herramienta BSD es simplemente más vieja que el hábito del envolvimiento). Cuando a tu consumidor le importe, fija el ancho explícitamente y no confíes nunca en el predeterminado.

Primero el texto: el salto de línea invisible

Codificar texto en la shell empieza con una trampa: echo añade un salto de línea. Esas cinco letras "hello" se convierten en seis bytes en el momento en que pasan por echo, y el sexto byte viaja de contrabando a la salida, invisible y permanente:

echo "hello" | base64

Eso imprime aGVsbG8K, y el carácter final codifica el salto de línea. La solución es la que deberías usar para el texto donde el recuento de bytes importa: printf con un formato, sin adornos:

printf '%s' "hello" | base64

Ahora la salida es aGVsbG8=, exactamente cinco bytes, y el último carácter es un signo de relleno en vez de un byte vivo. La misma regla se aplica a los here-strings, que añaden un salto de línea final igual que echo: base64 <<< "hello" te da de nuevo la versión aGVsbG8K. Cuando tengas dudas, pregúntate qué es el último byte antes de codificarlo.

Para cualquier cosa que quieras en una sola línea, añade -w 0 (o los primos de -w 0 de abajo), que también elimina el salto de línea final que el comando emitiría de lo contrario:

printf '%s' "hello world and more" | base64 -w 0

Eso es una línea limpia e ininterrumpida, sin salto de línea final, lista para caer en una URL, un valor JSON o un archivo de configuración sin ninguna ceremonia adicional.

Archivos y el ancho de envolvimiento

Los archivos son el caso común, y toda implementación acepta un argumento FILE, que mantiene los bytes por completo alejados del mecanismo de comillas de la shell:

base64 -w 0 report.pdf > report.b64

Sin -w 0, la salida llega envuelta cada 76 caracteres, que es exactamente lo que quiere un consumidor MIME:

base64 report.pdf > report.mime.b64

El ancho es un dial que controlas por consumidor. Setenta y seis es la convención MIME del RFC 2045, sesenta y cuatro es la convención PEM que usan certificados y claves, y cero significa una línea ininterrumpida para URLs y APIs:

base64 -w 64 key.bin | head -2

Si el consumidor vive en Windows y espera finales de línea CRLF, convierte después del envolvimiento, no antes:

base64 -w 76 attachment.bin | sed 's/$/\r/' > attachment.crlf.b64

En el camino de OpenSSL, el equivalente al modo de una línea es el flag -A, que además suprime el salto de línea final:

openssl base64 -A < report.pdf

Antes de enviar un archivo envuelto, una comprobación de tamaño no cuesta nada y atrapa un número sorprendente de errores (un archivo codificado dos veces, un archivo codificado con la entrada equivocada):

wc -c report.pdf
base64 report.pdf | wc -c

El segundo número debería ser unos cuatro tercios del primero, más un byte por cada línea envuelta para los saltos de línea. Si es muy distinto, detente y mira qué es lo que realmente le diste al codificador.

Base64 seguro para URL: intercambiar los dos caracteres escurridizos

Dos caracteres del alfabeto estándar, + y /, son los niños problemáticos: un + en la cadena de consulta de una URL significa un espacio, un / puede parecer un separador de ruta, y ambos fuerzan la codificación por porcentaje en el momento en que la cadena entra en una URL, una cookie o un nombre de archivo. La sección 5 del RFC 4648 lo resuelve con un dialecto que sustituye exactamente esos dos caracteres por - y _, y descarta el relleno, porque una URL rara vez necesita anunciar la longitud exacta en bytes.

La receta de la shell es un intercambio más un recorte, un paso por tr para el alfabeto y otro para quitar el relleno:

printf '\376\117\202' | base64 -w 0 | tr '+/' '-_' | tr -d '='

Esos tres bytes normalmente se codifican como /k+C, que sería feo en una URL; la tubería lo convierte en _k-C, cuatro caracteres que pueden viajar a cualquier parte. El intercambio es posicional, así que es fácil confundir la dirección: la codificación va tr '+/' '-_' (el más se vuelve guion, la barra se vuelve guion bajo), y la inversa, que pertenece a la decodificación, va tr '_-' '/+'. Una dirección confundida no da error, solo produce bytes distintos, que es el peor tipo de bug para soltar al mundo.

El dialecto importa siempre que la cadena sale del control de la shell: segmentos de JWT, tokens en cadenas de consulta, valores en cookies o nombres de archivo, y cualquier identificador que otro sistema leerá como parte de una URL. El basenc de GNU produce el dialecto de forma nativa, con el relleno todavía en su sitio:

printf '%s' "hello" | basenc --base64url

Quita el relleno con tr -d '=' si el consumidor quiere la forma sin relleno, como la mayoría.

Acuñando un JWT en la shell

Los JSON Web Tokens son el consumidor más visible del Base64 seguro para URL en el mundo de las APIs. Un JWT compacto son tres segmentos base64url unidos por puntos: la cabecera, el payload y la firma, según el RFC 7515. Los dos primeros son JSON plano; la firma es un resumen binario de los dos primeros segmentos unidos por un punto, que es exactamente el tipo de cosa en lo que openssl es bueno.

key="supersecretkey"
h=$(printf '%s' '{"alg":"HS256","typ":"JWT"}' | base64 -w 0 | tr '+/' '-_' | tr -d '=')
p=$(printf '%s' '{"sub":"42","name":"homer"}' | base64 -w 0 | tr '+/' '-_' | tr -d '=')
s=$(printf '%s' "$h.$p" | openssl dgst -sha256 -hmac "$key" -binary | base64 -w 0 | tr '+/' '-_' | tr -d '=')
printf '%s.%s.%s\n' "$h" "$p" "$s"

Eso imprime un JWT HS256 compacto que cualquier librería estándar de cualquier plataforma aceptará. Fíjate en la división del trabajo: la parte Base64 es el alfabeto, la parte openssl dgst -sha256 -hmac es la criptografía, y el unir con puntos es el formato. Mantén los tres trabajos separados en tu cabeza y la tubería se mantiene obvia.

Tres precauciones para el campo. Primera, el MAC se computa sobre el texto ASCII de los dos primeros segmentos más el punto, así que los segmentos ya deben estar en su forma base64url final cuando los firmes; reenvolver o rellenar de nuevo después de firmar rompe el token. Segunda, la clave se queda fuera del token: la firma demuestra quién firmó, la clave mantiene el secreto en secreto. Tercera, acuñar en un script de la shell es una herramienta de pruebas y automatización, no un reemplazo para el servidor que de verdad emitirá y verificará estos tokens, y un token acuñado con alg: none no demuestra nada en absoluto.

Data URIs: archivos viajando dentro de cadenas

El RFC 2397 define el esquema de URL data:, y su forma Base64 deja vivir a un archivo dentro de una URL: data:, luego un tipo de medio opcional, luego ;base64 cuando el payload está codificado en Base64, luego una coma, luego los datos. Omitir el tipo de medio y el predeterminado es text/plain;charset=US-ASCII, que es una trampa que conviene conocer, porque la mayoría de la gente quiere decir una imagen o un documento JSON, no texto ASCII.

printf 'data:text/plain;base64,%s\n' "$(printf '%s' "hi there" | base64 -w 0)"

Eso imprime data:text/plain;base64,aGkgdGhlcmU=, una URL completa y autosuficiente que un navegador mostrará encantado. Para una imagen, la misma forma con un tipo de medio de verdad:

printf 'data:image/png;base64,%s\n' "$(base64 -w 0 icon.png)" > icon.uri

Pega el resultado en el src de una etiqueta img de HTML o en un background de CSS, y la imagen viaja con el documento, sin segunda petición HTTP. Las trampas son todas de tamaño: el propio RFC dice que el esquema solo es útil para valores cortos, los navegadores imponen sus propios límites de longitud de URL, cada byte inline cuesta el sobrecoste del 33 por ciento encima del tamaño propio de la imagen, y una página llena de data URIs es una página sin ninguna historia de caché para esas imágenes. Para iconos pequeños y gráficos incrustados de una sola vez es un gusto; para una biblioteca de fotos es un impuesto.

Secretos, configuración y variables de entorno

Base64 aparece en el trabajo de configuración y secretos por una razón concreta: convierte bytes arbitrarios, incluidos espacios, comillas y saltos de línea, en una cadena que sobrevive a un export, una línea de configuración o un campo JSON sin ninguna acrobacia de comillas. Kubernetes es el ejemplo más visible: cada campo bajo .data de un secreto es Base64, así que crear un secreto en la shell es solo codificar:

kubectl create secret generic app --from-literal=password='s3cret'

El servidor de API guarda la contraseña como czNjcmV0 bajo .data, y cualquier nodo con acceso al secreto puede leerla de vuelta con una decodificación. El mismo movimiento funciona para tus propios archivos de configuración:

export API_TOKEN_B64=$(printf '%s' "$API_TOKEN" | base64 -w 0)

O, para un archivo que la aplicación lee al arrancar:

printf 'token=%s\n' "$(printf '%s' "$API_TOKEN" | base64 -w 0)" >> app.conf

Ahora viene la advertencia que merece un lugar en la pared: Base64 es codificación, no cifrado. La sección de seguridad del RFC 4648 es directa al respecto y señala que la codificación "oculta visualmente información que de otro modo se reconocería fácilmente, como contraseñas, pero no proporciona ninguna confidencialidad computacional", y que exactamente este malentendido ha causado incidentes de seguridad reales cuando alguien pegó un intercambio de protocolo "protegido" en un reporte de error y reveló accidentalmente las credenciales. Si el valor debe ser secreto, cifrálo (y luego codifica en Base64 el texto cifrado para guardarlo); si Base64 es todo lo que tienes, trata el valor codificado como texto plano en el momento en que sale de la pantalla.

Unicode, conjuntos de caracteres y los bytes que hay debajo

El codificador lee bytes, no caracteres, y la shell le entrega los bytes que hayan producido el locale y el comando. Para texto UTF-8 eso es normalmente exactamente lo que quieres: la é de héllo ya ocupa dos bytes, c3 a9, y la codificación simplemente los lleva consigo:

printf 'h\xc3\xa9llo' | base64

Eso imprime aMOpbGxv, y un consumidor UTF-8 del otro lado recupera héllo, byte a byte. Los problemas empiezan cuando la fuente no es UTF-8. Un archivo Latin-1 con la misma palabra guarda un único byte e9 para la é, y codificar esos bytes tal cual produce texto que solo un consumidor Latin-1 puede leer de vuelta. Convierte primero, codifica después:

iconv -f ISO-8859-1 -t UTF-8 note.txt | base64 -w 0

Dos hechos más a nivel de byte. Un BOM UTF-8, tres bytes al frente de un archivo, se codifica como 77u/ y se quedará al frente de tu salida decodificada para siempre a menos que lo quites primero:

sed '1s/^\xef\xbb\xbf//' file.txt | base64 -w 0

Y el locale nunca cambia la codificación en sí, porque el codificador es una máquina de bytes; solo cambia lo que escribiste. Cuando la salida se vea mal, revisa los bytes que diste, no la codificación que corriste.

Correo, APIs y subidas

El correo es donde Base64 aprendió sus modales, y los modales siguen siendo la convención. SMTP históricamente solo llevaba ASCII de 7 bits, así que los adjuntos viajan como Base64 envuelto cada 76 caracteres con finales de línea CRLF, según el RFC 2045. Producir esa forma exacta para una parte MIME es el envolvimiento más la conversión de finales de línea:

base64 -w 76 attachment.bin | sed 's/$/\r/' > attachment.mime

La vieja guardia sigue de servicio en los sistemas embebidos: el uuencode de BusyBox con el flag -m produce Base64 MIME envuelto en el conocido marco begin-base64, y su hermano uudecode lo lee de vuelta:

busybox uuencode -m photo.jpg < photo.jpg > photo.uu

Las APIs y las subidas usan la misma idea con ropa JSON: el binario se convierte en una cadena Base64 dentro de un campo JSON, y curl lo lleva. Construir el cuerpo en una variable de la shell mantiene las comillas honestas:

body="{\"file\":\"$(base64 -w 0 upload.bin)\"}"
curl -fsS -X POST https://httpbin.org/post -H "Content-Type: application/json" -d "$body"

Aquí viven dos trampas de interoperabilidad. Primera, comprueba qué alfabeto quiere la API: algunas esperan Base64 estándar, otras esperan el dialecto seguro para URL, y una cadena con caracteres + enviada a un extremo seguro para URL (o al revés) fallará la validación o, peor, se decodificará a los bytes equivocados. Segunda, cuidado con la doble codificación, el bug clásico donde un script codifica un valor que el servidor codifica otra vez, y el viaje de ida y vuelta necesita dos decodificaciones para desenredarse.

Cuando el payload se pone grande

El codificador, como el decodificador, es una máquina de streaming: lee en trozos y escribe en trozos, así que un tarball de 10 GB no necesita 13 GB de RAM, y el comando corre encantado durante minutos con entradas grandes y un uso de memoria plano. La matemática del tamaño es la única herramienta de planificación que necesitas: la salida es cuatro caracteres por cada tres bytes de entrada, más un byte por cada línea envuelta, así que un archivo de 300 MB se convierte en unos 400 MB de texto. Para una comprobación de realidad rápida de cualquier archivo:

base64 -w 0 big.bin | wc -c

Cuando el texto mismo debe moverse por un canal con límite de tamaño (un tope de adjuntos de correo, un sistema de tickets, un mensaje de mensajería), divide la forma codificada, nunca el binario crudo, para que cada trozo siga siendo texto ordinario que puedes pegar, comprimir o reenviar:

base64 -w 0 big.bin | split -b 4000 - part_

Eso produce una racha de partes de 4000 caracteres; el receptor las vuelca juntas en orden con cat y decodifica una sola vez. Y cuando el payload es comprimible, comprime antes de codificar, porque Base64 añade redundancia encima de lo que los datos ya contienen: un tarball de un directorio de proyecto normalmente se reduce varias veces con gzip antes de que se aplique el recargo Base64 del 33 por ciento:

tar czf - project/ | base64 -w 0 > project.b64

La velocidad no será tu limitante. Estos codificadores empujan gigabytes en mucho menos de un segundo en una máquina moderna; un archivo de 200 MB tarda aproximadamente una décima de segundo con las implementaciones de coreutils y OpenSSL, e incluso BusyBox, el más lento de los comunes, termina en una fracción de segundo (medido en aproximadamente una cuarta parte de segundo para 200 MB en una máquina moderna, varias veces más lento que coreutils pero ni de lejos un cuello de botella). El cuello de botella en las tuberías reales es casi siempre la red, no la codificación.

Los pequeños caracteres que muerden

Las trampas del lado de la codificación son más pequeñas que las del lado de la decodificación, y es justo:

Hábitos que te mantienen a salvo

• Nombra el recuento de bytes. printf '%s' para el texto, el argumento FILE para los archivos, y una comprobación de wc -c antes de enviar cualquier cosa donde el tamaño importe.
• Fija el envolvimiento explícitamente. -w 0 para URLs y JSON, -w 76 para MIME, -w 64 para PEM. Nunca dejes el ancho al predeterminado de la herramienta.
• Elige el alfabeto para el destino. Estándar para el correo y los archivos, seguro para URL para los tokens y las URLs, y comprueba la documentación del consumidor antes de codificar.
• Comprime antes de codificar. Para cualquier payload comprimible, gzip o tar czf primero; el recargo del 33 por ciento se aplica a lo que le entregues al codificador.
• Divide el texto, no el binario. Cuando un límite de tamaño se meta en el medio, split la forma codificada para que cada trozo siga siendo seguro para pegar, y reensambla en orden antes de la decodificación única.
• Guarda los tres trabajos del JWT separados. Alfabeto, criptografía, formato: codifica los segmentos, firma el texto ASCII de los segmentos unidos, y luego emite. Reordénalos y el token se rompe.
• No dejes nunca que Base64 haga de cifrado. Si el valor es secreto, cifralo y luego codifica el texto cifrado. Si no es secreto, dilo y deja de preocuparte.

Una breve historia de la codificación en la shell

• 1980, Berkeley. Mary Ann Horton escribe uuencode y uudecode en la Universidad de California, Berkeley, para llevar archivos binarios por el correo entre sistemas Unix. El nombre, "codificación de Unix a Unix", es el certificado de nacimiento del formato, y durante la década siguiente más o menos, esto es con lo que los usuarios de shell codifican.
• La era del módem. uuencode en UNIX y BinHex en el TRS-80 y el Apple II, con el Macintosh un paso atrás, resuelven el mismo problema con alfabetos distintos, cada uno confiando solo en los caracteres que su propio terminal puede imprimir.
• 1993. MIME estandariza Base64 para el correo en el RFC 1521, más tarde RFC 2045, con el envolvimiento de líneas cada 76 caracteres que el predeterminado de coreutils todavía lleva hoy.
• Antes de 2006 en Linux. No existe el comando base64. Los scripts de la shell recurren a openssl base64, uuencode -m, Perl o Python, y el hábito de OpenSSL es tan profundo que la mitad de los viejos one-liners que hay por el mundo todavía empiezan con él.
• 15 de agosto de 2006. coreutils 6.0 empaqueta el comando base64, y su archivo NEWS lo acredita como "funcionalidad de codificación y decodificación base64 (RFC 3548)", y empieza la era de un solo comando. Un par de meses después, en octubre de 2006, el RFC 4648 formaliza la familia de alfabetos, incluido el dialecto seguro para URL al que este artículo vuelve una y otra vez.
• OS X 10.7. macOS empaqueta su propio base64, el sabor BSD sin envolvimiento por defecto, y por eso "solo ejecutar base64" necesita una comprobación de plataforma en los scripts portables.
• 2024. coreutils 9.5 cambia cómo los decodificadores tratan la entrada sin relleno y no canónica, lo que en la práctica significa que los codificadores tienen un pase gratis: la salida que las versiones viejas de GNU habrían rechazado ahora se decodifica de forma limpia. El lado codificador del formato es el estable; los decodificadores son los que se movieron.
• 2025. La reescritura en Rust de coreutils (uutils) se vuelve el predeterminado de las versiones actuales de Ubuntu. Mismo comando, mismos flags, un motor nuevo, y el mismo predeterminado de 76 caracteres que heredó de la versión en C.

Pequeñas maravillas

• El nombre del formato es verdad en todas las máquinas. printf 'base64' | base64 da YmFzZTY0 en GNU, uutils, BusyBox, OpenSSL y macOS por igual. Ha sido verdad desde 2006 y siempre lo será.
• Un archivo de nada se codifica como una pared de A. Dale tres bytes NUL y la salida es AAAA, porque tres bytes de valor cero se mapean a cuatro índices cero del alfabeto, cada uno representado por la A. Un archivo .b64 que empieza con una larga racha de A suele ser relleno de ceros en el archivo original (bytes NUL), no un misterio.
• El impuesto del 33 por ciento no tiene descuentos. Cuatro caracteres por cada tres bytes, sin compresión, sin segunda oportunidad. La única salida es comprimir los datos primero, que es por qué tar czf es el héroe de verdad de las tuberías de payloads grandes.
• Dos caracteres causaron todo el lío de las URLs. + y / son los únicos miembros del alfabeto que alguna vez necesitaron un sustituto, y un dialecto entero del formato existe para jubilarlos. El sesenta y dos y el sesenta y tres, las dos últimas casillas del alfabeto.
• Once caracteres, sesenta y cuatro bits. Un ID de vídeo de YouTube es una cadena base64url de 11 caracteres, un número de 64 bits con ropa de URL, y por eso viaja por las URLs sin un solo signo de porcentaje.
• El impostor más famoso de Git. Los bloques binarios de git diff --binary parecen Base64, pero las líneas prefijadas por z son un dialecto de estilo base85 de su propio cuño. Una mirada y sabes que no es tu alfabeto; un desvío de grep-y-decodificar y pierdes veinte minutos.
• Cada herramienta envuelve distinto, a propósito. 76 para MIME, 64 para PEM, cero en la herramienta BSD: tres predeterminados, tres convenciones heredadas, un formato. El ancho siempre fue tuyo de elegir; las herramientas solo recuerdan predeterminados distintos.
• El codificador nunca falla con tus datos. A diferencia de su primo decodificador, el codificador no tiene entrada inválida, no tiene corrupción, no tiene modo estricto. Toma bytes y da letras, cada vez. Los bugs de este artículo están todos en los bytes que le entregas y en el destino al que los mandas.

Y cuando el viaje apunta al otro lado, cuando una cadena larga de letras, dígitos y algún guion o guion bajo de vez en cuando aterriza en tu terminal y necesitas los bytes de vuelta, el artículo relacionado de decodificación Base64 enlazado abajo cubre ese ritual con la misma profundidad, desde los segmentos de JWT sin relleno hasta cada trampa de saltos de línea que los decodificadores esconden.

Última actualización: 2026-09-08

Artículo relacionado: Decodificación Base64 en Bash: una guía completa