Chiffrement Borg : repokey ou keyfile, où est la clé

Le mode de chiffrement d'un dépôt Borg se fige à la création

Le chiffrement Borg se décide à la première commande, avec l'option --encryption, et ce choix reste inscrit dans le dépôt pour toute sa vie. Les modes repokey et keyfile chiffrent vos archives de la même façon. Ils répondent à une seule question: où la clé est rangée. En repokey, la clé est écrite à l'intérieur du dépôt. En keyfile, elle est écrite sur la machine qui lance borg create, jamais dans le dépôt.

Cette différence décide de ce que vous devez mettre à l'abri. Un dépôt en repokey voyage avec sa clé: une copie du dépôt plus la phrase secrète suffisent pour restaurer. Un dépôt en keyfile ne voyage pas seul: sans le fichier de clé du client, la copie du dépôt est illisible et aucune commande ne la récupère. Dans les deux cas il faut la clé et la phrase secrète, donc la règle qui compte est la même: exportez la clé, et gardez-la avec la phrase secrète ailleurs que sur le serveur sauvegardé.

Tout ce qui suit se fait sur une seule machine, dans un seul terminal. Pas de second hôte, pas de montage FUSE. Le transport vers un dépôt distant en ssh:// et la rétention avec borg prune puis borg compact ne changent rien au mode de chiffrement, et ne sont pas traités ici.

Demandez la liste des modes à votre binaire, pas à un article

Le nom des commandes et la liste des modes ont changé entre les lignes de Borg. Commencez donc par interroger le binaire installé.

sudo apt update && sudo apt install -y borgbackup
borg --version
borg init --help
borg key --help

Relevez deux choses dans cette sortie: le numéro de version, et la liste exacte imprimée en face de -e MODE, --encryption MODE. Notez aussi les sous-commandes que borg key propose chez vous, car elles varient d'une version à l'autre.

Au 27 septembre 2026, le paquet borgbackup d'Ubuntu 24.04 est en version 1.2.8-1, et c'est cette ligne 1.2 que suivent les commandes ci-dessous. Elle exige --encryption à la création: il n'existe aucune valeur par défaut, ce qui explique pourquoi tant de lecteurs restent bloqués sur cette option précise. Ses modes sont none, authenticated, authenticated-blake2, repokey, repokey-blake2, keyfile et keyfile-blake2.

Si borg init --help répond que la commande est inconnue, votre binaire vient de la ligne 2.x. Elle renomme les commandes de dépôt: la création s'appelle borg repo-create, le dépôt se passe par l'option globale -r, et la liste des modes est différente (repokey-aes-ocb, repokey-chacha20-poly1305, leurs variantes blake2, et les mêmes en keyfile-). Un article écrit de mémoire vieillit mal sur ce point. La sortie de --help de votre machine est la seule liste qui vaille.

Créer un dépôt repokey et un dépôt keyfile côte à côte

Les deux dépôts tiennent dans votre répertoire personnel. BORG_NEW_PASSPHRASE répond à la demande de nouvelle phrase secrète et BORG_DISPLAY_PASSPHRASE à la question de vérification, ce qui évite quatre invites interactives.

mkdir -p ~/borg-demo ~/donnees
echo "fichier de demonstration" > ~/donnees/exemple.txt
export BORG_NEW_PASSPHRASE='phrase-de-demo-a-remplacer'
export BORG_DISPLAY_PASSPHRASE=no
borg init --encryption=repokey ~/borg-demo/depot-repokey
borg init --encryption=keyfile ~/borg-demo/depot-keyfile
unset BORG_NEW_PASSPHRASE

Ajoutez une archive dans chacun, pour travailler sur des dépôts réels plutôt que vides.

export BORG_PASSPHRASE='phrase-de-demo-a-remplacer'
borg create ~/borg-demo/depot-repokey::essai-1 ~/donnees
borg create ~/borg-demo/depot-keyfile::essai-1 ~/donnees
borg list ~/borg-demo/depot-keyfile

borg list doit afficher une ligne pour l'archive essai-1. Une erreur à cet endroit signifie que la phrase secrète exportée ne correspond pas à celle utilisée à la création.

