Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved cargo toml descriptions #4

Merged
merged 1 commit into from
Jun 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
# GitHub workflow for automatically
# testing code on push to main
# and pull requests.

name: Cargo Build & Test

on:
push:
branches:
- main
pull_request:
types: [synchronize]

env:
CARGO_TERM_COLOR: always
Expand Down
19 changes: 19 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Contributing

## Feature requests and bug reports

To request features or report bugs, submit an
[issue](https://github.com/manforowicz/gday/issues)
on this GitHub repository.
Please try to add as much details as you can.

Feel free to share your experiences using gday, by submitting issues.

## Contributing code

Learn how to contribute by following GitHub's
[Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)
guide.

Verify your code passes tests by running the cargo commands listed
in the `pre-push` file.
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2024 Marcin Anforowicz

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
109 changes: 48 additions & 61 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,61 @@
# Gday Project
# gday

**WORK IN PROGRESS - THIS PROJECT IS NOT READY YET**
**Note: this project is still in early-development, so expect breaking changes.**

Send files directly to anyone.

## Example
A command line tool for sending files.

<pre>
<b style="color:lime;">peer_1:</b> gday send msg.txt image.jpg
<i>*Asks for confirmation*</i>
<i>&lt;Asks for confirmation&gt;</i>
Tell your mate to run "gday receive <b>1.188T.W3H.E</b>".
<b>Transfer complete.</b>
</pre>

<pre>
<b style="color:lime;">peer_2:</b> gday receive <b>1.188T.W3H.E</b>
<i>*Asks for confirmation*</i>
<i>&lt;Asks for confirmation&gt;</i>
<b>Transfer complete.</b>
</pre>

[![asciicast](https://asciinema.org/a/662397.svg)](https://asciinema.org/a/662397)

## Features
## Installation

- Uses [TCP Hole Punching](https://bford.info/pub/net/p2pnat/)
with the help of a [gday_contact_exchange_server](/gday_contact_exchange_server/)
to establish a direct peer-to-peer connection,
even between different private networks.
Note: This may not work on networks with very restrictive [NATs](https://en.wikipedia.org/wiki/Network_address_translation).
### Executable

- Since the transfer is always direct,
you can send huge amounts of data without affecting any relay servers.
1. Go to [releases](https://github.com/manforowicz/gday/releases)
and download the correct file for your platform.
2. Extract the executable
(on Linux, try: `tar xf <file>`).
3. Run the executable: `./<path to executable>/gday`

- Doesn't require port forwarding.
### Cargo

- Automatically tries both IPv4 and IPv6.
If you have `cargo`, run `cargo install gday`.

- Uses password authenticated key exchange ([SPAKE2](https://datatracker.ietf.org/doc/rfc9382/))
to derive a strong encryption key from a weak shared password.
### Brew

If you have `brew`, run `brew install manforowicz/tap/gday`.

- Authenticated encryption using [ChaCha20Poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305).
## Features
- File transfer is always direct, without relays.
A server is only used to help the devices find each other.
- Doesn't require port forwarding.
- Files encrypted with streaming
[ChaCha20Poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305).
- Automatically tries both IPv4 and IPv6.
- Immune to malicious servers trying to impersonate your peer.
Uses password authenticated key exchange
([SPAKE2](https://datatracker.ietf.org/doc/rfc9382/))
to derive a strong encryption key from a weak shared password.

Want to send files easily, securely, and directly, without a relay or port forwarding?
Then go to the [gday page](gday/README.md).
## How it works
Uses [TCP Hole Punching](https://bford.info/pub/net/p2pnat/)
with the help of a server
to establish a direct peer-to-peer connection,
even between different private networks.
Note: This may not work on networks with very restrictive
[NATs](https://en.wikipedia.org/wiki/Network_address_translation).

## Usage
```
Expand Down Expand Up @@ -70,13 +83,12 @@ I'm very grateful to their creators and contributors.
<table>
<tr>
<th></th>
<th>Always direct (no relays)</th>
<th>Always direct (no relay)</th>
<th>Can work beyond LAN, through most <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
<th>Works through restrictive <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
<th>Works without port forwarding or opening</th>
<th>Works through very strict <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
<th>No port forwarding</th>
<th>Encrypted</th>
<th>Can resume interrupted transfers</th>
<th>Free & open source</th>
</tr>
<tr>
<td><strong><a href="https://github.com/manforowicz/gday">gday</a></strong></td>
Expand All @@ -86,7 +98,6 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/magic-wormhole/magic-wormhole">magic-wormhole</a></td>
Expand All @@ -96,7 +107,6 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/schollz/croc">croc</a></td>
Expand All @@ -106,27 +116,24 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/nirvik/iWant">iwant</a></td>
<tr>
<td><a href="https://github.com/psantosl/p2pcopy">p2pcopy</a></td>
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/psantosl/p2pcopy">p2pcopy</a></td>
<td>✅</td>
<td><a href="https://github.com/nirvik/iWant">iwant</a></td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/nils-werner/zget">zget</a></td>
Expand All @@ -136,7 +143,6 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/cowbell/sharedrop">sharedrop</a></td>
Expand All @@ -146,7 +152,6 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/kern/filepizza">filepizza</a></td>
Expand All @@ -156,37 +161,24 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td><a href="https://github.com/zerotier/toss">toss</a></td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>Personal <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> or <a href="https://en.wikipedia.org/wiki/HTTPS">HTTPS</a> server</td>
<td>Personal <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> or <a href="https://en.wikipedia.org/wiki/HTTPS">HTTPS</a></td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>✅</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>Personal <a href="https://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a> server</td>
<td>Personal <a href="https://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a></td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>Dropbox, Google Drive, etc.</td>
Expand All @@ -196,7 +188,6 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
</tr>
<tr>
<td>Delivering a USB drive</td>
Expand All @@ -206,11 +197,10 @@ I'm very grateful to their creators and contributors.
<td>✅</td>
<td>✅</td>
<td>❌</td>
<td>❓</td>
</tr>
</table>

Open an issue on GitHub to add more projects.
Open an [issue](https://github.com/manforowicz/gday/issues) on GitHub to add more projects.

## In this repository

Expand All @@ -220,9 +210,6 @@ Open an issue on GitHub to add more projects.
- [gday_encryption](/gday_encryption/) - Encrypts an IO stream.
- [gday_contact_exchange_protocol](/gday_contact_exchange_protocol/) - Protocol for two peers to share their socket
addresses via a server.
- [gday_file_offer_protocol](/gday_file_offer_protocol/) - Protocol for peers to offer to send each other files.

![gday crate dependency graph](/images/dependency_graph.svg)
- [gday_file_transfer](/gday_file_offer_protocol/) - Protocol for transferring files over a direct connection.s

## Motivation
![xkcd about sending files](/images/file_transfer.png)
![gday crate dependency graph](/images/dependency_graph.svg)
8 changes: 3 additions & 5 deletions gday/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "gday"
version = "0.1.1"
description = "Command line tool to send files easily, securely, and directly, without a relay or port forwarding."
description = "Command line tool to send files directly and securely, without a relay or port forwarding."
homepage = "https://github.com/manforowicz/gday/gday/"

# Inherit these keys from workspace toml
Expand All @@ -13,8 +13,7 @@ repository.workspace = true
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
anyhow = "1.0.86"
clap = { version = "4.5.4", features = ["derive"] }
clap = { version = "4.5.6", features = ["derive"] }
env_logger = "0.11.3"
gday_encryption = { version = "0.1.1", path = "../gday_encryption" }
gday_file_transfer = { version = "0.1.1", path = "../gday_file_transfer" }
Expand All @@ -23,7 +22,6 @@ indicatif = "0.17.8"
log = "0.4.21"
os_str_bytes = "7.0.0"
owo-colors = "4.0.0"
postcard = "1.0.8"
rand = "0.8.5"
serde = { version = "1.0.203", features = ["serde_derive"] }
thiserror = "1.0.61"
thiserror = "1.0.61"
2 changes: 2 additions & 0 deletions gday/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Note: this crate is still in early-development, so expect breaking changes.

# `gday`
![Crates.io Version](https://img.shields.io/crates/v/gday) ![docs.rs](https://img.shields.io/docsrs/gday)

Expand Down
2 changes: 2 additions & 0 deletions gday/src/main.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Note: this crate is still in early-development, so expect breaking changes.
//!
//! `gday` is a command line line tool for peers to send each other files.
//! Features:
//! - Never uses relays. Instead, uses a gday_contact_exchange_server to share socket
Expand Down
2 changes: 1 addition & 1 deletion gday_contact_exchange_protocol/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "gday_contact_exchange_protocol"
version = "0.1.1"
description = "Protocol that peers can use to exchange their public and private socket addresses via a server."
description = "Protocol for peers to exchange their socket addresses via a server."
homepage = "https://github.com/manforowicz/gday/gday_contact_exchange_protocol/"

# Inherit these keys from workspace toml
Expand Down
2 changes: 2 additions & 0 deletions gday_contact_exchange_protocol/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Note: this crate is still in early-development, so expect breaking changes.

# `gday_contact_exchange_protocol`
![Crates.io Version](https://img.shields.io/crates/v/gday_contact_exchange_protocol) ![docs.rs](https://img.shields.io/docsrs/gday_contact_exchange_protocol)

Expand Down
2 changes: 2 additions & 0 deletions gday_contact_exchange_protocol/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Note: this crate is still in early-development, so expect breaking changes.
//!
//! This protocol lets two users exchange their public and (optionally) private socket addresses via a server.
//!
//! On it's own, this crate doesn't do anything other than define a shared protocol.
Expand Down
2 changes: 1 addition & 1 deletion gday_encryption/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "gday_encryption"
version = "0.1.1"
description = "A simple ChaCha20Poly1305 encryption wrapper around an IO stream."
description = "Minimal ChaCha20Poly1305 encryption wrapper around an IO stream."
homepage = "https://github.com/manforowicz/gday/gday_encryption/"

# Inherit these keys from workspace toml
Expand Down
2 changes: 2 additions & 0 deletions gday_encryption/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Note: this crate is still in early-development, so expect breaking changes.

# `gday_encryption`
![Crates.io Version](https://img.shields.io/crates/v/gday_encryption) ![docs.rs](https://img.shields.io/docsrs/gday_encryption)

Expand Down
2 changes: 2 additions & 0 deletions gday_encryption/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Note: this crate is still in early-development, so expect breaking changes.
//!
//! A simple encrypted wrapper around an IO stream.
//! Uses [`chacha20poly1305`] with the [`chacha20poly1305::aead::stream`].
#![forbid(unsafe_code)]
Expand Down
2 changes: 1 addition & 1 deletion gday_file_transfer/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "gday_file_transfer"
version = "0.1.1"
description = "A minimal protocol to securely transfer files over an IO stream. Used by gday."
description = "Protocol to securely transfer files over an encrypted IO stream."
homepage = "https://github.com/manforowicz/gday/gday_file_transfer/"

# Inherit these keys from workspace toml
Expand Down
2 changes: 2 additions & 0 deletions gday_file_transfer/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Note: this crate is still in early-development, so expect breaking changes.

# `gday_file_offer_protocol`
![Crates.io Version](https://img.shields.io/crates/v/gday_file_offer_protocol) ![docs.rs](https://img.shields.io/docsrs/gday_file_offer_protocol)

Expand Down
Loading