Magic Wormhole : transférer fichiers et secrets sans serveur

Magic Wormhole transfère des fichiers, dossiers ou textes entre deux machines sans compte, sans serveur à configurer et avec un chiffrement de bout en bout. Il suffit de partager un code généré (ex: 7-crossover-clockwork) par un canal quelconque (téléphone, chat, email) pour que l’autre partie reçoive les données de manière sécurisée. L’outil est idéal pour partager un mot de passe à un collègue, envoyer une clé SSH ou transférer un fichier confidentiel.

Ce que vous allez apprendre

Envoyer un fichier ou un dossier de manière sécurisée
Transférer du texte (mot de passe, token API, snippet de code)
Partager une clé SSH publique avec wormhole ssh
Utiliser Tor pour plus d’anonymat
Connaître les limites et quand préférer d’autres outils

Magic Wormhole dans l’écosystème des transferts

Avant de choisir un outil de transfert, il est utile de comprendre ce qui différencie Magic Wormhole des autres solutions. Chaque outil répond à un besoin spécifique : scp et rsync nécessitent un accès SSH préalable, les services cloud demandent un compte, et PGP exige une gestion de clés complexe.

Magic Wormhole se distingue par sa simplicité : aucune configuration préalable n’est requise. Les deux parties installent l’outil, l’une génère un code, l’autre le saisit, et le transfert s’effectue.

Solution	Chiffrement	Besoin de compte	Taille max	Cas d’usage
Magic Wormhole	✅ E2E	❌ Non	Illimité	Transfert ponctuel, secrets, clés SSH
scp	✅ SSH	❌ Non (mais clés)	Illimité	Transfert serveur à serveur
rsync	✅ SSH	❌ Non (mais clés)	Illimité	Sauvegardes, synchronisation
SFTP	✅ SSH	❌ Non (mais clés)	Illimité	Transfert interactif
Email + PGP	✅ E2E	⚠️ Clés PGP	Limité	Messages, petits fichiers
WeTransfer	⚠️ TLS	✅ Optionnel	2 Go	Partage simple
Dropbox/Drive	⚠️ TLS	✅ Oui	Variable	Stockage + partage

En résumé : si vous devez transférer un fichier à quelqu’un qui n’a pas accès à votre serveur SSH et que vous ne voulez pas passer par un service cloud, Magic Wormhole est la solution idéale.

Pourquoi choisir Magic Wormhole ?

Aucune configuration : pas de clé SSH à échanger au préalable
Aucun compte : pas d’inscription, pas de mot de passe à retenir
Chiffrement E2E : les serveurs relais ne voient que des données chiffrées
Code simple : facile à dicter au téléphone (ex: 7-crossover-clockwork)
Usage unique : chaque code ne peut servir qu’une seule fois

Installation

# Installation isolée avec pipx (recommandé)
pipx install magic-wormhole

# Ou avec pip dans un environnement utilisateur
pip install --user magic-wormhole

# Vérifier l'installation
wormhole --version
# magic-wormhole 0.22.0

# Disponible dans les dépôts officiels (peut être une version plus ancienne)
sudo apt install magic-wormhole

# Vérifier
wormhole --version

# Via Homebrew
brew install magic-wormhole

# Vérifier
wormhole --version

# Via Chocolatey
choco install magic-wormhole

# Vérifier
wormhole --version

Comprendre le fonctionnement

Magic Wormhole utilise PAKE (Password-Authenticated Key Exchange) avec l’algorithme SPAKE2 pour établir une clé de chiffrement partagée à partir d’un code court. Voici le processus simplifié :

L’émetteur génère un code : wormhole send fichier.txt produit un code comme 7-crossover-clockwork
Le code est transmis par un canal quelconque (téléphone, chat, en personne)
Le récepteur entre le code : wormhole receive 7-crossover-clockwork
PAKE établit la clé : les deux parties dérivent une clé de chiffrement commune sans jamais la transmettre
Connexion P2P ou relais : si possible, connexion directe entre les machines. Sinon, passage par un serveur relais (données toujours chiffrées)
Transfert chiffré : les données transitent chiffrées de bout en bout

