Base64-codering in Bash: een complete gids

Je hebt bytes en je hebt een tekenreeks nodig. Een tekstbestand dat in een JSON-lichaam moet leven. Een beeld dat in een config-regel moet zitten. Een token dat door een URL, een omgevingsvariabele of een HTTP-header zal reizen. Een privésleutel die in een certificaatopslag thuishoort. Dit is het dagelijks werk van Base64-coderen in de shell, en het antwoord van de shell is één klein, verassend draagbaar commando.

De ruil in één adem: Base64 schrijft elke drie bytes ruwe data om naar vier tekens uit een alfabet van 64 letters (A-Z, a-z, 0-9, plus + en /) en vult de staart op met één of twee =-tekens als het aantal bytes geen veelvoud van drie is. De startpagina van deze site legt het formaat volledig uit; hier besteden we onze tijd aan het produceren van de tekst, het kiezen van het juiste dialect voor de bestemming, en de groottefactuur betalen met open ogen. Eén getal om in je zak te stoppen: de gecodeerde vorm is normaal gesproken zo'n derde groter dan het origineel, vier tekens per drie bytes, en het komt steeds terug.

De cast is klein. Het base64-commando uit coreutils (GNU of de nieuwere uutils-familie in Rust), basenc uit dezelfde familie voor het URL-veilige dialect, openssl base64 voor machines zonder coreutils, het BusyBox-applet voor ingebouwde systemen, en de BSD-variant op macOS. Vijf tools, één klus, een paar flags die je kennen moet.

Kies je encoder

Ze lezen allemaal bytes uit de standaardinvoer of een bestand en schrijven tekst naar de standaarduitvoer, dus ze passen allemaal in dezelfde pipelines. De verschillen zijn de standaardregelomwikkeling en de beschikbare dialecten:

Lees die omwikkelkolom nog een keer, want dat is het stille verschil tussen de families. Coreutils en BusyBox wikkelen standaard op 76 om, OpenSSL op 64, en het BSD-gereedschap wikkelt helemaal niet om. Geen van hen is fout; ze hebben gewoon verschillende conventies geërfd (MIME zegt 76, PEM zegt 64, en het BSD-gereedschap is simpelweg ouder dan de omwikkelgewoonte). Als je afnemer er om geeft, stel dan de breedte expliciet in en vertrouw nooit op de standaard.

Eerst de tekst: het onzichtbare regeleinde

Coderen van tekst in een shell begint met één val: echo voegt een nieuwe regel toe. Die vijf letters "hello" worden zes bytes op het moment dat ze door echo gaan, en de zesde byte reist mee naar de uitvoer, onzichtbaar en blijvend:

echo "hello" | base64

Die print aGVsbG8K, en het laatste teken codeert de nieuwe regel. De oplossing is de die je moet gebruiken voor tekst waar het aantal bytes toe doet: printf met een formaat, zonder versiering:

printf '%s' "hello" | base64

De uitvoer is nu aGVsbG8=, precies vijf bytes waard, en het laatste teken is een paddingteken in plaats van een echte byte. Dezelfde regel geldt voor here-strings, die net als echo een afsluitende nieuwe regel toevoegen: base64 <<< "hello" geeft je weer de aGVsbG8K-versie. Twijfel je, vraag jezelf dan af wat de laatste byte is vóór je hem codeert.

Als je iets op één regel wilt, voeg dan -w 0 toe (of de neefjes van -w 0 hieronder); die verwijderen ook de afsluitende nieuwe regel die het commando anders zou printen:

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

Die is één nette, onafgebroken regel zonder afsluitende nieuwe regel, klaar om in een URL, een JSON-waarde of een config-bestand te gooien zonder verdere poespas.

Bestanden en de omwikkelbreedte

Bestanden zijn het gangbare geval, en elke implementatie neemt een FILE-argument, wat de bytes helemaal ver weg houdt van het quote-apparaat van de shell:

base64 -w 0 report.pdf > report.b64

Zonder -w 0 komt de uitvoer omgebroken op 76 tekens, en dat is precies wat een MIME-afnemer wil:

base64 report.pdf > report.mime.b64

De breedte is een knop die je per afnemer bedient. Zes-en-zeventig is de MIME-conventie uit RFC 2045, vier-en-zestig is de PEM-conventie die certificaten en sleutels gebruiken, en nul betekent één onafgebroken regel voor URLs en APIs:

base64 -w 64 key.bin | head -2

Als de afnemer op Windows zit en CRLF-regelafsluitingen verwacht, converteer dan na het omwikken, niet ervoor:

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

