Encodage Base64 en Bash : un guide complet

Vous avez des octets et il vous faut une chaîne. Un fichier texte qui doit vivre dans un corps JSON. Une image qui doit tenir sur une ligne de configuration. Un jeton qui va voyager à travers une URL, une variable d'environnement ou un en-tête HTTP. Une clé privée qui a sa place dans un magasin de certificats. C'est le boulot de tous les jours de l'encodage Base64 dans la shell, et la réponse de la shell est une seule commande, petite et remarquablement portable.

L'échange en un souffle : le Base64 réécrit chaque groupe de trois octets de données brutes en quatre caractères d'un alphabet de 64 lettres (A-Z, a-z, 0-9, plus + et /), en remplissant la queue d'un ou deux signes = quand le nombre d'octets n'est pas un multiple de trois. La page d'accueil de ce site explique le format en entier ; ici, on passe notre temps à produire le texte, à choisir le bon dialecte pour la destination, et à payer la note de taille les yeux ouverts. Un chiffre à garder en poche : la forme encodée est normalement environ un tiers plus grosse que l'original, quatre caractères pour trois octets, et ça revient sans cesse.

La distribution est petite. La commande base64 de coreutils (GNU ou la famille Rust uutils plus récente), basenc de la même famille pour le dialecte URL-safe, openssl base64 pour les machines sans coreutils, l'applet BusyBox pour les systèmes embarqués, et la saveur BSD sur macOS. Cinq outils, un travail, quelques drapeaux qui valent le coup de les connaître.

Choisir son encodeur

Chacun de ces outils lit des octets depuis l'entrée standard ou un fichier et écrit du texte vers la sortie standard, donc ils se glissent tous dans les mêmes pipelines. Les différences, c'est l'enveloppement par défaut des lignes et les dialectes disponibles :

Lisez cette colonne d'enveloppement deux fois, parce que c'est la différence silencieuse entre les familles. Coreutils et BusyBox enveloppent à 76 par défaut, OpenSSL enveloppe à 64, et l'outil BSD n'enveloppe pas du tout. Aucun n'a tort ; ils ont juste hérité de conventions différentes (MIME dit 76, PEM dit 64, et l'outil BSD est tout simplement plus vieux que l'habitude d'envelopper). Quand votre consommateur s'en soucie, fixez la largeur explicitement et ne comptez jamais sur la valeur par défaut.

Le texte d'abord : le saut de ligne invisible

Encoder du texte dans une shell commence par un piège : echo ajoute un saut de ligne. Ces cinq lettres « hello » deviennent six octets dès qu'elles passent par echo, et le sixième octet voyage avec jusqu'à la sortie, invisible et permanent :

echo "hello" | base64

Cela affiche aGVsbG8K, et le dernier caractère encode le saut de ligne. Le correctif est celui qu'il faut utiliser pour du texte où le nombre d'octets compte : printf avec un format, sans décoration :

printf '%s' "hello" | base64

Maintenant la sortie est aGVsbG8=, exactement cinq octets, et le dernier caractère est un signe de remplissage plutôt qu'un octet vivant. La même règle s'applique aux here-strings, qui ajoutent un saut de ligne final comme echo : base64 <<< "hello" vous redonne la version aGVsbG8K. En cas de doute, demandez-vous ce que vaut le dernier octet avant de l'encoder.

Pour tout ce que vous voulez sur une seule ligne, ajoutez -w 0 (ou les cousins de -w 0 ci-dessous), qui retire aussi le saut de ligne final que la commande émettrait sinon :

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

C'est une ligne propre et ininterrompue, sans saut de ligne final, prête à tomber dans une URL, une valeur JSON ou un fichier de configuration sans aucune cérémonie de plus.

Fichiers et largeur d'enveloppement

Les fichiers sont le cas courant, et toute implémentation prend un argument FILE, qui tient les octets à l'écart du mécanisme de guillemets de la shell, tout à fait :

base64 -w 0 report.pdf > report.b64

Sans -w 0, la sortie arrive enveloppée à 76 caractères, ce qui est exactement ce qu'un consommateur MIME veut :

base64 report.pdf > report.mime.b64

La largeur est un bouton que vous réglez par consommateur. Soixante-seize, c'est la convention MIME de la RFC 2045, soixante-quatre, c'est la convention PEM utilisée par les certificats et les clés, et zéro, c'est une ligne ininterrompue pour les URL et les API :

base64 -w 64 key.bin | head -2

Si le consommateur vit sur Windows et attend des fins de ligne CRLF, convertissez après l'enveloppement, pas avant :

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

