Moving a file from one computer to another should be simple, and it rarely is. Email has size limits. Cloud storage needs an account on both sides and leaves a copy on someone else's server. scp needs SSH set up and a reachable address. A USB stick needs the two machines in the same room.
Tools like croc and Magic Wormhole showed a nicer way: the sender gets a short code, the receiver types it, and the files arrive encrypted. ptransfer is a small Go tool in that style. The sender gets a code like 4821-lamp-gold-lake, the receiver types it, and the files arrive encrypted end to end, through a relay or directly over the LAN when that is possible. You can run the relay yourself.
What it does
One code, no accounts. The code is a number plus three words from a 256-word list. The number only picks a room on the relay, and the relay sees a hash of it, not the number itself. The whole phrase is the password for a PAKE (password-authenticated key exchange). That means the relay cannot decrypt anything, and someone who tries to guess the code gets one try per session.
Encryption from vetted code. The PAKE is github.com/schollz/pake/v3, the one croc uses, on P-256, with the participant identities bound into the key. After the exchange, both sides confirm the key with an HMAC: a wrong code stops both sides before any file data moves. From there everything is AES-256-GCM with a key derived by HKDF. These pieces come from Go's standard crypto/hkdf, crypto/hmac and AES-GCM. Nothing is hand-rolled beyond the framing. Nonces are a direction tag plus a counter, so a modified, dropped, reordered, replayed or reflected frame fails authentication.
A relay that is a dumb pipe. Both sides say hello to the relay with the room hash. Once they are paired, the relay only copies bytes between them. It never sees file names, sizes or contents.
Direct connection on the LAN. The sender listens on a random port and advertises its private LAN addresses over the encrypted channel. If the receiver can connect and an encrypted ping/pong works, the data moves over that connection. Otherwise it stays on the relay.
Resume. Files are written as *.ptpart while they arrive. If a transfer is interrupted, the receiver reports how much of each partial file it has, with its SHA-256. The sender resumes only if that matches the start of its own file. Files that already arrived are skipped.
Verification before a file gets its name. The sender offers paths, sizes, modes and SHA-256 hashes. Data moves in 256 KiB chunks. Every finished file is checked against the sender's SHA-256 before it is renamed into place.
Safety on the receiving side. Paths are checked: no absolute paths, no .., no backslashes, no NUL bytes, and everything must stay inside the output directory. An existing file that differs is not replaced unless you pass -overwrite.
How to use it
The README lists prebuilt binaries for Linux, macOS and Windows (amd64 and arm64) on the GitHub releases page, each with a checksums.txt of SHA-256 sums. For example, on Linux amd64:
curl -LO https://github.com/AbdeldjalilChougui/ptransfer/releases/download/v0.1.0/ptransfer_0.1.0_linux_amd64.tar.gz
tar xzf ptransfer_0.1.0_linux_amd64.tar.gz
Or install from source with Go:
go install github.com/AbdeldjalilChougui/ptransfer/cmd/ptransfer@latest
A transfer needs three things: a relay, a sender and a receiver.
# somewhere both machines can reach (a VPS, or one of the two machines)
./ptransfer relay -addr 0.0.0.0:9009
# machine A
./ptransfer send -relay relay.example.org:9009 holiday-photos/ notes.pdf
# Code: 4821-lamp-gold-lake
# machine B
./ptransfer receive -relay relay.example.org:9009 -out ~/Downloads 4821-lamp-gold-lake
You can send several files and folders in one go. The PTRANSFER_RELAY environment variable sets the default relay, so you don't have to repeat -relay each time.
If a transfer is interrupted, by Ctrl-C or a network drop, run it again with a new code. Files that already arrived are skipped, and partial files resume where they stopped.
What happens during a transfer
It helps to know the order of the steps, because each one closes a specific hole:
- Both sides connect to the relay and join the same room, picked by the hash of the number in the code.
- They run the PAKE through the relay, with the whole code as the password.
- They confirm the key. With a wrong code, both sides stop here.
- The sender proposes a direct connection and sends its LAN addresses, already encrypted. The receiver dials and proves it holds the key with an encrypted ping.
- The sender sends the offer: paths, sizes, modes, SHA-256.
- The receiver accepts, and for each file gives a resume offset and the hash of the partial data it already has.
- Data chunks flow. The receiver writes
*.ptpart, verifies the SHA-256, then renames.
Things to know
The README is direct about the state of the project: early but working, meant for your own files.
- Not audited. The design is close to croc's, but the README says to treat it as a personal project.
- The code has about 37 bits of entropy. That is plenty against online guessing, since there is one guess per session and the sender notices failures. Don't reuse codes.
- Hashing first. The sender hashes every file before the offer, so very large folders take a moment to start.
- Direct mode is LAN only. The receiver must reach the sender's private address: same LAN, no client isolation. There is no NAT traversal (no STUN, no hole punching), and IPv6 link-local addresses are not advertised. With direct mode on, the sender listens on all interfaces on a random port during the transfer.
- The relay is open. It has no authentication, rate limiting or bandwidth caps. Put it behind a firewall or add limits before exposing it widely.
- Regular files only. Symlinks, empty directories, ownership and timestamps are not preserved. Permission bits are.
- One sender and one receiver per code. No multicast, no pausing.
What was tested. go test -race ./... covers code generation and normalisation, the secure channel (same key on both sides, wrong code failing on both sides with ErrWrongCode, flipped bits, dropped and reflected frames rejected, a malformed PAKE message not crashing the process) and the relay (pairing, a second sender for the same room refused, abandoned rooms freed, timeouts). The transfer tests run end to end through a local relay on 127.0.0.1: a folder with nested directories, an empty file and binary files arrives byte for byte with its file modes; the direct connection is used when reachable; a wrong code writes nothing; a tampering proxy that flips one bit mid-stream is detected with ErrTampered and no unverified file is put in place; resume sends only the rest of a partial file; and path traversal attempts are rejected.
Why I built it
The problem is the one in the intro: moving a file between your own machines, or to a friend, without accounts, cloud storage or setting up SSH. The tools that solved it well rely on a relay, and I wanted one I could run myself and a codebase small enough to read fully.
That second point is the other goal of the project. The README describes it as a compact, readable example of how a PAKE-based transfer tool is put together: code phrase, relay room, key exchange, key confirmation, encrypted framing, direct connection, resume. Each step is a small package (code, secure, relay, transfer) with its own tests, so you can read one piece at a time.
Get the code
The source, the protocol diagram and the tests are on GitHub: https://github.com/AbdeldjalilChougui/ptransfer. It's MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)