gday

Crates.iogday
lib.rsgday
version0.5.1
created_at2024-06-07 23:13:55.22987+00
updated_at2025-09-20 21:34:23.1657+00
descriptionCommand line tool to securely send files (without a relay or port forwarding).
homepage
repositoryhttps://github.com/manforowicz/gday/
max_upload_size
id1265310
size68,837
Marcin Anforowicz (manforowicz)

documentation

README

gday

Crates.io Version

Tool for trying to send files directly between computers, without a relay. Works through most NATs, but not all.

For a higher success rate, consider a tool that uses a relay server, such as magic-wormhole.

peer_1: gday send file.mp4 folder
Tell your mate to run "gday get 1.n5xn8.wvqsf".

peer_2: gday get 1.n5xn8.wvqsf
Transfer complete.

asciicast

Installation

  1. Download an executable from releases.
  2. Extract it (on Linux: tar xf <file>).
  3. Run it: ./gday

Alternatively:

cargo install gday

or

brew install manforowicz/tap/gday

Features

  • Files are sent directly, without a relay.

    • A server is only used to exchange socket addresses at the beginning. Then, a peer-to-peer connection is established with TCP Hole Punching. This may not work through some restrictive NATs. If that happens, enable IPv6, move to a different network, or use a tool with a relay server such as magic-wormhole or croc.

  • Automatically resumes interrupted transfers. Just gday send the same files, and the download will pick up where it left off.

    • This is implemented by having the receiver check whether the offered file name and last modified time exactly match a metadata file left by an interrupted transfer.

  • If a contact exchange server is down, just uses a different one from the default list. Or specify your own with --server.

  • Server connection encrypted with TLS and file transfer is over TCP that's end-to-end encrypted with ChaCha20Poly1305.

    • (not TLS for file transfer, because the rustls library doesn't support PSK which is needed for the certificate-less peer-to-peer connection).

  • Automatically tries both IPv4 and IPv6.

    • When IPv6 is available, connection almost always succeeds because IPv6 NATs are uncommon.

  • Authenticates your peer using SPAKE2 to derive an encryption key from a shared secret.

  • No unsafe Rust in this repository.

Usage

Usage: gday [OPTIONS] <COMMAND>

Commands:
  send  Send files and/or directories
  get   Receive files
  help  Print this message or the help of the given subcommand(s)

Options:
  -s, --server <SERVER>        Use a custom gday server with this domain name
  -p, --port <PORT>            Connect to a custom server port
  -u, --unencrypted            Connect to server with TCP instead of TLS
  -v, --verbosity <VERBOSITY>  Verbosity. (trace, debug, info, warn, error) [default: warn]
  -h, --help                   Print help
  -V, --version                Print version

Similar Projects

No relays Works beyond LAN Works through very strict NATs No port forwarding Encrypted Can resume interrupted transfers
gday ✅ ✅ ❌ ✅ ✅ ✅
magic-wormhole ❌ ✅ ✅ ✅ ✅ ✅
croc ❌ ✅ ✅ ✅ ✅ ✅
p2pcopy ✅ ✅ ❌ ✅ ❌ ❌
qft ✅ ✅ ❌ ✅ ❌ ❌
iwant ✅ ❌ ❌ ✅ ❌ ❌
zget ✅ ❌ ❌ ✅ ❌ ❌
sharedrop ❌ ✅ ✅ ✅ ✅ ❌
filepizza ❌ ✅ ✅ ✅ ✅ ❌
Personal SSH or HTTPS ✅ ✅ ✅ ❌ ✅ ❌
Personal FTP ✅ ✅ ✅ ❌ ❌ ❌
Dropbox, Google Drive, etc. ❌ ✅ ✅ ✅ ✅ ❌
Delivering a USB drive ✅ ✅ ✅ ✅ ✅ ❌

Technical Overview

  1. Peer A randomly generates a "room code" and "shared secret".

  2. Peer A randomly selects a gday server ID and connects to it over TLS.

  3. Peer A sends its room code, private IP addresses, and port numbers to the gday server.

  4. Peer A combines the server's ID, room code, and shared secret into a code of form "1.n5xn8.wvqsf" and tells it to Peer B, possibly via phone call or text message.

  5. Peer B also sends this room code and its private IP addresses and port numbers to the gday server.

  6. The gday server looks at the TCP connections with the clients to determine their public IP addresses and ports.

  7. The gday server sends both peers the public and private IP addresses and ports of the other peer.

  8. From the same private port that they used to connect to the server, each peer tries a few times to connect over TCP to both the private and public socket addresses of the other peer. This may fail on networks with strict NATs.

  9. Once any of the connection attempts succeeds, they use password-authenticated key exchange to derive a strong key from their shared secret, and use it to encrypt their TCP connection with chacha20poly1305.

  10. Peer A sends Peer B a list of offered files and their sizes.

  11. Peer B detects interrupted downloads by checking if any offered file's name and last modified time exactly matches metadata saved in a local temporary file leftover from the interrupted download.

  12. Peer B sends Peer A the file portions it would like to receive

  13. Peer A sends all the accepted files to Peer B, back-to-back.

Related

gday dependency graph

Commit count: 100

cargo fmt