Magic Wormhole: A Deep Dive into Secure, Simple File Transfer

Core Architecture

The Protocol Stack

Magic Wormhole operates on a multi-layered architecture:

1. The Mailbox Server (Rendezvous Server)

  • A WebSocket-based relay that facilitates initial connection establishment
  • Default public server: ws://relay.magic-wormhole.io:4000/v1
  • Stores encrypted messages temporarily
  • Never sees plaintext data
  • Can be self-hosted for increased reliability

2. The Transit Relay

  • Handles actual data transfer when direct peer-to-peer connections fail
  • Used when both peers are behind NAT
  • Default server: tcp:transit.magic-wormhole.io:4001
  • All data passing through is end-to-end encrypted

3. Connection Negotiation The tool attempts multiple connection strategies in parallel:

  • Direct peer-to-peer connection (when peers are on same LAN)
  • Direct connection over the internet (when one peer has public IP)
  • Relayed connection via Transit Relay (as fallback)

Cryptographic Foundation: PAKE and SPAKE2

The security heart of Magic Wormhole is Password-Authenticated Key Exchange (PAKE), specifically the SPAKE2 algorithm developed by Abdalla and Pointcheval.

How PAKE Works:

  1. Uses a short, low-entropy password (the wormhole code) to establish a strong, high-entropy shared key
  2. Trades interaction for offline attack resistance
  3. An attacker must perform a man-in-the-middle attack during the initial connection AND correctly guess the code
  4. With default 16-bit codes, attackers have only a 1-in-65,536 chance per attempt
  5. Each code is single-use only, limiting attack opportunities

Encryption Details:

  • Session keys derived from PAKE phase
  • Data encrypted using NaCl/libsodium “secretbox”
  • 256-bit shared secrets after successful key exchange
  • All file data encrypted end-to-end before transmission

The Wormhole Code System

Codes follow a structured format: [number]-[word]-[word]

  • Example: 7-guitarist-revenge or 3-passenger-watchword
  • Nameplate (number): Identifies the specific mailbox (typically 1-2 digits)
  • Words: Phonetically-distinct wordlist for clarity
  • Tab-completion on receiver side minimizes typing errors
  • Default 16-bit entropy, configurable with --code-length

Installation and Platform Support

Python Implementation (Original)

pip install magic-wormhole

Requirements:

  • Python 3.10+ (tested up to 3.12)
  • Dependencies: SPAKE2, pynacl, Twisted, autobahn
  • Packaged in many OS repositories (Debian, Ubuntu, Arch, etc.)

Alternative Implementations

Rust Implementation:

cargo install magic-wormhole
  • More performant in many scenarios
  • Better cross-platform binary distribution
  • Available at: magic-wormhole/magic-wormhole.rs

Go Implementation (wormhole-william):

go install github.com/psanford/wormhole-william@latest
  • Excellent performance characteristics
  • Single binary distribution
  • Compatible with Python implementation
  • Available prebuilt binaries

GUI Implementations:

  • Rymdport: Cross-platform GUI (formerly wormhole-gui)
  • GNOME Warp: Native GNOME integration
  • iyox Wormhole: Android client
  • Wormhole File Transfer: QR code feature for mobile transfers

All implementations maintain protocol compatibility, allowing Python clients to communicate with Rust or Go clients seamlessly.

Use Cases

1. Ad-Hoc File Transfer

The primary and most common use case—transferring files when you’re already in communication:

  • Phone conversations: “Let me send you that file” → generate code → speak it
  • Video calls: Send code via chat while talking
  • In-person: Show code on screen or speak it
  • IRC/Slack: Paste code in chat for direct transfer

2. Password and Credential Delivery

More secure than email or messaging apps:

wormhole send --text "username:password123"

Perfect for:

  • Delivering initial passwords to new users
  • Sharing API keys or tokens
  • Distributing SSH keys or certificates

3. Application Integration

Tahoe-LAFS Integration:

  • Uses wormhole protocol for user invitations
  • Exchanges secret connection details via secure mailbox
  • No server-side password storage required

Magic Folder:

  • Utilizes wormhole for folder sharing invitations
  • Grants access to synchronized folders
  • Exchanges capability strings securely

