1 2<p align="center"> 3<img 4 src="https://user-images.githubusercontent.com/6550035/46709024-9b23ad00-cbf6-11e8-9fb2-ca8b20b7dbec.jpg" 5 width="408px" border="0" alt="croc"> 6<br> 7<a href="https://github.com/schollz/croc/releases/latest"><img src="https://img.shields.io/badge/version-v9.5.0-brightgreen.svg?style=flat-square" alt="Version"></a> 8<a href="https://coveralls.io/github/schollz/croc"><img src="https://img.shields.io/badge/coverage-81%25-green.svg?style=flat-square" alt="Coverage"></a> 9<a href="https://travis-ci.org/schollz/croc"><img 10src="https://img.shields.io/travis/schollz/croc.svg?style=flat-square" alt="Build 11Status"></a> 12<p align="center">This project is supported by:</p> 13<p align="center"> 14 <a href="https://www.digitalocean.com/"> 15 <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" width="201px"> 16 </a> 17</p> 18</p> 19 20`croc` is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, *croc* is the only CLI file-transfer tool that does **all** of the following: 21 22- allows **any two computers** to transfer data (using a relay) 23- provides **end-to-end encryption** (using PAKE) 24- enables easy **cross-platform** transfers (Windows, Linux, Mac) 25- allows **multiple file** transfers 26- allows **resuming transfers** that are interrupted 27- local server or port-forwarding **not needed** 28- **ipv6-first** with ipv4 fallback 29- can **use proxy**, like tor 30 31For more information about `croc`, see [my blog post](https://schollz.com/software/croc6). 32 33![Example](src/install/customization.gif) 34 35## Install 36 37Download [the latest release for your system](https://github.com/schollz/croc/releases/latest), or install a release from the command-line: 38 39``` 40curl https://getcroc.schollz.com | bash 41``` 42 43 44On macOS you can install the latest release with [Homebrew](https://brew.sh/): 45 46``` 47brew install croc 48``` 49 50On macOS you can also install the latest release with [MacPorts](https://macports.org/): 51 52``` 53sudo port selfupdate 54sudo port install croc 55``` 56 57On Windows you can install the latest release with [Scoop](https://scoop.sh/) or [Chocolatey](https://chocolatey.org): 58 59``` 60scoop install croc 61``` 62 63``` 64choco install croc 65``` 66 67On Unix you can install the latest release with [Nix](https://nixos.org/nix): 68 69``` 70nix-env -i croc 71``` 72 73 74On Alpine Linux you have to install dependencies first: 75 76``` 77apk add bash coreutils 78wget -qO- https://getcroc.schollz.com | bash 79``` 80 81On Arch Linux you can install the latest release with `pacman`: 82 83``` 84pacman -S croc 85``` 86 87On Gentoo you can install with `portage`: 88``` 89emerge net-misc/croc 90``` 91 92On Termux you can install with `pkg`: 93 94``` 95pkg install croc 96``` 97 98On FreeBSD you can install with `pkg`: 99 100``` 101pkg install croc 102``` 103 104Or, you can [install Go](https://golang.org/dl/) and build from source (requires Go 1.17+): 105 106``` 107go install github.com/schollz/croc/v9@latest 108``` 109 110On Android there is a 3rd party F-Droid app [available to download](https://f-droid.org/en/packages/com.github.howeyc.crocgui/). 111 112 113## Usage 114 115To send a file, simply do: 116 117``` 118$ croc send [file(s)-or-folder] 119Sending 'file-or-folder' (X MB) 120Code is: code-phrase 121``` 122 123Then to receive the file (or folder) on another computer, you can just do 124 125``` 126croc code-phrase 127``` 128 129The code phrase is used to establish password-authenticated key agreement ([PAKE](https://en.wikipedia.org/wiki/Password-authenticated_key_agreement)) which generates a secret key for the sender and recipient to use for end-to-end encryption. 130 131There are a number of configurable options (see `--help`). A set of options (like custom relay, ports, and code phrase) can be set using `--remember`. 132 133### Custom code phrase 134 135You can send with your own code phrase (must be more than 6 characters). 136 137``` 138croc send --code [code-phrase] [file(s)-or-folder] 139``` 140 141### Allow overwriting without prompt 142 143By default, croc will prompt whether to overwrite a file. You can automatically overwrite files by using the `--overwrite` flag (recipient only). For example, receive a file to automatically overwrite: 144 145``` 146croc --yes --overwrite <code> 147``` 148 149 150### Use pipes - stdin and stdout 151 152You can pipe to `croc`: 153 154``` 155cat [filename] | croc send 156``` 157 158In this case `croc` will automatically use the stdin data and send and assign a filename like "croc-stdin-123456789". To receive to `stdout` at you can always just use the `--yes` will automatically approve the transfer and pipe it out to `stdout`. 159 160``` 161croc --yes [code-phrase] > out 162``` 163 164All of the other text printed to the console is going to `stderr` so it will not interfere with the message going to `stdout`. 165 166 167### Send text 168 169Sometimes you want to send URLs or short text. In addition to piping, you can easily send text with `croc`: 170 171``` 172croc send --text "hello world" 173``` 174 175This will automatically tell the receiver to use `stdout` when they receive the text so it will be displayed. 176 177 178### Use a proxy 179 180You can use a proxy as your connection to the relay by adding a proxy address with `--socks5`. For example, you can send via a tor relay: 181 182``` 183croc --socks5 "127.0.0.1:9050" send SOMEFILE 184``` 185 186### Change encryption curve 187 188You can choose from several different elliptic curves to use for encryption by using the `--curve` flag. Only the recipient can choose the curve. For example, receive a file using the P-521 curve: 189 190``` 191croc --curve p521 <codephrase> 192``` 193 194Available curves are P-256, P-348, P-521 and SIEC. SIEC is the default curve used, it is a lesser known curve that belongs to a class of "super-isolated" curves which has security that does not reduce to the security of curves around it. (Scholl, Travis. Experimental Mathematics 28.4 (2019): 385-397) 195 196 197### Self-host relay 198 199The relay is needed to staple the parallel incoming and outgoing connections. By default, `croc` uses a public relay but you can also run your own relay: 200 201``` 202croc relay 203``` 204 205By default it uses TCP ports 9009-9013. Make sure to open those up. You can customized the ports (e.g. `croc relay --ports 1111,1112`), but you must have a minimum of **2** ports for the relay. The first port is for communication and the subsequent ports are used for the multiplexed data transfer. 206 207You can send files using your relay by entering `--relay` to change the relay that you are using if you want to custom host your own. 208 209``` 210croc --relay "myrelay.example.com:9009" send [filename] 211``` 212 213Note, when sending, you only need to include the first port (the communication port). The subsequent ports for data transfer will be transmitted back to the user from the relay. 214 215#### Self-host relay (docker) 216 217If it's easier you can also run a relay with Docker: 218 219 220``` 221docker run -d -p 9009-9013:9009-9013 -e CROC_PASS='YOURPASSWORD' schollz/croc 222``` 223 224Be sure to include the password for the relay otherwise any requests will be rejected. 225 226``` 227croc --pass YOURPASSWORD --relay "myreal.example.com:9009" send [filename] 228``` 229 230Note: when including `--pass YOURPASSWORD` you can instead pass a file with the password, e.g. `--pass FILEWITHPASSWORD`. 231 232## License 233 234MIT 235 236## Acknowledgements 237 238`croc` has gone through many iterations, and I am awed by all the great contributions! If you feel like contributing, in any way, by all means you can send an Issue, a PR, ask a question, or tweet me ([@yakczar](http://ctt.ec/Rq054)). 239 240Thanks [@warner](https://github.com/warner) for the [idea](https://github.com/warner/magic-wormhole), [@tscholl2](https://github.com/tscholl2) for the [encryption gists](https://gist.github.com/tscholl2/dc7dc15dc132ea70a98e8542fefffa28), [@skorokithakis](https://github.com/skorokithakis) for [code on proxying two connections](https://www.stavros.io/posts/proxying-two-connections-go/). Finally thanks for making pull requests [@maximbaz](https://github.com/maximbaz), [@meyermarcel](https://github.com/meyermarcel), [@Girbons](https://github.com/Girbons), [@techtide](https://github.com/techtide), [@heymatthew](https://github.com/heymatthew), [@Lunsford94](https://github.com/Lunsford94), [@lummie](https://github.com/lummie), [@jesuiscamille](https://github.com/jesuiscamille), [@threefjord](https://github.com/threefjord), [@marcossegovia](https://github.com/marcossegovia), [@csleong98](https://github.com/csleong98), [@afotescu](https://github.com/afotescu), [@callmefever](https://github.com/callmefever), [@El-JojA](https://github.com/El-JojA), [@anatolyyyyyy](https://github.com/anatolyyyyyy), [@goggle](https://github.com/goggle), [@smileboywtu](https://github.com/smileboywtu), [@nicolashardy](https://github.com/nicolashardy), [@fbartels](https://github.com/fbartels), [@rkuprov](https://github.com/rkuprov), [@hreese](https://github.com/hreese), [@xenrox](https://github.com/xenrox) and [Ipar](https://github.com/lpar)! 241