Points de sécurité importants :

Code à usage unique : chaque code ne peut servir qu’une seule fois
Attaque MITM : un attaquant qui essaie de deviner le code n’a qu’une chance (1/65536 avec le code par défaut de 16 bits)
Serveurs relais : ne voient que des données chiffrées, impossibles à déchiffrer sans le code

Envoyer et recevoir des fichiers

Envoyer un fichier

wormhole send /chemin/vers/fichier.txt

Sortie attendue :

Sending 36 Bytes file named 'fichier.txt'
Wormhole code is: 40-pegasus-burbank
█▀▀▀▀▀▀▀██▀▀▀█▀█▀██▀▀▀█▀▀▀▀▀▀▀█
█ █▀▀▀█ █▀▀▀▀█ ▄▄▄█████ █▀▀▀█ █
...
On the other computer, please run:

wormhole receive 40-pegasus-burbank

Par défaut, un QR code ASCII est affiché. Le destinataire peut le scanner avec une application compatible ou entrer le code manuellement.

Recevoir un fichier

wormhole receive 40-pegasus-burbank

Sortie attendue :

Receiving file (36 bytes) into: fichier.txt
ok? (y/n): y
Receiving (->tcp:192.168.1.10:58986)..
100%|===========================| 36/36 [00:00<00:00, 120KB/s]
Received file written to fichier.txt

Envoyer un dossier complet

wormhole send /chemin/vers/dossier/

Le dossier est automatiquement compressé en archive zip avant l’envoi.

Personnaliser le transfert avec les options

Magic Wormhole propose plusieurs options pour adapter le transfert à vos besoins. Par exemple, si le QR code ASCII encombre votre terminal, désactivez-le avec --no-qr. Si vous souhaitez un code facile à retenir, créez-le vous-même avec --code. Pour les transferts sensibles, l’option --verify affiche une chaîne de vérification que les deux parties peuvent comparer oralement.

Option	Description	Exemple
`--no-qr`	Désactiver le QR code ASCII	`wormhole send --no-qr fichier.txt`
`--code CODE`	Utiliser un code personnalisé	`wormhole send --code mon-code fichier.txt`
`--verify`	Afficher une chaîne de vérification	`wormhole send --verify fichier.txt`
`--code-length N`	Changer la longueur du code (mots)	`wormhole send --code-length 4 fichier.txt`
`--accept-file`	Accepter sans confirmation (receive)	`wormhole receive --accept-file CODE`
`-o FILE`	Renommer le fichier reçu	`wormhole receive -o autre-nom.txt CODE`

Alias pratiques

Magic Wormhole propose des alias courts :

# wormhole tx = wormhole send
wormhole tx fichier.txt

# wormhole rx = wormhole receive
wormhole rx 7-crossover-clockwork

Transférer du texte

Pour partager un mot de passe, un token API ou un snippet de code :

wormhole send --text "SuperSecretPassword123"

Sortie attendue :

Sending text message (22 Bytes)
Wormhole code is: 87-breakaway-clamshell
On the other computer, please run:

wormhole receive 87-breakaway-clamshell

Côté récepteur :

wormhole receive 87-breakaway-clamshell

Le texte s’affiche directement dans le terminal sans créer de fichier.

Recevoir uniquement du texte

Pour refuser les transferts de fichiers et n’accepter que du texte :

wormhole receive --only-text CODE

Cela protège contre un envoi de fichier malveillant si vous attendez uniquement du texte.

Partager une clé SSH

Magic Wormhole propose des sous-commandes dédiées pour ajouter une clé SSH publique à un fichier authorized_keys distant.

Scénario : ajouter un utilisateur à votre serveur

Sur le serveur, lancez l’invitation :

wormhole ssh invite

Sortie :

Now tell the other user to run:

wormhole ssh accept 3-tambourine-repay

Communiquez le code à l’utilisateur (téléphone, chat, etc.)

L’utilisateur exécute sur sa machine :

wormhole ssh accept 3-tambourine-repay

Si plusieurs clés publiques existent, il devra choisir :

