Codifica Base64 in Bash: una guida completa

Hai dei byte e ti serve una stringa. Un file di testo che deve vivere dentro un corpo JSON. Un'immagine che deve stare in una riga di configurazione. Un token che attraverserà un URL, una variabile d'ambiente o un'intestazione HTTP. Una chiave privata che appartiene a un archivio di certificati. Questo è il lavoro quotidiano della codifica Base64 nella shell, e la risposta della shell è un comando singolo, piccolo, sorprendentemente portatile.

Lo scambio in un fiato: il Base64 riscrive ogni tre byte di dati grezzi in quattro caratteri da un alfabeto di 64 lettere (A-Z, a-z, 0-9, più + e /), riempiendo la coda con uno o due segni = quando il numero di byte non è un multiplo di tre. La home page di questo sito spiega il formato per intero; qui spendiamo il nostro tempo a produrre il testo, a scegliere il dialetto giusto per la destinazione e a pagare il conto delle dimensioni con gli occhi aperti. Un numero da tenere in tasca: la forma codificata è normalmente circa un terzo più grande dell'originale, quattro caratteri per tre byte, e torna sempre a presentarsi.

Il cast è piccolo. Il comando base64 dei coreutils (GNU o la famiglia più recente uutils in Rust), basenc della stessa famiglia per il dialetto sicuro per URL, openssl base64 per le macchine senza coreutils, l'applet BusyBox per i sistemi embedded e il sapore BSD su macOS. Cinque strumenti, un lavoro, un paio di flag che vale la pena conoscere.

Scegli il tuo codificatore

Ognuno di questi legge byte dallo standard input o da un file e scrive testo sullo standard output, quindi tutti si inseriscono nelle stesse pipeline. Le differenze sono l'avvolgimento di riga predefinito e i dialetti disponibili:

Leggi due volte quella colonna dell'avvolgimento, perché è la differenza silenziosa tra le famiglie. Coreutils e BusyBox avvolgono a 76 di default, OpenSSL avvolge a 64, e lo strumento BSD non avvolge affatto. Nessuna di queste ha torto; hanno semplicemente ereditato convenzioni diverse (MIME dice 76, PEM dice 64, e lo strumento BSD è semplicemente più vecchio dell'abitudine dell'avvolgimento). Quando è importante per il tuo consumatore, imposta la larghezza esplicitamente e non fare mai affidamento sul predefinito.

Prima il testo: il cambio di riga invisibile

Codificare testo in una shell parte con una trappola: echo aggiunge un cambio di riga. Quelle cinque lettere "hello" diventano sei byte nel momento in cui passano attraverso echo, e il sesto byte viaggia nell'output, invisibile e permanente:

echo "hello" | base64

Quello stampa aGVsbG8K, e l'ultimo carattere codifica l'a capo. La correzione è quella che dovresti usare per il testo dove il numero di byte conta: printf con un formato, nessuna decorazione:

printf '%s' "hello" | base64

Ora l'output è aGVsbG8=, esattamente il valore di cinque byte, e l'ultimo carattere è un segno di riempimento invece di un byte vivo. La stessa regola vale per le here-string, che aggiungono un cambio di riga finale proprio come echo: base64 <<< "hello" ti dà di nuovo la versione aGVsbG8K. Quando hai dubbi, chiediti cos'è l'ultimo byte prima di codificarlo.

Per qualsiasi cosa che vuoi su una riga sola, aggiungi -w 0 (o i cugini di -w 0 qui sotto), che rimuove anche l'ultimo cambio di riga che altrimenti il comando emetterebbe:

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

Quella è una riga pulita e ininterrotta, senza cambio di riga finale, pronta per essere inserita in un URL, in un valore JSON o in un file di configurazione senza alcuna cerimonia ulteriore.

File e la larghezza di avvolgimento

I file sono il caso comune, e ogni implementazione accetta un argomento FILE, che tiene i byte completamente alla larga dal meccanismo di virgolettatura della shell:

base64 -w 0 report.pdf > report.b64

Senza -w 0, l'output arriva avvolto a 76 caratteri, che è esattamente ciò che un consumatore MIME vuole:

base64 report.pdf > report.mime.b64

La larghezza è una manopola che controlli per ciascun consumatore. Settanta e sei è la convenzione MIME di RFC 2045, sessantaquattro è la convenzione PEM usata da certificati e chiavi, e zero significa una riga ininterrotta per URL e API:

base64 -w 64 key.bin | head -2

