schollz/croc
1
0
Fork 0
mirror of https://github.com/schollz/croc.git synced 2024-12-25 14:54:30 +03:00
Code Issues Projects Releases Wiki Activity

simplify readme

Browse Source
This commit is contained in:
Zack Scholl 2019-05-01 13:20:30 -06:00
parent ecfdb2d440
commit 77b11e3c3f
1 changed files with 12 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
README.md
View File

@ -4,7 +4,7 @@
src="https://user-images.githubusercontent.com/6550035/46709024-9b23ad00-cbf6-11e8-9fb2-ca8b20b7dbec.jpg"
width="408px" border="0" alt="croc">
<br>
<a href="https://github.com/schollz/croc/releases/latest"><img src="https://img.shields.io/badge/version-4.1.5-brightgreen.svg?style=flat-square" alt="Version"></a>
<a href="https://github.com/schollz/croc/releases/latest"><img src="https://img.shields.io/badge/version-6.0.0-brightgreen.svg?style=flat-square" alt="Version"></a>
<img src="https://img.shields.io/badge/coverage-77%25-brightgreen.svg?style=flat-square" alt="Code coverage">
<a href="https://travis-ci.org/schollz/croc"><img
src="https://img.shields.io/travis/schollz/croc.svg?style=flat-square" alt="Build
@ -15,79 +15,43 @@ Status"></a>
<p align="center"><code>curl https://getcroc.schollz.com | bash</code></p>
*croc* is a tool that allows any two computers to simply and securely transfer files and folders. There are many tools that can do this but AFAIK *croc* is the only tool that is easily installed and used on any platform, *and* has secure peer-to-peer transferring, *and* has the capability to resume broken transfers.
*croc* is a tool that allows any two computers to simply and securely transfer files and folders. There are many tools that can do this but AFAIK *croc* is the only tool that is easily installed and used on any platform, *and* has secure peer-to-peer transferring (through a relay), allows multiple files, *and* has the capability to resume broken transfers.
## Overview
**Transmit encrypted data with a code phrase**
For more information on how croc works, see [my blog post](https://schollz.com/software/croc).
*croc* securely transfers data using *code phrases* - a combination of three random words (mnemonicoded 4 bytes). The code phrase is shared between the sender and the recipient for password authenticated key exchange ([PAKE](https://github.com/schollz/pake)), a cryptographic method to use a shared weak key (the "code phrase") to generate a strong key for secure end-to-end encryption. By default, a code phrase can only be used once between two parties so an attacker would have a chance of less than 1 in *4 billion* to guess the code phrase correctly to steal the data. An attacker with the wrong code phrase will fail the PAKE and the sender will be notified without any data transfering. Only two people with the right code phrase will be able to computers transfer encrypted data through a relay.
**Fast data transfer through TCP**
The actual data transfer is accomplished using a relay, either using raw TCP sockets or websockets. If both computers are on the LAN network then *croc* will use a local relay, otherwise a public relay is used. All the data going through the relay is encrypted using the PAKE-generated session key, so the relay can't spy on information passing through it. The data is transferred in blocks, where each block is compressed and encrypted, and the recipient keeps track of blocks received so that it can resume the transfer if interrupted.
**Relay allows any two computers to connect**
*croc* differs from a utility like *scp* because it doesn't require any two computers to have enabled port-forwarding. Instead, *croc* will uses a relay - a temporary server setup locally (if both computers are on lan) or publicly (default is at croc4.schollz.com). Any two computers can connect to the relay, and after securing their channel with PAKE, they can transfer encrypted metadata and data through the relay. The relay works by first having the computers communicate the PAKE protocol via websockets, and then exchanging encrypted metadata, and then stapling the TCP connections directly so that they can transfer directly.
**Why another data transfer utility?**
My motivation to write *croc*, as stupid as it sounds, is because I wanted to create a program that made it easy to send a 3GB+ PBS documentary to my friend in a different country. My friend has a Windows computer and is not comfortable using a terminal. So I wanted to write a program that, while secure, is simple to receive a file. *croc* accomplishes this, and now I find myself using it almost everyday at work. To receive a file you can just download the executable and double click on it. The name is inspired by the [fable of the frog and the crocodile](https://web.archive.org/web/20180926035731/http://allaboutfrogs.org/stories/crocodile.html).
## Examples
The first example shows the basic transfer of some file or folder from computer 1 to computer 2. _These two gifs should run in sync if you force-reload (Ctl+F5)_
![send](.github/1.gif)
![receive](.github/2.gif)
The second example shows how you can restart a broken transfer. Here, computer 2 presses Ctl+C during a transfer to abruptly break the connection, and then resumes by having computer 1 re-send the file. _These two gifs should run in sync if you force-reload (Ctl+F5)_
![send](.github/3.gif)
![receive](.github/4.gif)
In version 4, there is now a GUI available for [Windows](https://github.com/schollz/croc/releases/latest) and [Linux](https://github.com/schollz/croc/releases/latest):
<div style="text-align:center">
<img src="https://user-images.githubusercontent.com/6550035/47256575-8a193e00-d437-11e8-96fa-42c9d072a8f1.PNG">
</div>
## Install
[Download the latest release for your system](https://github.com/schollz/croc/releases/latest).
Or, you can [install Go](https://golang.org/dl/) and build from source with `go get github.com/schollz/croc`. Since *croc* uses [Go modules](https://golang.org/doc/go1.11#modules) it requires Go version 1.11+.
Or, you can quickly install a release from the command-line:
Download [the latest release for your system](https://github.com/schollz/croc/releases/latest), or install a release from the command-line:
```
$ curl https://getcroc.schollz.com | bash
```
Or, you can [install Go](https://golang.org/dl/) and build from source (requires Go 1.11+):
```
$ wget -qO- https://getcroc.schollz.com | bash
go get github.com/schollz/croc
```
## Usage
The basic usage is to just do
To send a file, simply do:
```
$ croc send FILE
```
to send and then on the other computer you can just do
Them to receive the file, you can just do
```
$ croc [code phrase]
$ croc [code-phrase]
```
to receive (you'll be prompted to enter the code phrase). Note, by default, you don't need any arguments for receiving, instead you will be prompted to enter the code phrase. This makes it possible for you to just double click the executable to run (nice for those of us that aren't computer wizards).
### Custom code phrase
You can send with your own code phrase (must be more than 4 characters).