Potential Use Cases for Developers:

  • Client provisioning without web portals
  • Peer-to-peer messaging setup
  • Distributed system node initialization
  • Mobile app pairing (QR codes + wormhole codes)

4. Directory Transfer

Send entire directory structures:

wormhole send my-project/

Note: Original Python implementation requires zipping first; Rust and Go implementations handle directories natively.

5. Cross-Platform Transfers

Works seamlessly between:

  • Windows ↔ Linux
  • macOS ↔ Windows
  • Linux ↔ Linux
  • Mobile (Android) ↔ Desktop

6. Air-Gapped Networks (with Tor)

Enhanced privacy mode:

wormhole --tor send filename
  • Routes traffic through Tor network
  • Increases anonymity
  • Useful for sensitive environments
  • Supports .onion relay servers

Key Benefits

1. Zero Configuration

  • No SSH keys to generate or exchange
  • No port forwarding required
  • No firewall configuration needed
  • No user accounts or registration
  • No shared passwords to maintain

2. Strong Security

  • End-to-end encryption
  • Forward secrecy (codes are single-use)
  • Resistant to offline attacks
  • Minimal trust required in relay servers
  • Open-source and auditable

3. Human-Friendly

  • Short, pronounceable codes
  • Tab completion reduces typing
  • Clear error messages
  • Works across NAT boundaries
  • Automatic relay fallback

4. Lightweight

  • Small download size
  • Minimal dependencies (especially Go/Rust versions)
  • Low resource consumption
  • Works on Raspberry Pi and similar devices

5. Cross-Platform

  • Available for all major operating systems
  • Protocol compatibility between implementations
  • Mobile support (Android)
  • Can be embedded in other applications

6. Privacy-Preserving

  • No permanent account creation
  • No tracking or analytics
  • Can be used with Tor
  • Self-hostable infrastructure

Performance Benchmarks

Performance varies significantly based on implementation, network conditions, and hardware:

Observed Transfer Speeds