Pour le chemin OpenSSL, l'équivalent du mode une-ligne est le drapeau -A, qui supprime aussi le saut de ligne final :

openssl base64 -A < report.pdf

Avant d'envoyer un fichier enveloppé, une vérification de plausibilité de la taille ne coûte rien et attrape un nombre surprenant d'erreurs (un fichier encodé deux fois, un fichier encodé avec la mauvaise entrée) :

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

Le deuxième nombre devrait être environ quatre sur trois fois la taille du premier, plus un octet par ligne enveloppée pour les sauts de ligne. S'il est radicalement différent, arrêtez-vous et regardez ce que vous avez réellement donné à l'encodeur.

Base64 URL-safe : échanger les deux caractères chiants

Deux caractères de l'alphabet standard, + et /, sont les enfants terribles : un + dans une chaîne de requête d'URL veut dire espace, un / peut ressembler à un séparateur de chemin, et les deux forcent l'encodage en pourcent dès que la chaîne entre dans une URL, un cookie ou un nom de fichier. La section 5 de la RFC 4648 règle ça avec un dialecte qui remplace exactement ces deux caractères par - et _, et supprime le remplissage, puisque une URL a rarement besoin de déclamer la longueur exacte en octets.

La recette shell est un échange plus une coupe, un passage dans tr pour l'alphabet et un pour enlever le remplissage :

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

Ces trois octets s'encodent normalement en /k+C, ce qui serait laid dans une URL ; le pipeline en fait _k-C, quatre caractères qui peuvent voyager n'importe où. L'échange est positionnel, donc la direction est facile à mélanger : l'encodage passe par tr '+/' '-_' (plus devient tiret, barre oblique devient tiret bas), et l'inverse, qui appartient au décodage, passe par tr '_-' '/+'. Une direction mélangée ne donne pas d'erreur, elle produit juste d'autres octets, ce qui est le pire genre de bug à livrer.

Le dialecte compte à chaque fois que la chaîne sort du contrôle de la shell : segments de JWT, jetons dans des chaînes de requête, valeurs dans des cookies ou des noms de fichiers, et tout identifiant qu'un autre système lira comme partie d'une URL. Le basenc de GNU produit le dialecte nativement, avec le remplissage encore en place :

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

Supprimez le remplissage avec tr -d '=' si le consommateur veut la forme coupée, comme la plupart.

Frapper un JWT dans la shell

Les JSON Web Tokens sont le consommateur le plus visible du Base64 URL-safe dans le monde des API. Un JWT compact est trois segments base64url reliés par des points : l'en-tête, le payload et la signature, selon la RFC 7515. Les deux premiers sont du JSON pur ; la signature est un digest binaire des deux premiers segments reliés par un point, ce qui est exactement le genre de choses que openssl sait faire.

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"

Cela affiche un JWT HS256 compact qu'une bibliothèque standard de n'importe quelle plateforme acceptera. Remarquez la division du travail : la partie Base64 est l'alphabet, la partie openssl dgst -sha256 -hmac est le cryptage, et la liaison par points est le format. Gardez les trois tâches séparées dans votre tête et le pipeline reste évident.

Trois précautions pour le terrain. D'abord, le MAC est calculé sur le texte ASCII des deux premiers segments plus le point, donc les segments doivent déjà être dans leur forme base64url finale quand vous les signez ; ré-envelopper ou ré-remplir après la signature casse le jeton. Deuxièmement, la clé reste en dehors du jeton : la signature prouve qui a signé, la clé garde le secret secret. Troisièmement, frapper dans un script shell est un outil de test et d'automatisation, pas un remplacement du serveur qui émettra et vérifiera réellement ces jetons, et un jeton frappé avec alg: none ne prouve absolument rien.

Data URIs : des fichiers qui voyagent dans des chaînes

La RFC 2397 définit le schéma d'URL data:, et sa forme Base64 laisse un fichier vivre dans une URL : data:, puis un type média optionnel, puis ;base64 quand le payload est encodé en Base64, puis une virgule, puis les données. Omettez le type média et la valeur par défaut est text/plain;charset=US-ASCII, ce qui est un piège à pied qui vaut le coup de le connaître, parce que la plupart du temps on vise une image ou un document JSON, pas du texte ASCII.

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

Cela affiche data:text/plain;base64,aGkgdGhlcmU=, une URL complète et autosuffisante qu'un navigateur affichera sans problème. Pour une image, la même forme avec un vrai type média :

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