Une précision sur ces variables: BORG_PASSPHRASE place la phrase secrète dans l'environnement du processus, ce qui va pour une démonstration jetable. Pour une sauvegarde réelle, préférez BORG_PASSCOMMAND, qui lit la phrase sur la sortie standard d'une commande, ou BORG_PASSPHRASE_FD, qui la lit sur un descripteur de fichier.

Où la clé finit-elle vraiment ? Cherchez-la, ne la supposez pas

Plutôt que de recopier un chemin par défaut trouvé ailleurs, faites imprimer la clé par Borg, prenez le premier mot de sa première ligne comme marqueur, puis cherchez ce marqueur sur le disque.

borg key export ~/borg-demo/depot-keyfile | head -c 32; echo
marqueur=$(borg key export ~/borg-demo/depot-keyfile | head -1 | awk '{print $1}')
echo "marqueur : $marqueur"
grep -rl "$marqueur" "$HOME" 2>/dev/null

Notez ce que grep retourne, et surtout ce qu'il ne retourne pas: le chemin du fichier de clé du dépôt keyfile, tel que votre version le nomme, et aucun fichier situé à l'intérieur du dépôt repokey. Le répertoire où ce fichier atterrit est celui que désigne la variable BORG_KEYS_DIR, et BORG_KEY_FILE permet d'imposer un fichier précis. La documentation amont est claire sur leur portée: ces deux variables ne s'appliquent qu'aux modes keyfile, jamais aux modes repokey.

Pour le dépôt repokey, la clé est rangée dans le fichier config du dépôt. Comparez les deux fichiers, tronqués pour ne pas remplir l'écran de base64.

for d in ~/borg-demo/depot-repokey ~/borg-demo/depot-keyfile; do
  echo "== $d"
  cut -c1-72 "$d/config"
done

Regardez lequel des deux fichiers porte une entrée key et lequel n'en porte pas. C'est toute la différence entre les deux familles de modes, visible en clair, sans rien deviner. Cette clé stockée est chiffrée par votre phrase secrète, ce n'est donc pas un secret en clair, mais traitez-la comme un secret: ne collez pas cette sortie dans un ticket ni sur un forum.

Une autre chose à relever dans cette sortie: l'entrée key ne tient pas sur une seule ligne. Sa valeur est repliée sur plusieurs lignes, les suivantes décalées par une indentation, comme le veut la convention des fichiers INI. D'où une règle: n'éditez jamais ce config à la main. Effacer la première ligne de l'entrée laisse les lignes indentées derrière elle, où elles se rattachent à l'entrée précédente, celle qui porte l'identifiant du dépôt, et Borg refuse d'ouvrir un dépôt dont il ne sait plus lire l'identifiant. borg key import ne rattrape pas cela, parce qu'il ouvre le dépôt avant d'y écrire la clé. Si vous voulez sortir la clé d'un dépôt repokey, regardez ce que borg key --help propose chez vous plutôt que d'ouvrir un éditeur de texte.

La conséquence est immédiate. Copiez le répertoire du dépôt repokey ailleurs et il reste lisible avec la seule phrase secrète.

cp -a ~/borg-demo/depot-repokey /tmp/copie-repokey
BORG_RELOCATED_REPO_ACCESS_IS_OK=yes borg list /tmp/copie-repokey

BORG_RELOCATED_REPO_ACCESS_IS_OK=yes répond à l'avertissement que Borg émet quand un dépôt qu'il connaît déjà apparaît à un nouvel emplacement. Le dépôt keyfile ne se comporte pas ainsi, et la section suivante le montre en supprimant sa clé.

Ce que fait le dépôt quand la clé et la phrase secrète ont disparu

Simulez la perte, en gardant d'abord une copie de secours hors du répertoire personnel pour ne pas polluer les recherches suivantes.

cle=$(grep -rl "$marqueur" "$HOME" 2>/dev/null | head -1)
cp "$cle" /tmp/copie-de-secours-cle
rm "$cle"
borg list ~/borg-demo/depot-keyfile

Relevez la ligne exacte que votre version affiche, et gardez-la: c'est le message que vous lirez le jour d'une restauration sur une machine neuve. Le dépôt est intact, les archives sont toutes là, et rien ne peut les ouvrir. Aucune option ne contourne cela, parce que la clé est le matériel de chiffrement lui-même et non un simple contrôle d'accès.

