Jay Taylor's notes

back to listing index


[web search]
Original source (github.com)
Tags: golang go file-transfer github.com
Clipped on: 2018-05-29
Skip to content
Image (Asset 1/8) alt=

Easily and securely transfer stuff from one computer to another.

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).

I hear you asking, Why another open-source peer-to-peer file transfer utilities? There are great tools that already do this. But, after review, I found it was useful to make another. Namely, croc has no dependencies (just download a binary and run), it works on any operating system, and its blazingly fast because it does parallel transfer over multiple TCP ports.


These two gifs should run in sync if you force-reload (Ctl+F5)




$ croc -send some-file-or-folder
Sending 4.4 MB file named 'some-file-or-folder'
Code is: cement-galaxy-alpha

Sending (->[1]63982)..
  89% |███████████████████████████████████     | [12s:1s]
File sent (2.6 MB/s)


$ croc
Enter receive code: cement-galaxy-alpha
Receiving file (4.4 MB) into: some-file-or-folder
ok? (y/n): y

Receiving (<-[1]63975)..
  97% |██████████████████████████████████████  | [13s:0s]
Received file written to some-file-or-folder (2.6 MB/s)

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).

Using croc in pipes

You can easily use croc in pipes when you need to send data through stdin or get data from stdout.


$ cat some_file_or_folder | croc

In this case croc will automatically use the stdin data and send and assign a filename like "croc-stdin-123456789".


$ croc --code code-phrase --yes --stdout | more

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.


Download the latest release for your system.

Or, you can install Go and build from source with go get github.com/schollz/croc.

How does it work?

croc is similar to magic-wormhole in spirit and design. Like magic-wormhole, croc generates a code phrase for you to share with your friend which allows secure end-to-end transfering 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 cowyo.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.

The code phrase for transfering files is just three words which are 16 random bits that are menemonic encoded. This code phrase is hashed using sha256 and sent to the relay which maps that hashed code phrase to that connection. When the relay finds a matching code phrase hash for both the receiver and the sender (i.e. they both have the same code phrase), then the sender transmits the encrypted metadata to the receiver through the relay. Then the receiver decrypts and reviews the metadata (file name, size), and chooses whether to consent to the transfer.

After the receiver consents to the transfer, the sender transmits encrypted data through the relay. The relay setups up Go channels for each connection which pipes all the data incoming from that sender's connection out to the receiver's connection. After the transmission the channels are destroyed and all the connection and meta data information is wiped from the relay server. The encrypted file data never is stored on the relay.


Encryption uses pbkdf2 (see RFC2898) where the code phrase shared between the sender and receiver is used as the passphrase. For each of the two encrypted data blocks (metadata stored on relay server, and file data transmitted), a random 8-byte salt is used and a IV is generated according to NIST Recommendation for Block ciphers, Section 8.2.


On the receiver's computer, each piece of received encrypted data is written to a separate file. These files are concatenated and then decrypted. The hash of the decrypted file is then checked against the hash transmitted from the sender (part of the meta data block).

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).

You can also run your own relay, it is very easy. On your server, your-server.com, just run

$ 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.


I am awed by all the great contributions made! 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).





Press h to open a hovercard with more details.