Collez le résultat dans une balise img HTML, dans son src, ou dans un background CSS, et l'image part avec le document, sans seconde requête HTTP. Les pièges sont tous question de taille : la RFC elle-même dit que le schéma n'est utile que pour des valeurs courtes, les navigateurs imposent leurs propres limites de longueur d'URL, chaque octet inliné coûte les 33 pour cent de surcoût par-dessus la taille de l'image elle-même, et une page pleine de data URIs est une page sans aucune histoire de mise en cache pour ces images. Pour de petits icônes et des graphiques embarqués ponctuels, c'est un plaisir ; pour une bibliothèque de photos, c'est une taxe.

Secrets, configuration et variables d'environnement

Le Base64 apparaît dans le travail de configuration et de secrets pour une raison précise : il transforme des octets arbitraires, y compris espaces, guillemets et sauts de ligne, en une chaîne qui survit à un export, une ligne de configuration ou un champ JSON sans aucune acrobatie de guillemets. Kubernetes est l'exemple le plus visible : chaque champ sous .data d'un secret est du Base64, donc créer un secret dans la shell est juste de l'encodage :

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

Le serveur API range le mot de passe en tant que czNjcmV0 sous .data, et n'importe quel nœud avec accès au secret peut le relire avec un seul décodage. Le même geste marche pour vos propres fichiers de configuration :

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

Ou, pour un fichier que l'application lit au démarrage :

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

Vient maintenant l'avertissement qui mérite d'être affiché sur un mur : le Base64 est de l'encodage, pas du chiffrement. La section sécurité de la RFC 4648 est franche là-dessus, notant que l'encodage « masque visuellement des informations autrement facilement reconnaissables, comme des mots de passe, mais ne fournit aucune confidentialité calculatoire », et que ce malentendu exact a causé de vrais incidents de sécurité quand quelqu'un a collé un échange de protocole « protégé » dans un rapport de bug et a révélé par erreur les identifiants. Si la valeur doit être secrète, chiffrez-la (et ensuite faites du Base64 sur le chiffré pour le stockage) ; si le Base64 est tout ce que vous avez, traitez la valeur encodée comme du texte brut dès qu'elle quitte l'écran.

Unicode, charsets et les octets dessous

L'encodeur lit des octets, pas des caractères, et la shell lui remet les octets que la locale et la commande ont produits. Pour du texte UTF-8, c'est d'habitude exactement ce que vous voulez : le é de héllo est déjà deux octets, c3 a9, et l'encodage les transporte juste avec :

printf 'h\xc3\xa9llo' | base64

Cela affiche aMOpbGxv, et un consommateur UTF-8 de l'autre côté retrouve héllo, octet pour octet. Les ennuis commencent quand la source n'est pas UTF-8. Un fichier Latin-1 avec le même mot garde un unique octet e9 pour le é, et encoder ces octets tels quels produit un texte qu'un seul consommateur Latin-1 peut relire. Convertissez d'abord, encodez ensuite :

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

Deux faits de niveau octet de plus. Un BOM UTF-8, trois octets au début d'un fichier, s'encode en 77u/ et restera au début de votre sortie décodée pour toujours à moins de l'enlever d'abord :

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

Et la locale ne change jamais l'encodage lui-même, parce que l'encodeur est une machine à octets ; elle ne change que ce que vous avez tapé. Quand la sortie a l'air fausse, vérifiez les octets que vous avez donnés, pas l'encodage que vous avez lancé.

E-mails, API et téléversements

L'e-mail est là que le Base64 a appris les bonnes manières, et les bonnes manières sont toujours la convention. Le SMTP ne portait historiquement que de l'ASCII 7 bits, donc les pièces jointes voyagent en Base64 enveloppé à 76 caractères avec des fins de ligne CRLF, selon la RFC 2045. Produire exactement cette forme pour une partie MIME, c'est l'enveloppement plus la conversion des fins de ligne :

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

L'ancienne garde est encore de service dans les systèmes embarqués : l'uuencode de BusyBox avec le drapeau -m produit du MIME Base64 enveloppé dans le cadre familier begin-base64, et son frère uudecode le relit :

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

Les API et les téléversements utilisent la même idée en costume JSON : le binaire devient une chaîne Base64 dans un champ JSON, et curl le transporte. Construire le corps dans une variable shell garde les guillemets honnêtes :

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