La réparation consiste à réimporter la copie.

borg key import ~/borg-demo/depot-keyfile /tmp/copie-de-secours-cle
borg list ~/borg-demo/depot-keyfile

Faites maintenant l'autre moitié du test, sur le dépôt repokey, avec une phrase secrète fausse.

BORG_PASSPHRASE='mauvaise-phrase' borg list ~/borg-demo/depot-repokey

Relevez là aussi le message affiché. La clé est bien présente dans le dépôt, mais elle est chiffrée par la phrase secrète, donc une phrase perdue vaut une clé perdue. C'est la raison pour laquelle la phrase secrète d'un dépôt repokey doit être longue et générée, jamais choisie de tête: elle est le seul obstacle qui reste à qui obtient une copie du dépôt.

Ce qu'il faut copier hors du serveur pour qu'une restauration reste possible

borg key export fonctionne pour les deux familles de modes et produit un fichier que borg key import sait relire. C'est l'opération à faire une fois par dépôt, juste après la création.

borg key export ~/borg-demo/depot-repokey ~/cle-depot-repokey.txt
borg key export ~/borg-demo/depot-keyfile ~/cle-depot-keyfile.txt
chmod 600 ~/cle-depot-repokey.txt ~/cle-depot-keyfile.txt
borg key export --paper ~/borg-demo/depot-keyfile ~/cle-keyfile-papier.txt

L'option --paper écrit une version numérotée, lisible et retapable à la main, faite pour être imprimée; elle se réimporte avec borg key import --paper. Si les permissions par défaut de vos fichiers vous surprennent, la logique derrière chmod 600 est détaillée dans les modes chmod numériques et symboliques.

Sortez ensuite ces fichiers de la machine sauvegardée, puis effacez-les de son disque. Un export de clé posé à côté du dépôt ne sert à rien: le jour où vous perdez le serveur, vous perdez les deux ensemble. La documentation amont le dit sans détour pour les modes keyfile: garder une copie de la clé sur le système que vous sauvegardez n'est pas suffisant.

repokey ou keyfile pour un dépôt chez un hébergeur

Prenez le cas courant: un serveur à sauvegarder, et un dépôt posé sur un VPS de stockage ou sur une storage box louée. Le client Borg tourne sur le serveur, le dépôt vit ailleurs.

repokey est le choix raisonnable par défaut dans cette configuration. La clé suit le dépôt, donc une restauration sur une machine neuve demande l'accès au dépôt et la phrase secrète, rien d'autre. Le coût est net: qui obtient une copie du dépôt obtient aussi la clé chiffrée, et il ne lui manque plus que la phrase secrète. Une phrase longue et aléatoire n'est donc pas une précaution, c'est la condition du mode.

keyfile sépare les deux éléments. La clé reste chez le client, le dépôt chez l'hébergeur, et quelqu'un qui ne détient que le dépôt n'a rien d'exploitable. Le coût est opérationnel: vous gérez un fichier de plus, sur chaque client, et une machine réinstallée sans ce fichier ne restaure plus rien. Ce mode se tient quand vous savez déjà où vit la copie de la clé et qui la détient.

Les modes authenticated et authenticated-blake2 n'apportent aucune confidentialité: ils authentifient le contenu sans le chiffrer. Ils ont un sens quand le chiffrement est déjà assuré en dessous, par exemple par un volume chiffré côté hébergeur, ce que traite chiffrer vos données sur un VPS de stockage. Le mode none renonce aux deux, et sur un dépôt hébergé chez un tiers il n'y a pas de raison de le choisir.

Le suffixe -blake2 change la fonction de hachage, pas l'endroit où la clé est rangée. La documentation amont indique que BLAKE2b est plus rapide que SHA-256 sur les processeurs dépourvus d'extensions matérielles de hachage, ce qui dépend du CPU que votre plan vous alloue; cela se vérifie dans /proc/cpuinfo, exactement comme la présence d'AES-NI sur un VPS. Sur le choix de l'outil avant celui du mode, la comparaison entre Restic et BorgBackup pose les critères. Et si le dépôt n'existe pas encore, le comparatif entre VPS de stockage, volume bloc et stockage objet aide à décider où le poser.