Voor de OpenSSL-route is het equivalent van de één-regel-modus de -A-flag, die ook de afsluitende nieuwe regel onderdrukt:

openssl base64 -A < report.pdf

Vóór je een omwikkeld bestand verzendt, kost een controle op plausibiliteit van de grootte niets en vangt een verrassend aantal fouten (een bestand dat twee keer gecodeerd is, een bestand dat met de verkeerde invoer is gecodeerd):

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

Het tweede getal zou ongeveer vier derde van het eerste moeten zijn, plus één byte per omgebroken regel voor de nieuwe regels. Is het ver uit de boeg, stop dan en kijk wat je de encoder eigenlijk hebt gevoerd.

URL-veilige Base64: de twee onhandige tekens verwisselen

Twee tekens in het standaardalfabet, + en /, zijn de problemkinderen: een + in een URL-querystring betekent een spatie, een / kan eruitzien als een padseparator, en beide dwingen percent-codering op het moment dat de tekenreeks een URL, cookie of bestandsnaam binnenkomt. Sectie 5 van RFC 4648 lost dit op met een dialect dat precies die twee tekens vervangt door - en _, en het padding laat vallen, omdat een URL zelden de exacte bytelengte hoeft te adverteren.

Het shell-recept is een ruil plus een knipbeurt, één ritje door tr voor het alfabet en één voor het verwijderen van het padding:

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

Die drie bytes coderen normaal naar /k+C, en dat zou lelijk zijn in een URL; de pipeline maakt er _k-C van, vier tekens die overal heen kunnen. De ruil is positiegebonden, dus de richting is makkelijk te verwisselen: coderen gaat tr '+/' '-_' (plus wordt streepje, slash wordt onderteken), en de omgekeerde, die bij decoderen hoort, gaat tr '_-' '/+'. Een verwisselde richting geeft geen fout, hij produceert alleen andere bytes, en dat is het ergste soort bug om te verspreiden.

Het dialect doet er toe telkens wanneer de tekenreeks de controle van de shell verlaat: JWT-segmenten, tokens in querystrings, waarden in cookies of bestandsnamen, en elke identifier die een ander systeem als onderdeel van een URL leest. De basenc van GNU produceert het dialect native, met het padding nog op zijn plek:

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

Haal het padding weg met tr -d '=' als de afnemer de versie zonder padding wil, zoals de meeste dat doen.

Een JWT munten in de shell

JSON Web Tokens zijn de meest zichtbare afnemer van URL-veilige Base64 in de API-wereld. Een compact JWT is drie base64url-segmenten die met stippen aan elkaar worden gezet: de header, de payload en de handtekening, conform RFC 7515. De eerste twee zijn gewoon JSON; de handtekening is een binair digest van de eerste twee segmenten die met een stip zijn samengevoegd, en dat is precies het soort ding waar openssl goed in is.

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"

Die print een compact HS256-JWT dat elke standaardbibliotheek op elk platform accepteert. Kijk naar de taakverdeling: het Base64-gedeelte is het alfabet, het openssl dgst -sha256 -hmac-gedeelte is de cryptografie, en het samenvoegen met stippen is het formaat. Houd de drie taken apart in je hoofd en de pipeline blijft overduidelijk.

Drie waarschuwingen voor het veld. Eerst: de MAC wordt berekend over de ASCII-tekst van de eerste twee segmenten plus het stippertje, dus de segmenten moeten al in hun definitieve base64url-vorm zitten op het moment dat je ze ondertekent; opnieuw omwikken of opnieuw padding geven na het tekenen breekt het token. Ten tweede: de sleutel blijft buiten het token: de handtekening bewijst wie heeft getekend, de sleutel houdt het geheim geheim. Ten derde: munten in een shellscript is een test- en automatiseringsmiddel, geen vervanging voor de server die deze tokens daadwerkelijk zal uitgeven en verifiëren, en een token dat met alg: none is gemunt bewijst helemaal niets.

Data-URIs: bestanden die meereizen in tekenreeksen

RFC 2397 definieert het data:-URL-schema, en zijn Base64-vorm laat een bestand leven in een URL: data:, dan een optionele mediatype, dan ;base64 als de payload Base64-gecodeerd is, dan een komma, dan de data. Laat de mediatype weg en de standaard is text/plain;charset=US-ASCII, en dat is een voetkanon dat je moet kennen, omdat de meeste mensen een beeld of een JSON-document bedoelen, geen ASCII-tekst.

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

Die print data:text/plain;base64,aGkgdGhlcmU=, een complete, zelfstandige URL die een browser met plezier toont. Voor een beeld, dezelfde vorm met een echte mediatype:

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