Deux pièges d'interopérabilité vivent ici. D'abord, vérifiez quel alphabet l'API veut : certaines attendent du Base64 standard, certaines attendent le dialecte URL-safe, et une chaîne avec des caractères + envoyée à un point d'entrée URL-safe (ou l'inverse) échouera la validation ou, pire, se décodera en mauvais octets. Deuxièmement, surveillez le double encodage, le bug classique où un script encode une valeur que le serveur encode à nouveau, et l'aller-retour a besoin de deux décodages pour se dérouler.

Quand le payload devient gros

L'encodeur, comme le décodeur, est une machine de streaming : il lit par morceaux et écrit par morceaux, donc un tarball de 10 GB n'a pas besoin de 13 GB de RAM, et la commande tourne joyeusement pendant des minutes sur des entrées grosses avec un usage mémoire plat. Le calcul de taille est le seul outil de planification dont vous avez besoin : la sortie fait quatre caractères pour trois octets d'entrée, plus un octet par ligne enveloppée, donc un fichier de 300 MB devient environ 400 MB de texte. Pour un contrôle de réalité rapide sur n'importe quel fichier :

base64 -w 0 big.bin | wc -c

Quand le texte lui-même doit passer par un canal avec limite de taille (un plafond de pièce jointe d'e-mail, un système de tickets, un message IM), coupez la forme encodée, jamais le binaire brut, pour que chaque morceau reste du texte ordinaire que vous pouvez coller, comprimer ou transférer :

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

Cela produit une série de morceaux de 4000 caractères ; le destinataire les recolle ensemble dans l'ordre avec cat et décode une seule fois. Et quand le payload est compressible, compressez avant d'encoder, parce que le Base64 ajoute de la redondance par-dessus ce que les données contiennent déjà : un tarball d'un répertoire de projet rétrécit typiquement plusieurs fois sous gzip avant que la surcharge Base64 de 33 pour cent ne s'applique :

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

La vitesse ne sera pas votre contrainte. Ces encodeurs poussent des gigaoctets en bien moins d'une seconde sur une machine moderne ; un fichier de 200 MB prend une dixième de seconde environ avec les implémentations coreutils et OpenSSL, et même BusyBox, la plus lente des courantes, est encore fini en une fraction de seconde (mesuré à un quart de seconde environ pour 200 MB sur une machine moderne, plusieurs fois plus lent que coreutils mais loin d'être un goulot d'étranglement). Le goulot d'étranglement dans les pipelines réels est presque toujours le réseau, pas l'encodage.

Les petits caractères qui mordent

Les pièges du côté encodage sont plus petits que ceux du côté décodage, et c'est mérité :

Des habitudes qui vous gardent en sécurité

• Donnez un nom au nombre d'octets. printf '%s' pour le texte, l'argument FILE pour les fichiers, et une vérification de plausibilité wc -c avant d'envoyer quoi que ce soit où la taille compte.
• Fixez l'enveloppement explicitement. -w 0 pour les URL et le JSON, -w 76 pour le MIME, -w 64 pour le PEM. Ne laissez jamais la largeur à la valeur par défaut de l'outil.
• Choisissez l'alphabet pour la destination. Standard pour l'e-mail et les fichiers, URL-safe pour les jetons et les URL, et vérifiez la documentation du consommateur avant d'encoder.
• Compressez avant d'encoder. Pour n'importe quel payload compressible, gzip ou tar czf d'abord ; la surcharge de 33 pour cent s'applique à ce que vous donnez à l'encodeur.
• Coupez le texte, pas le binaire. Quand une limite de taille se met en travers, split la forme encodée pour que chaque morceau reste sûr à coller, et réassemblez dans l'ordre avant le décodage unique.
• Gardez les trois tâches JWT séparées. Alphabet, cryptage, format : encodez les segments, signez le texte ASCII des segments reliés, puis émettez. Réordonnez-les et le jeton casse.
• N'autorisez jamais le Base64 à remplacer le chiffrement. Si la valeur est secrète, chiffrez-la puis encodez le chiffré. Si elle n'est pas secrète, dites-le et cessez de vous inquiéter.

Une courte histoire de l'encodage dans la shell

• 1980, Berkeley. Mary Ann Horton écrit uuencode et uudecode à l'Université de Californie, Berkeley, pour faire voyager des fichiers binaires par e-mail entre systèmes Unix. Le nom, « encodage Unix-vers-Unix », est l'acte de naissance du format, et pendant la décennie qui suit, c'est avec cela que les utilisateurs de shell encodent.
• L'ère du modulateur. uuencode sur UNIX et BinHex sur le TRS-80 et l'Apple II, avec le Macintosh un peu derrière, résolvent le même problème avec des alphabets différents, chacun ne faisant confiance qu'aux caractères que son propre terminal peut imprimer.
• 1993. MIME standardise le Base64 pour l'e-mail dans la RFC 1521, plus tard RFC 2045, avec l'enveloppement à 76 caractères que la valeur par défaut de coreutils porte encore aujourd'hui.
• Avant 2006 sur Linux. Il n'y a pas de commande base64. Les scripts shell vont vers openssl base64, uuencode -m, Perl ou Python, et l'habitude OpenSSL est si ancrée que la moitié des vieux one-liners dans la nature commencent encore par elle.
• 15 août 2006. coreutils 6.0 livre la commande base64, son fichier NEWS la crédite en tant que « fonctionnalité d'encodage et de décodage Base64 (RFC 3548) », et l'ère de la commande unique commence. Quelques mois plus tard, en octobre 2006, la RFC 4648 formalise la famille d'alphabets, y compris le dialecte URL-safe vers lequel cet article ne cesse de tendre la main.
• OS X 10.7. macOS embarque son propre base64, la saveur BSD sans enveloppement par défaut, et c'est pourquoi « lance juste base64 » a besoin d'une vérification de plateforme dans les scripts portables.
• 2024. coreutils 9.5 change la manière dont les décodeurs traitent les entrées sans remplissage et non canoniques, ce qui en pratique veut dire que les encodeurs ont un passe gratuit : une sortie que d'anciennes versions de GNU auraient rejetée se décode maintenant proprement. Le côté encodeur du format est le stable ; ce sont les décodeurs qui ont bougé.
• 2025. La réécriture de coreutils en Rust (uutils) devient la valeur par défaut des sorties Ubuntu actuelles. Même commande, mêmes drapeaux, un nouveau moteur, et le même défaut à 76 caractères hérité de la version C.

De petites merveilles

• Le nom du format est vrai sur chaque machine. printf 'base64' | base64 donne YmFzZTY0 sur GNU, uutils, BusyBox, OpenSSL et macOS, tous pareils. C'est vrai depuis 2006 et le sera toujours.
• Un fichier de rien s'encode en un mur de A. Donnez-lui trois octets NUL et la sortie est AAAA, parce que trois octets de valeur zéro se mappent sur quatre indices zéro dans l'alphabet, chacun représenté par A. Un fichier .b64 qui commence par une longue série de A est d'habitude un bourrage de zéros dans le fichier original (octets NUL), pas un mystère.
• La taxe de 33 pour cent n'a pas de réductions. Quatre caractères pour trois octets, pas de compression, pas de seconde chance. La seule échappatoire est de compresser les données d'abord, et c'est pourquoi tar czf est le vrai héros des pipelines à gros payload.
• Deux caractères ont causé tous les ennuis d'URL. + et / sont les seuls membres de l'alphabet qui aient jamais eu besoin d'un substitut, et un dialecte entier du format existe pour les mettre à la retraite. Soixante-deux et soixante-trois, les deux derniers postes de l'alphabet.
• Onze caractères, soixante-quatre bits. Un identifiant de vidéo YouTube est une chaîne base64url de 11 caractères, un nombre de 64 bits en costume URL, et c'est pourquoi il voyage à travers les URL sans le moindre signe pourcent.
• L'imposteur le plus célèbre de git. Les blocs binaires dans git diff --binary ressemblent au Base64, mais les lignes préfixées par z sont un dialecte de style base85 à part. Un coup d'œil et vous savez que ce n'est pas votre alphabet ; un détour grep-et-décoder et vous perdez vingt minutes.
• Chaque outil enveloppe différemment, exprès. 76 pour le MIME, 64 pour le PEM, zéro sur l'outil BSD : trois valeurs par défaut, trois conventions héritées, un format. La largeur a toujours été à vous de choisir ; les outils se sont juste souvenus de valeurs par défaut différentes.
• L'encodeur ne rate jamais sur vos données. Contrairement à son cousin décodeur, l'encodeur n'a pas d'entrée invalide, pas de corruption, pas de mode strict. Il prend des octets et donne des lettres, à chaque fois. Les bugs de cet article sont tous dans les octets que vous lui donnez et la destination où vous les envoyez.

Et quand le voyage pointe dans l'autre sens, quand une longue chaîne de lettres, de chiffres et, de temps en temps, de tiret ou de tiret bas atterrit dans votre terminal et que vous avez besoin des octets, l'article lié sur le décodage Base64, en lien ci-dessous, couvre ce rituel avec la même profondeur, des segments de JWT sans remplissage à chaque piège de saut de ligne que les décodeurs cachent.

Dernière mise à jour : 2026-09-08

Article associé : Décodage Base64 en Bash : un guide complet