Multiple public-keys found:
  0: id_ed25519.pub
  1: id_rsa.pub
Send which one?: 0

La clé est ajoutée automatiquement à ~/.ssh/authorized_keys sur le serveur

Options de la commande SSH

La commande wormhole ssh accepte des options pour contrôler quel utilisateur reçoit la clé et quelle clé publique est envoyée. Par défaut, la clé est ajoutée à l’utilisateur courant et l’émetteur envoie sa clé par défaut (~/.ssh/id_*.pub). Ces options permettent de personnaliser ce comportement.

Option	Description	Exemple
`-u USER`	Ajouter à un autre utilisateur	`wormhole ssh invite -u deploy`
`-F FILE`	Spécifier la clé à envoyer	`wormhole ssh accept -F ~/.ssh/special.pub CODE`
`-y`	Accepter sans confirmation	`wormhole ssh accept -y CODE`

Utiliser Tor pour plus d’anonymat

Dans certaines situations, vous ne voulez pas que votre adresse IP soit visible par le serveur relais ou par le destinataire. C’est le cas pour les lanceurs d’alerte, les journalistes, ou simplement pour renforcer la confidentialité d’un échange.

Magic Wormhole supporte nativement le réseau Tor, qui fait transiter vos connexions à travers plusieurs nœuds pour masquer votre origine. Trois modes sont disponibles :

--tor : utilise un daemon Tor déjà actif sur votre machine (port 9050 par défaut)
--launch-tor : démarre une instance Tor temporaire le temps du transfert
--tor-control-port : spécifie manuellement l’adresse du contrôleur Tor

# Utiliser un daemon Tor existant (le plus courant)
wormhole send --tor fichier.txt
wormhole receive --tor CODE

# Lancer une instance Tor temporaire (si Tor n'est pas démarré)
wormhole send --launch-tor fichier.txt

# Spécifier le port de contrôle Tor (configuration avancée)
wormhole send --tor-control-port tcp:localhost:9051 fichier.txt

Important : les deux parties doivent utiliser l’option --tor pour que l’anonymat soit effectif. Si seul l’émetteur utilise Tor, le récepteur verra son adresse IP normale.

Variables d’environnement

Si vous utilisez Magic Wormhole régulièrement avec les mêmes options, vous pouvez les définir comme variables d’environnement. Cela évite de répéter --no-qr à chaque commande ou de toujours ajouter --accept-file dans vos scripts.

Ces variables sont particulièrement utiles dans deux cas :

Automatisation : dans un script qui reçoit automatiquement des fichiers, définissez WORMHOLE_ACCEPT_FILE=1 pour éviter l’invite de confirmation
Serveurs relais privés : si votre entreprise héberge ses propres serveurs Wormhole, configurez WORMHOLE_RELAY_URL et WORMHOLE_TRANSIT_HELPER une fois pour toutes

Variable	Équivalent	Usage
`WORMHOLE_RELAY_URL`	`--relay-url`	URL du serveur mailbox (coordination des codes)
`WORMHOLE_TRANSIT_HELPER`	`--transit-helper`	URL du serveur relais transit (transfert des données)
`WORMHOLE_ACCEPT_FILE`	`--accept-file`	Accepter sans confirmation (`1` ou `true`)
`WORMHOLE_QR`	`--qr` / `--no-qr`	Activer/désactiver le QR code (`0` ou `1`)

Exemple pratique : désactiver le QR code et accepter automatiquement les fichiers dans votre .bashrc ou .zshrc :

# Ajouter à ~/.bashrc ou ~/.zshrc
export WORMHOLE_QR=0          # Désactiver le QR code par défaut
export WORMHOLE_ACCEPT_FILE=1 # Accepter automatiquement les fichiers

# Ensuite, les commandes sont plus simples
wormhole receive CODE  # Pas de QR, pas de confirmation

Bonnes pratiques de sécurité