Python Implementation:

  • LAN transfers: 11.6 MB/s (reported in issue #276)
  • Internet via public relay: 40-50 MB/s typical
  • Custom relay: 50-70 MB/s achievable
  • Small file example: 3.75 MB transferred at 1.81 MB/s

Rust Implementation:

  • Performance issues noted on M1 Mac (bottleneck under investigation)
  • Other platforms: comparable to Python or better
  • Generally more CPU-efficient than Python

Go Implementation (wormhole-william):

  • Full gigabit speeds achievable on good networks
  • Excellent CPU efficiency
  • Consistent performance across platforms

Bottlenecks and Limitations

Common Issues:

  1. Public Relay Congestion: The free public relay can become saturated
  2. NAT Traversal Overhead: Relay routing slower than direct P2P
  3. Single-threaded Transfers: No parallel stream support
  4. CPU Encryption Overhead: On low-power devices (Raspberry Pi ~7s startup)
  5. Windows Performance: Python version historically slower on Windows

Comparison with Other Tools:

  • SSH/SCP: ~40 MB/s (single-threaded limitation)
  • Magic Wormhole (public relay): 40-50 MB/s
  • Magic Wormhole (private relay): 50-100+ MB/s
  • Direct iperf: 750+ MB/s (baseline network capability)

Performance Optimization Strategies

  1. Run Your Own Relay:
pip3 install magic-wormhole-transit-relay
twistd3 transitrelay

Then use:

wormhole send --transit-helper=tcp:YOUR_IP:4001 filename
  1. Use Go or Rust Implementations:
  • Lower overhead
  • Better multi-platform performance
  • Faster startup times
  1. Optimize Network Path:
  • Same LAN: Direct P2P (fastest)
  • Different networks with one public IP: Still direct
  • Both behind NAT: Requires relay (slower)
  1. Hardware Considerations:
  • Raspberry Pi: Expect ~19s startup (Python), ~7s with optimizations
  • Modern x86/ARM: Minimal CPU overhead
  • Network bandwidth usually the limiting factor

Advanced Features

Custom Code Generation

wormhole send --code-length=4 file.txt  # 4-word code (more entropy)

Text Snippets

echo "secret message" | wormhole send --text

Appid (Application Identifier)

Different appids create separate namespaces:

wormhole --appid=custom.app send file

Useful for:

  • Application-specific transfers
  • Isolated communication channels
  • Custom protocol implementations

Offline Codes

Both sides can prepare codes offline, then connect later when online.

Verifier Codes

Additional verification for paranoid users:

  • Compare verifier strings out-of-band
  • Confirms no MITM attack occurred
  • Optional but recommended for sensitive transfers

API Integration

from wormhole import wormhole

w = wormhole.create(appid, relay_url, reactor)
code = yield w.get_code()
# Display code to user
yield w.send(data)

Comparison with Alternatives

vs. Croc

Croc (written in Go) is inspired by Magic Wormhole but uses a different protocol:

Advantages of Croc:

  • Resume support for interrupted transfers
  • IPv6 support
  • Multiple file transfers
  • Folder sending without zipping
  • Can set custom code phrases
  • Self-relay support built-in

Disadvantages of Croc:

  • Not compatible with Magic Wormhole protocol
  • Known security concerns (fixed but historical)
  • Fragments the user base
  • Different cryptographic approach (not SPAKE2)

Verdict: Croc offers more features but Magic Wormhole has better-vetted security and wider protocol support.

vs. SCP/SFTP

Magic Wormhole advantages:

  • No SSH key setup
  • Works across NAT
  • No hostname/IP needed
  • User-friendly codes

SCP/SFTP advantages:

  • Established, trusted protocol
  • Better performance (when configured)
  • Scriptable with known infrastructure
  • Standard on Unix systems

vs. Dropbox/Google Drive

Magic Wormhole advantages:

  • No account required
  • Direct peer-to-peer (when possible)
  • End-to-end encrypted
  • No file size limits (server-dependent)
  • Ephemeral (no cloud storage)

Cloud services advantages:

  • Persistent storage
  • Multiple recipients
  • Web interface
  • Sync capabilities
  • Mobile apps

vs. WebRTC (ShareDrop, FilePizza)

Magic Wormhole advantages:

  • Command-line interface
  • Scriptable
  • Library for integration
  • Works without browser

WebRTC advantages:

  • No installation needed
  • Visual interface
  • QR code support
  • Mobile-friendly

Security Considerations

Trust Model

What you must trust:

  1. The cryptographic implementation (SPAKE2, NaCl)
  2. Your communication channel for the code (phone, in-person, etc.)
  3. The software implementation itself

What you don’t need to trust:

  1. The Mailbox server (sees only encrypted data)
  2. The Transit relay (also sees only encrypted data)
  3. Network infrastructure (encryption protects in-transit)

Attack Scenarios

Man-in-the-Middle:

  • Attacker must be active during initial connection
  • Must correctly guess code in single attempt (1/65,536 chance)
  • Failed attempts generate error messages
  • Multiple failed attempts very noticeable

Eavesdropping:

  • All data encrypted with strong keys
  • Even if relay is compromised, data remains secure
  • Forward secrecy: past sessions can’t be decrypted

Code Interception:

  • If attacker learns code and acts immediately, attack possible
  • Mitigation: Use secure channels for code transmission
  • Use verifier codes for high-security scenarios
  • Codes expire after use or timeout (~3 minutes in older versions)

Known Vulnerabilities

As noted by Jeff Geerling: “There are Known Vulnerabilities, so I wouldn’t think about sending over state secrets.”

Recommendations:

  • Don’t use for classified information
  • Verify verifier codes for sensitive transfers
  • Use Tor mode for anonymity requirements
  • Self-host relays for corporate use
  • Keep software updated

Developer Information

Library API

Twisted (Asynchronous):

from twisted.internet import reactor
from wormhole import wormhole

def send_file(filename):
    w = wormhole.create(appid, relay_url, reactor)
    code = yield w.get_code()
    print(f"Code: {code}")
    yield w.send(open(filename, 'rb').read())
    yield w.close()

Future Blocking API: The project plans to add synchronous/blocking support for easier integration.

Running Your Own Infrastructure

Mailbox Server:

pip install magic-wormhole-mailbox-server
wormhole-mailbox-server --port=4000

Transit Relay:

pip install magic-wormhole-transit-relay
twistd3 transitrelay --port=4001

Docker Support: Both can be easily containerized for deployment.

Protocol Extensions

The core protocol is extensible:

  • Dilation: Future feature for long-lived channels
  • Custom Application Protocols: Build on wormhole foundation
  • Multi-message Support: Send multiple messages over one wormhole

The Ecosystem

Official Projects

  • magic-wormhole - Original Python implementation
  • magic-wormhole.rs - Rust implementation
  • magic-wormhole-mailbox-server - Server component
  • magic-wormhole-transit-relay - Relay component

Community Projects

  • wormhole-william - Go implementation (psanford)
  • Rymdport - Cross-platform GUI
  • GNOME Warp - GNOME desktop integration
  • croc - Inspired alternative with different protocol
  • Various mobile apps and web interfaces

Package Availability

Magic Wormhole is available in:

  • Debian/Ubuntu repositories
  • Arch Linux (AUR)
  • Fedora/RHEL repositories
  • Homebrew (macOS)
  • Chocolatey (Windows)
  • Snap Store
  • Flathub

Real-World Adoption

Magic Wormhole has been adopted by various projects and organizations:

Academic Use:

  • Featured in cryptography courses
  • Used for secure research data exchange
  • Example of practical PAKE implementation

Corporate Use:

  • IT departments for secure credential distribution
  • DevOps teams for quick file sharing
  • Remote support scenarios

Open Source Community:

  • Integrated into Tahoe-LAFS distributed storage
  • Used by Magic Folder for secure sharing
  • Referenced in security best practices

Uniswap Assessment: While not directly related to Magic Wormhole, the document mentions other secure transfer protocols. The Wormhole blockchain bridge (different project) was rated #1 by Uniswap’s Bridge Assessment Committee—showing the “wormhole” concept has broad appeal in secure communication.

Future Directions

Planned Improvements

Dilation:

  • Long-lived wormhole connections
  • Replace separate Transit class
  • Multiple bi-directional streams
  • Better for interactive applications

Enhanced NAT Traversal:

  • Improved hole-punching techniques
  • STUN/TURN integration
  • Better direct connection success rates

Performance Optimization:

  • Multi-threaded transfers
  • Parallel stream support
  • Better buffering strategies
  • Reduced protocol overhead

Mobile Experience:

  • Native iOS apps
  • Improved Android support
  • QR code integration
  • Camera-based code scanning

Community Wishlist

  • Resume support (being worked on)
  • Better directory handling (solved in Rust/Go)
  • GUI improvements
  • WebAssembly support
  • Browser plugin
  • Integration with more platforms

Conclusion

Magic Wormhole represents a rare achievement in security software: it makes the secure option also the easiest option. By leveraging PAKE cryptography and a clever relay architecture, it eliminates the friction that typically accompanies secure file transfer.

Key Takeaways:

  • Simple UX: Just two commands and a short code
  • Strong security: End-to-end encryption with forward secrecy
  • Zero setup: No configuration, keys, or accounts
  • Cross-platform: Works everywhere, interoperably
  • Open source: Auditable and trustworthy
  • Extensible: Library for custom applications

When to Use Magic Wormhole:

  • Ad-hoc file transfers during calls/chats
  • Secure credential delivery
  • Quick file sharing without cloud services
  • Cross-platform transfers
  • NAT-traversal scenarios
  • Application key exchange

When Not to Use:

  • Classified/highly sensitive data (use verified secure channels)
  • Large-scale file distribution (use proper CDN)
  • Persistent file sharing (use cloud storage)
  • Resumable transfers of huge files (consider croc or BitTorrent)

For most everyday file transfer needs, Magic Wormhole hits the sweet spot of security, simplicity, and practicality. It’s a tool that deserves a place in every developer’s and power user’s toolkit.

Resources

Acknowledgments

Created by Brian Warner, with contributions from the open-source community. The project demonstrates the power of good cryptographic engineering combined with thoughtful UX design.

Last Updated: November 2024
Based on Magic Wormhole 0.21.x and ecosystem projects as of 2024