Plak het resultaat in de src van een HTML-img-tag of in een CSS-background en het beeld reist mee met het document, zonder tweede HTTP-verzoek. De valkuilen gaan allemaal over grootte: de RFC zelf zegt dat het schema alleen nuttig is voor korte waarden, browsers leggen hun eigen URL-lengtelimieten op, elk inline byte kost de 33-procent-toeslag bovenop de eigen grootte van het beeld, en een pagina vol data-URIs is een pagina zonder cache-verhaal voor die beelden. Voor kleine icoontjes en eenmalige ingebedde graphics is het een genot; voor een fotoarchief is het een belasting.

Secrets, config en omgevingsvariabelen

Base64 duikt op in config- en secrets-werk om één specifieke reden: het zet willekeurige bytes, inclusief spaties, aanhalingstekens en nieuwe regels, om naar een tekenreeks die een export, een config-regel of een JSON-veld overleeft zonder enige quote-acrobatiek. Kubernetes is het meest zichtbare voorbeeld: elk veld onder .data van een secret is Base64, dus een secret aanmaken in de shell is gewoon coderen:

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

De API-server bewaart het wachtwoord als czNjcmV0 onder .data, en elke node met toegang tot het secret kan het met één decode weer eruit halen. Dezelfde zet werkt ook voor je eigen config-bestanden:

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

Of, voor een bestand dat de applicatie bij het opstarten leest:

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

Nu komt de waarschuwing die op een muur thuishoort: Base64 is codering, geen versleuteling. De beveiligingssectie van RFC 4648 is er bloot over en merkt op dat de codering "informatie die anders makkelijk te herkennen zou zijn, zoals wachtwoorden, visueel verbergt, maar geen enkele rekenmatige vertrouwelijkheid biedt", en dat precies dit misverstand echte beveiligingsincidenten heeft veroorzaakt toen iemand een "beschermde" protocolwissel in een bugrapport plakte en per ongeluk de inloggegevens onthulde. Moet de waarde geheim blijven, versleutel hem dan (en zet daarna de cryptotext in Base64 voor opslag); als Base64 alles is wat je hebt, behandel de gecodeerde waarde als platte tekst op het moment dat die het scherm verlaat.

Unicode, charsets en de bytes eronder

De encoder leest bytes, geen tekens, en de shell reikt hem welke bytes dan ook die de locale en het commando hebben geproduceerd. Voor UTF-8-tekst is dat meestal precies wat je wilt: de é in héllo is al twee bytes, c3 a9, en de codering draagt ze gewoon mee:

printf 'h\xc3\xa9llo' | base64

Die print aMOpbGxv, en een UTF-8-afnemer aan de overkant krijgt héllo terug, byte voor byte. De problemen beginnen als de bron geen UTF-8 is. Een Latin-1-bestand met hetzelfde woord houdt de é als de ene byte e9, en die bytes rechtstreeks coderen produceert tekst die alleen een Latin-1-afnemer kan teruglezen. Converteer eerst, codeer dan:

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

Nog twee feiten op byte-niveau. Een UTF-8-BOM, drie bytes voorin een bestand, codeert naar 77u/ en blijft voor eeuwig voorin je gedecodeerde uitvoer zitten tenzij je hem eerst eraf haalt:

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

En de locale verandert nooit de codering zelf, want de encoder is een bytemachine; hij verandert alleen wat je hebt getypt. Kijkt de uitvoer er verkeerd uit, dan controleer je de bytes die je hebt gevoerd, niet de codering die je hebt uitgevoerd.

E-mail, APIs en uploads

E-mail is waar Base64 zijn manieren heeft geleerd, en die manieren zijn nog steeds de conventie. SMTP voerde historisch gezien alleen 7-bits ASCII, dus reizen bijlagen als Base64, omgebroken op 76 tekens met CRLF-regelafsluitingen, conform RFC 2045. Die exacte vorm produceren voor een MIME-deel is het omwikken plus de regelafsluitingsconversie:

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

De oude bewaker is op ingebouwde systemen nog steeds in dienst: het BusyBox-uuencode met de -m-flag produceert MIME-Base64, omwikkeld in de vertrouwde begin-base64-omkadering, en zijn broer uudecode leest het weer terug:

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

APIs en uploads gebruiken hetzelfde idee in JSON-kledij: het binair wordt een Base64-tekenreeks in een JSON-veld, en curl draagt het. Het lichaam in een shellvariabele opbouwen houdt het quoten eerlijk:

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

