Robot
/
croc
mirror of https://github.com/schollz/croc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update readme

This commit is contained in:
Zack Scholl 2018-07-03 07:10:15 -07:00
parent 8373e374cd
commit bba0bca15e
1 changed files with 21 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@ -13,13 +13,13 @@
*croc* allows any two computers to directly and securely transfer files and folders. When sending a file, *croc* generates a random code phrase which must be shared with the recipient so they can receive the file. The code phrase encrypts all data and metadata and also serves to authorize the connection between the two computers in a intermediary relay. The relay connects the TCP ports between the two computers and does not store any information (and all information passing through it is encrypted).
**New version released June 24th, 2018 - please upgrade if you are using the public relay.**
**New version released Jly 3rd, 2018 - please upgrade if you are using the public relay.**
I hear you asking, *Why another open-source peer-to-peer file transfer utilities?* [There](https://github.com/cowbell/sharedrop) [are](https://github.com/webtorrent/instant.io) [great](https://github.com/kern/filepizza) [tools](https://github.com/warner/magic-wormhole) [that](https://github.com/zerotier/toss) [already](https://github.com/ipfs/go-ipfs) [do](https://github.com/zerotier/toss) [this](https://github.com/nils-werner/zget). But, after review, [I found it was useful to make another](https://schollz.github.io/sending-a-file/). Namely, *croc* has no dependencies (just [download a binary and run](https://github.com/schollz/croc/releases/latest)), it works on any operating system, and its blazingly fast because it does parallel transfer over multiple TCP ports.
# Example
_These two gifs should run in sync if you force-reload (Ctl+F5)_
<!-- _These two gifs should run in sync if you force-reload (Ctl+F5)_
**Sender:**
@ -27,23 +27,22 @@ _These two gifs should run in sync if you force-reload (Ctl+F5)_
**Receiver:**
![receive](https://raw.githubusercontent.com/schollz/croc/master/logo/receiver2.gif)
![receive](https://raw.githubusercontent.com/schollz/croc/master/logo/receiver2.gif) -->
**Sender:**
```
$ croc -send some-file-or-folder
$ croc send some-file-or-folder
Sending 4.4 MB file named 'some-file-or-folder'
Code is: cement-galaxy-alpha
On the other computer please run
Your public key: ecad-bakery-cup-unlit-roam-fetid-arulo-updike
Recipient public key: bike-cokery-casina-donut-field-farrow-mega-shine
ok? (y/n): y
croc cement-galaxy-alpha
Sending (->[1]63982)..
89% |███████████████████████████████████ | [12s:1s]
File sent (2.6 MB/s)
Transfer complete.
```
**Receiver:**
@ -52,14 +51,11 @@ File sent (2.6 MB/s)
$ croc
Enter receive code: cement-galaxy-alpha
Receiving file (4.4 MB) into: some-file-or-folder
Your public key: bike-cokery-casina-donut-field-farrow-mega-shine
Recipient public key: ecad-bakery-cup-unlit-roam-fetid-arulo-updike
ok? (y/n): y
ok? (y/N): y
Receiving (<-[1]63975)..
97% |██████████████████████████████████████ | [13s:0s]
Received file written to some-file-or-folder (2.6 MB/s)
Received file written to some-file-or-folder
```
Note, by default, you don't need any arguments for receiving! This makes it possible for you to just double click the executable to run (nice for those of us that aren't computer wizards).
@ -71,7 +67,7 @@ You can easily use *croc* in pipes when you need to send data through stdin or g
**Sender:**
```
$ cat some_file_or_folder | croc
$ cat some_file_or_folder | croc send
```
In this case *croc* will automatically use the stdin data and send and assign a filename like "croc-stdin-123456789".
@ -79,7 +75,7 @@ In this case *croc* will automatically use the stdin data and send and assign a
**Receiver:**
```
$ croc --code code-phrase --yes --stdout | more
$ croc --code code-phrase --yes --stdout receive
```
Here the reciever specified the code (`--code`) so it will not be prompted, and also specified `--yes` so the file will be automatically accepted. The output goes to stdout when flagged with `--stdout`.
@ -92,24 +88,20 @@ Here the reciever specified the code (`--code`) so it will not be prompted, and
Or, you can [install Go](https://golang.org/dl/) and build from source with `go get github.com/schollz/croc`.
# How does it work?
![Protocol](https://camo.githubusercontent.com/b85a5f63469a2f986ce4d280862b46b00ff6605c/68747470733a2f2f692e696d6775722e636f6d2f73376f515756502e706e67)
# How does it work?
*croc* is similar to [magic-wormhole](https://github.com/warner/magic-wormhole#design) in spirit. Like *magic-wormhole*, *croc* generates a code phrase for you to share with your friend which allows secure end-to-end transferring of files and folders through a intermediary relay that connects the TCP ports between the two computers. The standard relay is on a public IP address (default `ws://croc3.schollz.com`), but before transmitting the file the two instances of *croc* send out UDP broadcasts to determine if they are both on the local network, and use a local relay instead of the cloud relay in the case that they are both local.
*croc* is similar to [magic-wormhole](https://github.com/warner/magic-wormhole#design) in spirit. Like *magic-wormhole*, *croc* generates a code phrase for you to share with your friend which allows secure end-to-end transferring of files and folders through a intermediary relay that connects the TCP ports between the two computers. Like *magic-wormhole*, security is enabled by performing password-authenticated key exchange (PAKE) with the weak code phrase to generate a session key on both machines without passing any private information between the two. The session key is then verified and used to encrypt the content with AES-256. If at any point the PAKE fails, an error will be reported and the file will not be transferred. More details on the PAKE transfer can be found at [github.com/schollz/pake](https://github.com/schollz/pake).
## Relay
## Run your own relay
*croc* relies on a TCP relay to staple the parallel incoming and outgoing connections. The relay temporarily stores connection information and the encrypted meta information. The default uses a public relay at, `cowyo.com`, which has a 30-day uptime of 99.989% ([click here to check the current status of the public relay](https://stats.uptimerobot.com/lOwJYIgRm)).
You can also run your own relay, it is very easy. On your server, `your-server.com`, just run
*croc* relies on a TCP relay to staple the parallel incoming and outgoing connections. The relay temporarily stores connection information and the encrypted meta information. The default uses a public relay at, `wss://croc3.schollz.com`. You can also run your own relay, it is very easy. On your server, `your-server.com`, just run
```
$ croc -relay
$ croc relay
```
Now, when you use *croc* to send and receive you should add `-server your-server.com` to use your relay server. Make sure to open up TCP ports 27001-27009.
Now, when you use *croc* to send and receive you should add `-server your-server.com` to use your relay server. Make sure to open up TCP ports (see `croc relay --help` for which ports to open).
# Contribute
@ -119,6 +111,10 @@ I am awed by all the [great contributions](#acknowledgements) made! If you feel
# Protocol
This is an outline of the protocol used here. The basic PAKE protocol is from [Dan Boneh and Victor Shoup's crypto book](https://crypto.stanford.edu/%7Edabo/cryptobook/BonehShoup_0_4.pdf) (pg 789, "PAKE2 protocol).
![Basic PAKE](https://camo.githubusercontent.com/b85a5f63469a2f986ce4d280862b46b00ff6605c/68747470733a2f2f692e696d6775722e636f6d2f73376f515756502e706e67)
1. **Sender** requests new channel and receives empty channel from **Relay**, or obtains the channel they request (or an error if it is already occupied).
2. **Sender** generates *u* using PAKE from secret *pw*.
3. **Sender** sends *u* to **Relay** and the type of curve being used. Returns error if channel is already occupied by sender, otherwise it uses it.