Où garder la clé et la phrase secrète

La clé exportée et la phrase secrète sont deux secrets, et aucun des deux ne doit vivre sur la machine sauvegardée. Un gestionnaire de mots de passe est le bon endroit pour les deux, avec le chemin du dépôt et le mode utilisé notés dans la même fiche, parce que dans trois ans vous ne vous en souviendrez pas. Un Vaultwarden auto-hébergé sur un VPS fait ce travail, avec une boucle à éviter: si ce Vaultwarden tourne sur la machine que Borg sauvegarde, le secret nécessaire à la restauration disparaît avec elle. Hébergez-le ailleurs, et vérifiez que ses propres sauvegardes fonctionnent, ce que décrit la sauvegarde et la restauration de Vaultwarden.

Ajoutez une seconde copie qui survit au serveur et au gestionnaire. La sortie de borg key export --paper, imprimée et rangée dans une autre pièce, tient ce rôle; une clé USB chiffrée gardée hors ligne aussi. Deux copies dans deux endroits distincts, c'est le minimum, parce qu'une clé de sauvegarde perdue transforme des mois d'archives en octets inutiles.

L'accès au dépôt distant est un troisième secret, de nature différente: la clé SSH du compte qui écrit dans le dépôt. Elle n'ouvre pas les archives, elle ouvre le stockage, et elle relève de la gestion des clés SSH plutôt que des règles de la clé Borg.

Dernier geste utile, et le seul qui prouve quelque chose: une fois la clé exportée et rangée, faites une restauration d'essai depuis une machine qui n'a jamais vu ce dépôt. C'est ainsi que vous saurez que la copie exportée est complète et que la phrase secrète notée est la bonne.

FAQ

Peut-on changer le mode de chiffrement d'un dépôt Borg existant ?

Le mode est fixé à la création et borg init ne le remplace pas sur un dépôt déjà en place. Selon la version, borg key offre plus ou moins de sous-commandes autour de l'emplacement de la clé, donc lisez ce que borg key --help liste chez vous avant de chercher une option ailleurs. La voie sûre reste de créer un nouveau dépôt avec le mode voulu et d'y refaire des archives, en conservant l'ancien dépôt jusqu'à la première restauration réussie depuis le nouveau.

En mode repokey, faut-il quand même exporter la clé ?

Oui. La clé étant dans le dépôt, elle est protégée exactement autant que le dépôt: un dépôt effacé emporte la clé avec lui, et un fichier config abîmé peut y suffire. Un export gardé ailleurs est la seule copie de la clé qui ne dépende pas de l'état du dépôt, et il se réimporte dans un dépôt que Borg arrive encore à ouvrir. La documentation amont recommande cet export hors site pour repokey aussi, y compris sur papier.

Où Borg range-t-il le fichier de clé en mode keyfile ?

Dans le répertoire de clés du client, désigné par la variable BORG_KEYS_DIR, sachant que BORG_KEY_FILE permet d'imposer un fichier précis. Ces deux variables ne concernent que les modes keyfile. Plutôt que de recopier un chemin lu dans un article, exportez la clé vers la sortie standard, prenez le premier mot de la première ligne, puis lancez grep -rl avec ce mot sur votre répertoire personnel: le chemin retourné est celui de votre version.

Que se passe-t-il si je perds la phrase secrète mais que j'ai la clé ?

Les archives restent illisibles. La clé exportée est elle-même chiffrée par la phrase secrète, donc les deux sont nécessaires ensemble, quel que soit le mode. borg key change-passphrase change la phrase, mais il demande l'ancienne pour le faire, il ne sert donc à rien après la perte. Il n'existe pas de récupération, et c'est le comportement attendu d'un chiffrement correct.

La commande de création s'appelle-t-elle borg init ou borg repo-create ?

Cela dépend de la ligne installée. La ligne 1.2, celle qu'Ubuntu 24.04 empaquette, crée avec borg init --encryption=MODE CHEMIN. La ligne 2.x renomme les commandes de dépôt et crée avec borg repo-create, le dépôt étant passé par l'option globale -r. Lancez borg --version puis borg init --help: si la commande est inconnue, vous êtes sur la nouvelle ligne, et sa liste de modes est différente elle aussi.