Er wonen hier twee interoperabiliteitsvalen. Eerst: controleer welk alfabet de API wil: sommige verwachten standaard Base64, andere het URL-veilige dialect, en een tekenreeks met +-tekens die naar een URL-veilig eindpunt wordt gestuurd (of omgekeerd) faalt de validatie of, erger, decodeert naar de verkeerde bytes. Ten tweede: pas op voor dubbele codering, de klassieke bug waarbij een script een waarde codeert die de server opnieuw codeert, en de rondreis twee decodes nodig heeft om te ontrafelen.

Als de payload groot wordt

De encoder is, net als de decoder, een streamingmachine: hij leest in chunks en schrijft in chunks, dus een tarbal van 10 GB heeft geen 13 GB RAM nodig, en het commando draait met plezier minutenlang op grote invoer met vlak geheugengebruik. De groottemath is het enige planinstrument dat je nodig hebt: de uitvoer is vier tekens per drie invoer-bytes, plus één byte per omgebroken regel, dus een bestand van 300 MB wordt zo'n 400 MB tekst. Voor een snelle realiteitscheck bij elk bestand:

base64 -w 0 big.bin | wc -c

Als de tekst zelf door een kanaal met een groottelimiet moet (een e-mailbijlagelimit, een ticketsysteem, een IM-bericht), split dan de gecodeerde vorm, nooit het ruwe binair, zodat elke chunk gewoonlijke tekst blijft die je kunt plakken, comprimeren of doorsturen:

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

Die produceert een rij delen van 4000 tekens; de ontvanger cat ze in de juiste volgorde weer bij elkaar en decodeert één keer. En als de payload te comprimeren is, comprimeer dan vóór je codeert, want Base64 voegt redundantie toe bovenop wat de data al bevat: een tarbal van een projectmap krimpt doorgaans enkele malen onder gzip, vóór de 33-procent-Base64-toeslag wordt opgelegd:

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

Snelheid zal niet je beperking zijn. Deze encoders persen op een moderne machine gigabytes in ruim onder de seconde door; een bestand van 200 MB kost met de coreutils- en OpenSSL-implementaties zo'n tiende seconde, en zelfs BusyBox, de traagste van de gangbaren, is nog steeds klaar in een fractie van een seconde (gemeten op zo'n kwart seconde voor 200 MB op één moderne machine, enkele malen trager dan coreutils maar bij lange na geen knelpunt). Het knelpunt in echte pipelines is vrijwel altijd het netwerk, niet de codering.

De kleine tekens die bijten

De valkuilen van de coderingskant zijn kleiner dan die van de decodeerkant, en dat is maar terecht:

Gewoontes die je veilig houden

• Noem het aantal bytes. printf '%s' voor tekst, het FILE-argument voor bestanden, en een wc -c-plausibiliteitscheck vóór je iets verzendt waar grootte toe doet.
• Stel de omwikkeling expliciet in. -w 0 voor URLs en JSON, -w 76 voor MIME, -w 64 voor PEM. Laat de breedte nooit aan de standaard van het tool over.
• Kies het alfabet voor de bestemming. Standaard voor e-mail en bestanden, URL-veilig voor tokens en URLs, en lees de documentatie van de afnemer vóór je codeert.
• Comprimeer vóór je codeert. Voor elke te comprimeren payload eerst gzip of tar czf; de 33-procent-toeslag geldt voor alles wat je de encoder in handen geeft.
• Split de tekst, niet het binair. Zit een groottelimiet in de weg, split dan de gecodeerde vorm zodat elke chunk plakveilig blijft, en zet ze in de juiste volgorde weer bij elkaar vóór de enkele decode.
• Houd de drie JWT-taken apart. Alfabet, cryptografie, formaat: codeer de segmenten, onderteken de ASCII-tekst van de samengevoegde segmenten, en geef daarna uit. Wissel ze van volgorde en het token breekt.
• Laat Base64 nooit in de plaats staan van versleuteling. Is de waarde geheim, versleutel hem dan en codeer daarna de cryptotext. Is hij niet geheim, zeg dat dan en maak je geen zorgen meer.

Een korte geschiedenis van coderen in de shell