Transmettre le code par un canal différent : si le fichier est sensible, ne transmettez pas le code par le même canal (ex: ne pas envoyer fichier + code par Slack)
Utiliser --verify pour les transferts très sensibles : les deux parties voient une chaîne de vérification à comparer oralement
Préférer des codes plus longs pour les données critiques : --code-length 4 génère des codes à 4 mots au lieu de 2
Ne pas réutiliser les codes : chaque code est à usage unique et expire après utilisation
Vérifier la source : avant de recevoir un fichier, assurez-vous que l’émetteur est bien qui il prétend être

Dépannage

Magic Wormhole est généralement fiable, mais certains problèmes peuvent survenir, notamment liés à la saisie du code ou à la configuration réseau.

Problèmes courants et solutions

Voici les erreurs les plus fréquentes et comment les résoudre :

Problème	Cause probable	Solution
`Crowded` ou `Scary` error	Quelqu’un d’autre a tenté d’utiliser le code (attaque ou collision)	Générer un nouveau code avec `wormhole send`
Connexion lente	Les deux machines sont derrière NAT, le relais est utilisé	Comportement normal, la vitesse dépend du serveur relais
`ReactorNotRunning`	Le processus a été interrompu (Ctrl+C, perte de connexion)	Réessayer la commande depuis le début
Fichier non trouvé côté receive	Code mal saisi (espace, tiret manquant)	Vérifier le code caractère par caractère
`Timeout`	Le récepteur n’a pas lancé la commande à temps	Relancer `wormhole send` et transmettre le nouveau code

Conseil : si vous rencontrez une erreur Crowded ou Scary, cela peut indiquer qu’un attaquant tente de deviner votre code. Générez un nouveau code et utilisez --code-length 4 pour plus de sécurité.

Vérifier la connectivité

Si un transfert échoue ou est anormalement lent, vous pouvez activer le mode de diagnostic. L’option --dump-timing génère un fichier JSON contenant toutes les étapes de connexion : résolution DNS, établissement de la session PAKE, tentative de connexion directe, et utilisation éventuelle du relais.

# Mode verbeux pour le debug
wormhole --dump-timing timing.json send fichier.txt

Après le transfert (réussi ou non), ouvrez timing.json pour identifier l’étape qui a échoué ou pris du temps. Les informations clés sont :

direct_connection : indique si une connexion P2P a été établie (plus rapide)
relay_connection : indique si le relais a été utilisé (plus lent mais fonctionne derrière NAT)
total_time : durée totale du transfert

Limites de Magic Wormhole

Magic Wormhole est conçu pour des transferts ponctuels et interactifs. Il n’est pas adapté à tous les scénarios. Voici ses principales limites :

Pas de reprise de transfert : si le transfert s’interrompt, il faut recommencer depuis le début
Les deux parties doivent être en ligne : impossible de déposer un fichier pour qu’il soit récupéré plus tard
Pas d’historique : aucun log des transferts passés côté serveur (c’est aussi un avantage pour la confidentialité)
Un seul destinataire : chaque code ne peut être utilisé qu’une seule fois par une seule personne

Quand éviter Magic Wormhole : pour des sauvegardes automatisées, des transferts réguliers entre serveurs, ou des fichiers de plusieurs Go sur une connexion instable, préférez rsync (reprise possible) ou scp (intégré à SSH).

À retenir

Magic Wormhole transfère fichiers, dossiers et textes avec chiffrement E2E
Aucun compte nécessaire : juste un code à partager
Code à usage unique : un code = un transfert
wormhole send génère le code, wormhole receive le consomme
wormhole ssh invite/accept simplifie le partage de clés SSH
--text pour transférer du texte sans fichier
--tor pour plus d’anonymat via le réseau Tor
Pour les transferts réguliers, préférer rsync ou scp

Prochaines étapes

Transférer avec scp Copier des fichiers via SSH

Synchroniser avec rsync Sauvegardes et transferts delta

Tunnels SSH Sécuriser les connexions réseau

Gestion des secrets Stocker et distribuer les secrets

Ressources

Projet GitHub : github.com/magic-wormhole/magic-wormhole
Documentation officielle : magic-wormhole.readthedocs.io
Applications mobiles : Wormhole pour Android
Interface graphique : Warp pour Gnome