Se il consumatore vive su Windows e si aspetta terminazioni di riga CRLF, converti dopo l'avvolgimento, non prima:

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

Per il percorso OpenSSL, l'equivalente della modalità a riga singola è il flag -A, che sopprime anche l'a capo finale:

openssl base64 -A < report.pdf

Prima di spedire un file avvolto, un controllo di sanità sulle dimensioni non costa nulla e cattura un numero sorprendente di errori (un file codificato due volte, un file codificato con l'input sbagliato):

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

Il secondo numero dovrebbe essere circa quattro terzi del primo, più un byte per riga avvolta per gli a capo. Se è molto diverso, fermati e guarda cosa hai effettivamente dato in pasto al codificatore.

Base64 sicuro per URL: scambiare i due caratteri antipatici

Due caratteri nell'alfabeto standard, + e /, sono i bambini problematici: un + in una query string di un URL significa uno spazio, un / può sembrare un separatore di percorso, e entrambi impongono la codifica in percento nel momento in cui la stringa entra in un URL, in un cookie o in un nome di file. La sezione 5 di RFC 4648 risolve la cosa con un dialetto che sostituisce esattamente quei due caratteri con - e _, e toglie il riempimento, dato che un URL raramente ha bisogno di dichiarare la lunghezza esatta in byte.

La ricetta della shell è uno scambio più un taglio: una passata con tr per l'alfabeto e una per rimuovere il riempimento:

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

Quei tre byte si codificano normalmente in /k+C, che sarebbe brutto in un URL; la pipeline lo trasforma in _k-C, quattro caratteri che possono viaggiare dappertutto. Lo scambio è posizionale, quindi la direzione è facile da confondere: la codifica va tr '+/' '-_' (il più diventa trattino, lo slash diventa underscore), e quella inversa, che spetta alla decodifica, va tr '_-' '/+'. Una direzione confusa non dà errore, produce solo byte diversi, che è il peggior genere di bug da far partire.

Il dialetto conta ogni volta che la stringa lascia il controllo della shell: segmenti JWT, token in query string, valori in cookie o nomi di file, e qualsiasi identificatore che un altro sistema leggerà come parte di un URL. Il basenc di GNU produce il dialetto nativamente, con il riempimento ancora al suo posto:

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

Togli il riempimento con tr -d '=' se il consumatore vuole la forma senza riempimento, come la maggior parte fa.

Coniare un JWT nella shell

I JSON Web Token sono il consumatore più visibile del Base64 sicuro per URL nel mondo delle API. Un JWT compatto è composto da tre segmenti base64url uniti da punti: l'intestazione, il carico utile e la firma, secondo RFC 7515. I primi due sono JSON semplice; la firma è un digest binario dei primi due segmenti uniti da un punto, ed è esattamente il genere di cosa in cui openssl è bravo.

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"

Quello stampa un JWT HS256 compatto che qualsiasi libreria standard su qualsiasi piattaforma accetterà. Noterai la divisione del lavoro: la parte Base64 è l'alfabeto, la parte openssl dgst -sha256 -hmac è la crittografia, e l'unione con i punti è il formato. Tieni i tre lavori separati nella tua testa e la pipeline resta ovvia.

Tre avvertenze dal campo. Primo, il MAC è calcolato sul testo ASCII dei primi due segmenti più il punto, quindi i segmenti devono già essere nella loro forma base64url finale quando li firmi; riavvolgere o riapplicare il riempimento dopo la firma rompe il token. Secondo, la chiave resta fuori dal token: la firma dimostra chi ha firmato, la chiave tiene il segreto segreto. Terzo, coniare in uno script di shell è uno strumento di test e automazione, non un sostituto del server che emetterà e verificherà davvero questi token, e un token coniato con alg: none non dimostra nulla.

Data URI: file che viaggiano dentro le stringhe

RFC 2397 definisce lo schema URL data:, e la sua forma Base64 permette a un file di vivere dentro un URL: data:, poi un tipo media facoltativo, poi ;base64 quando il carico utile è codificato in Base64, poi una virgola, poi i dati. Ometti il tipo media e il predefinito è text/plain;charset=US-ASCII, che è un'insidia di cui vale la pena sapere qualcosa, perché la maggior parte delle volte si intende un'immagine o un documento JSON, non testo ASCII.

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

Quello stampa data:text/plain;base64,aGkgdGhlcmU=, un URL completa e autocontenuta che un browser mostrerà volentieri. Per un'immagine, la stessa forma con un tipo media vero:

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

Incolla il risultato in un tag HTML img, nella sua src, o in un background CSS e l'immagine viaggia con il documento, senza una seconda richiesta HTTP. Le insidie sono tutte sulla dimensione: l'RFC stesso dice che lo schema è utile solo per valori corti, i browser impongono i loro limiti di lunghezza delle URL, ogni byte incorporato costa il sovraccarico del 33 percento oltre la dimensione propria dell'immagine, e una pagina piena di data URI è una pagina senza una storia di cache per quelle immagini. Per icone piccole e grafiche incorporate una tantum è una gioia; per una libreria fotografica è una tassa.

Segreti, configurazione e variabili d'ambiente

Il Base64 appare nel lavoro di configurazione e segreti per un motivo specifico: trasforma byte arbitrari, inclusi spazi, virgolette e a capo, in una stringa che sopravvive a un export, a una riga di configurazione o a un campo JSON senza acrobazie di virgolettatura. Kubernetes è l'esempio più visibile: ogni campo sotto il .data di un segreto è Base64, quindi creare un segreto nella shell è solo codifica:

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

L'API server memorizza la password come czNjcmV0 sotto .data, e qualsiasi nodo con accesso al segreto può rileggerla con una sola decodifica. La stessa mossa funziona per i tuoi file di configurazione:

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

O, per un file che l'applicazione legge all'avvio:

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

Arriva qui l'avvertenza da appendere al muro: il Base64 è codifica, non cifratura. La sezione sulla sicurezza di RFC 4648 è diretta al riguardo, notando che la codifica "nasconde visivamente informazioni altrimenti facilmente riconoscibili, come le password, ma non fornisce alcuna riservatezza computazionale", e che proprio questo malinteso ha causato incidenti di sicurezza reali quando qualcuno ha incollato uno scambio di protocollo "protetto" in un rapporto di bug e ha rivelato per sbaglio le credenziali. Se il valore deve essere segreto, cifralo (e poi metti in Base64 il testo cifrato per la memorizzazione); se il Base64 è tutto quello che hai, tratta il valore codificato come testo semplice nel momento in cui lascia lo schermo.

Unicode, codifiche dei caratteri e i byte sotto

Il codificatore legge byte, non caratteri, e la shell gli consegna i byte che l'impostazione locale e il comando hanno prodotto. Per il testo UTF-8 è di solito esattamente quello che vuoi: la é in héllo è già formata da due byte, c3 a9, e la codifica se li porta dietro:

printf 'h\xc3\xa9llo' | base64

Quello stampa aMOpbGxv, e un consumatore UTF-8 dall'altra parte si ritrova héllo, byte per byte. I guai cominciano quando la fonte non è UTF-8. Un file Latin-1 con la stessa parola contiene un singolo byte e9 per la é, e codificare quei byte in diretta produce testo che solo un consumatore Latin-1 può rileggere. Prima converti, poi codifichi:

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

Due altri fatti a livello di byte. Un BOM UTF-8, tre byte all'inizio di un file, si codifica in 77u/ e resterà per sempre all'inizio del tuo output decodificato a meno che non lo togli prima:

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

E l'impostazione locale non cambia mai la codifica in sé, perché il codificatore è una macchina a byte; cambia solo quello che hai digitato. Quando l'output sembra sbagliato, controlla i byte che hai dato, non la codifica che hai eseguito.

Email, API e upload

L'email è il posto dove il Base64 ha imparato le maniere, e le maniere sono ancora la convenzione. Lo SMTP storicamente portava solo ASCII a 7 bit, quindi gli allegati viaggiano come Base64 avvolto a 76 caratteri con terminazioni di riga CRLF, secondo RFC 2045. Produrre quella forma esatta per una parte MIME è l'avvolgimento più la conversione delle terminazioni di riga:

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

La vecchia guardia è ancora in servizio nei sistemi embedded: il uuencode di BusyBox con il flag -m produce Base64 MIME avvolto nelle consuete righe di delimitazione begin-base64, e il suo fratello uudecode lo rilegge:

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

Le API e gli upload usano la stessa idea in abiti JSON: il binario diventa una stringa Base64 dentro un campo JSON, e curl lo trasporta. Costruire il corpo in una variabile di shell tiene la virgolettatura onesta:

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

Due trappole di interoperabilità vivono qui. Primo, controlla quale alfabeto vuole l'API: alcune si aspettano Base64 standard, altre il dialetto sicuro per URL, e una stringa con caratteri + mandata a un endpoint sicuro per URL (o vice versa) fallirà la validazione o, peggio, si decodificherà nei byte sbagliati. Secondo, stai attento alla doppia codifica, il bug classico in cui uno script codifica un valore che il server codifica di nuovo, e l'andata e il ritorno richiedono due decodifiche per srotolarsi.

Quando il carico utile diventa grosso

Il codificatore, come il decodificatore, è una macchina in streaming: legge a frammenti e scrive a frammenti, quindi un tarball da 10 GB non ha bisogno di 13 GB di RAM, e il comando funziona volentieri per minuti su input grossi con un uso della memoria piatto. Il calcolo delle dimensioni è l'unico strumento di pianificazione che ti serve: l'output è quattro caratteri per tre byte in ingresso, più un byte per riga avvolta, quindi un file da 300 MB diventa circa 400 MB di testo. Per un rapido controllo di realtà su qualsiasi file:

base64 -w 0 big.bin | wc -c

Quando il testo stesso deve attraversare un canale con un limite di dimensione (un limite di allegato per la email, un sistema di ticket, un messaggio IM), dividi la forma codificata, mai il binario grezzo, così ogni frammento resta testo ordinario che puoi incollare, comprimere o inoltrare:

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

Quello produce una serie di parti da 4000 caratteri; il ricevente le ricompone con cat nell'ordine e decodifica una volta sola. E quando il carico utile è comprimibile, comprimi prima di codificare, perché il Base64 aggiunge ridondanza sopra quello che i dati contengono già: il tarball di una directory di progetto si riduce tipicamente diverse volte con gzip prima che si applichi il sovrapprezzo del 33 percento del Base64:

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

La velocità non sarà il tuo vincolo. Questi codificatori spingono attraverso i gigabyte in meno di un secondo su una macchina moderna; un file da 200 MB richiede circa un decimo di secondo con le implementazioni coreutils e OpenSSL, e persino BusyBox, il più lento dei comuni, finisce ancora in una frazione di secondo (misurato a circa un quarto di secondo per 200 MB su una macchina moderna, più lento di qualche volta rispetto a coreutils ma nemmeno lontanamente un collo di bottiglia). Il collo di bottiglia nelle pipeline reali è quasi sempre la rete, non la codifica.

I piccoli caratteri che mordono

Le insidie del lato codifica sono più piccole di quelle del lato decodifica, ed è solo giusto che sia così:

Abitudini che ti tengono al sicuro

• Dai un nome al numero di byte. printf '%s' per il testo, l'argomento FILE per i file, e un controllo di sanità con wc -c prima di spedire qualsiasi cosa dove la dimensione conta.
• Imposta l'avvolgimento esplicitamente. -w 0 per URL e JSON, -w 76 per MIME, -w 64 per PEM. Non lasciare mai la larghezza al predefinito dello strumento.
• Scegli l'alfabeto per la destinazione. Standard per email e file, sicuro per URL per token e URL, e controlla la documentazione del consumatore prima di codificare.
• Comprimi prima di codificare. Per qualsiasi carico utile comprimibile, prima gzip o tar czf; il sovrapprezzo del 33 percento si applica a quello che dai al codificatore.
• Dividi il testo, non il binario. Quando un limite di dimensione sta di traverso, usa split sulla forma codificata così ogni frammento resta sicuro da incollare, e ricomponi nell'ordine prima della decodifica unica.
• Tieni separate le tre mansioni del JWT. Alfabeto, crittografia, formato: codifica i segmenti, firma il testo ASCII dei segmenti uniti, poi emetti. Scambia l'ordine e il token si rompe.
• Non lasciare mai che il Base64 stia al posto della cifratura. Se il valore è segreto, cifralo e poi codifica il testo cifrato. Se non è segreto, dillo e smetti di preoccuparti.

Una breve storia della codifica nella shell

• 1980, Berkeley. Mary Ann Horton scrive uuencode e uudecode all'Università della California, Berkeley, per far passare file binari attraverso la email tra sistemi Unix. Il nome, "codifica Unix-to-Unix", è l'atto di nascita del formato, e per il decennio successivo circa è questo lo strumento con cui gli utenti della shell codificano.
• L'era del modem. uuencode su UNIX e BinHex sul TRS-80 e sull'Apple II con il Macintosh un passo indietro risolvono lo stesso problema con alfabeti diversi, ognuno che si fida solo dei caratteri che il proprio terminale può stampare.
• 1993. MIME standardizza il Base64 per la email in RFC 1521, poi RFC 2045, con l'avvolgimento di riga a 76 caratteri che il predefinito dei coreutils porta ancora oggi.
• Prima del 2006 su Linux. Non c'è un comando base64. Gli script di shell ricorrono a openssl base64, uuencode -m, Perl o Python, e l'abitudine OpenSSL è così radicata che metà dei vecchi comandi in riga singola in circolazione iniziano ancora con quello.
• 15 agosto 2006. coreutils 6.0 distribuisce il comando base64, il suo file NEWS lo accredita come "funzionalità di codifica e decodifica Base64 (RFC 3548)", e l'era del comando unico ha inizio. Un paio di mesi dopo, nell'ottobre 2006, RFC 4648 formalizza la famiglia di alfabeti, incluso il dialetto sicuro per URL a cui questo articolo continua a ricorrere.
• OS X 10.7. macOS distribuisce il suo base64, il sapore BSD senza avvolgimento predefinito, ed è per questo che "lancia base64 e basta" ha bisogno di un controllo della piattaforma negli script portatili.
• 2024. coreutils 9.5 cambia come i decodificatori trattano l'input senza riempimento e non canonico, il che in pratica significa che i codificatori hanno un passaggio libero: l'output che le versioni GNU più vecchie avrebbero rifiutato ora si decodifica senza problemi. Il lato codificatore del formato è quello stabile; a muoversi sono stati i decodificatori.
• 2025. La riscrittura in Rust dei coreutils (uutils) diventa il predefinito nelle release correnti di Ubuntu. Stesso comando, stessi flag, un nuovo motore e lo stesso predefinito a 76 caratteri ereditato dalla versione C.

Piccoli miracoli

• Il nome del formato è vero su ogni macchina. printf 'base64' | base64 dà YmFzZTY0 su GNU, uutils, BusyBox, OpenSSL e macOS allo stesso modo. È vero dal 2006 e lo sarà sempre.
• Un file di niente si codifica in un muro di A. Daggi in pasto tre byte NUL e l'output è AAAA, perché tre byte di valore zero mappano su quattro indici zero nell'alfabeto, ciascuno rappresentato da A. Un file .b64 che inizia con una lunga fila di A è di solito riempimento di zeri nel file originale (byte NUL), non un mistero.
• La tassa del 33 percento non conosce sconti. Quattro caratteri per tre byte, nessuna compressione, nessuna seconda possibilità. L'unica via di fuga è comprimere i dati prima, ed è per questo che tar czf è l'eroe vero delle pipeline a carico utile grosso.
• Due caratteri hanno causato tutti i guai delle URL. + e / sono gli unici membri dell'alfabeto che abbiano mai avuto bisogno di un sostituto, e un dialetto intero del formato esiste per mandarli in pensione. Sessantadue e sessantatré, le ultime due caselle dell'alfabeto.
• Undici caratteri, sessantaquattro bit. L'ID di un video YouTube è una stringa base64url di 11 caratteri, un numero da 64 bit in abiti da URL, ed è per questo che viaggia attraverso le URL senza un solo segno di percentuale.
• L'impostore più famoso di Git. I blocchi binari in git diff --binary assomigliano al Base64, ma le righe con prefisso z sono un dialetto in stile base85 a sé. Uno sguardo e sai che non è il tuo alfabeto; una deviazione di grep-e-decodifica e perdi venti minuti.
• Ogni strumento avvolge in modo diverso, apposta. 76 per MIME, 64 per PEM, zero sullo strumento BSD: tre predefiniti, tre convenzioni ereditate, un formato. La larghezza è sempre stata tua da scegliere; gli strumenti si sono solo ricordati predefiniti diversi.
• Il codificatore non fallisce mai sui tuoi dati. A differenza del suo cugino della decodifica, il codificatore non ha input non validi, non ha corruzione, non ha modalità rigorosa. Prende byte e dà lettere, ogni volta. I bug di questo articolo sono tutti nei byte che gli dai e nella destinazione a cui li mandi.

E quando il viaggio punta dall'altra parte, quando una lunga stringa di lettere, cifre e, di tanto in tanto, un trattino o un underscore atterra nel tuo terminale e ti servono di nuovo i byte, l'articolo correlato sulla decodifica Base64 collegato qui sotto copre quel rituale nella stessa profondità, dai segmenti JWT senza riempimento a ogni trappola di cambio di riga che i decodificatori nascondono.

Ultimo aggiornamento: 2026-09-08

Articolo correlato: Decodifica Base64 in Bash: una guida completa