• 1980, Berkeley. Mary Ann Horton schrijft uuencode en uudecode aan de Universiteit van Californië, Berkeley, om binaire bestanden door e-mail te smokkelen tussen Unix-systemen. De naam, "Unix-naar-Unix-codering", is de geboorteakte van het formaat, en in het decennium of zo daarna is dit waar shellgebruikers mee coderen.
• Het dial-up-tijdperk. uuencode op UNIX en BinHex op de TRS-80 en de Apple II, met de Macintosh een stap achteraan, lossen hetzelfde probleem op met verschillende alfabetten, en elk vertrouwt alleen op de tekens die de eigen terminal kan afdrukken.
• 1993. MIME standardiseert Base64 voor e-mail in RFC 1521, later RFC 2045, met de regelomwikkeling op 76 tekens die de coreutils-standaard tot op de dag van vandaag nog draagt.
• Vóór 2006 op Linux. Er is geen base64-commando. Shellscripts grijpen naar openssl base64, uuencode -m, Perl of Python, en de OpenSSL-gewoonte is zo diep geworteld dat de helft van de oude one-liners in het wild er nog steeds mee begint.
• 15 augustus 2006. coreutils 6.0 levert het base64-commando, en het NEWS-bestand vermeldt het er simpelweg als "base64-codering en -decodering (RFC 3548) functionaliteit", en het één-commando-tijdperk begint. Een paar maanden later, in oktober 2006, formaliseert RFC 4648 de alfabetfamilie, inclusief het URL-veilige dialect waar dit artikel steeds weer naar grijpt.
• OS X 10.7. macOS levert zijn eigen base64, de BSD-variant zonder standaardomwikkeling, en daarom heeft "gewoon base64 draaien" een controle op het platform nodig in portabele scripts.
• 2024. coreutils 9.5 verandert hoe decoders omgaan met invoer zonder padding en niet-canonieke invoer, wat in de praktijk betekent dat encoders een vrijbrief krijgen: uitvoer die oudere GNU-versies zouden hebben afgewezen, decodeert nu netjes. De coderingskant van het formaat is de stabiele; de decoders zijn degenen die zich hebben verplaatst.
• 2025. De herschrijving van coreutils in Rust (uutils) wordt de standaard in recente Ubuntu-releases. Zelfde commando, zelfde flags, een nieuwe motor, en dezelfde 76-tekens-standaard die zij van de C-versie erfde.

Kleine wonderen

• De naam van het formaat is op elke machine waar. printf 'base64' | base64 geeft YmFzZTY0 op GNU, uutils, BusyBox, OpenSSL en macOS, allemaal. Het is waar sinds 2006 en blijft het altijd.
• Een bestand van niets codeert naar een muur van A's. Geef het drie NUL-bytes en de uitvoer is AAAA, want drie bytes met waarde nul worden afgebeeld op vier nul-indexen in het alfabet, en elk daarvan wordt weergegeven door A. Een .b64-bestand dat begint met een lange reeks A's is meestal nul-opvulling in het oorspronkelijke bestand (NUL-bytes), geen raadsel.
• De 33-procent-belasting kent geen korting. Vier tekens per drie bytes, geen comprimering, geen tweede kans. De enige ontsnapping is de data eerst comprimeren, en daarom is tar czf de echte held van pipelines met grote payloads.
• Twee tekens veroorzaakten de hele URL-rummel. + en / zijn de enige alfabetleden die ooit een vervanging nodig hebben gehad, en er is een heel dialect van het formaat in het leven geroepen om hen met pensioen te sturen. Twee-en-zestig en drie-en-zestig, de laatste twee plekken van het alfabet.
• Elf tekens, vierenzestig bits. Een YouTube-videoid is een base64url-tekenreeks van elf tekens, een 64-bits getal in URL-kledij, en daarom reist het door URLs zonder een enkel procentteken.
• De beroemdste nepot van git. De binaire blokken in git diff --binary lijken op Base64, maar de regels met z als voorvoegsel zijn een base85-stijl-dialect op zich. Eén blik en je weet dat het niet jouw alfabet is; één grep-en-decodeer-omweg en je verliest twintig minuten.
• Elk tool wikkelt anders om, opzettelijk. 76 voor MIME, 64 voor PEM, nul bij het BSD-gereedschap: drie standaarden, drie geërfde conventies, één formaat. De breedte was altijd aan jou de keuze; de tools hebben zich alleen verschillende standaarden herinnerd.
• De encoder faalt nooit op jouw data. In tegenstelling tot zijn decodeer-neef heeft de encoder geen ongeldige invoer, geen beschadiging, geen strikte modus. Hij neemt bytes en geeft letters, elke keer. De bugs in dit artikel zitten allemaal in de bytes die je hem geeft en de bestemming waarnaar je ze stuurt.

En als de reis de andere kant op wijst, wanneer een lange tekenreeks van letters, cijfers en af en toe een streepje of onderteken in je terminal landt en je de bytes er weer bij nodig hebt, dan dekt het gerelateerde Base64-decoderingsartikel dat hieronder is gelinkt dat ritueel in dezelfde diepte, van JWT-segmenten zonder padding tot elke nieuwe-regel-val die de decoders verstoppen.

Laatst bijgewerkt: 2026-10-06

Gerelateerd artikel: Base64-decodering in Bash: een complete gids