secretshare lets you share secret data securely and easily.
You do this:
$ secretshare send /path/to/supersecret.txt ... To receive this secret: secretshare receive JOlFukTBXDlsdS8P+8ETA_z25hU5Ou4bOvXpJQFV0Wc
You send the recipient the output. And the recipient does this:
$ secretshare receive JOlFukTBXDlsdS8P+8ETA_z25hU5Ou4bOvXpJQFV0Wc File saved as supersecret.txt
What makes secretshare better than more common methods of sharing secrets?
- Secrets are deleted from the cloud after 24-48 hours, so a snooper can't go back through the recipient's or sender's communication history later and retrieve them.
- Secrets are encrypted with a one-time-use key, so a snooper can't use the key from one secret to steal another.
- Secrets are never transmitted or stored in the clear, so a snooper can't even read them if they manage to compromise the Amazon S3 bucket in which they're stored.
- Users don't need Amazon AWS credentials, so a snooper can't steal those credentials from a user.
Want to run secretshare at your organization? Installation instructions can be found in the Server setup (for admins) section. Just need to know how to use it? Check out The basics (for users).
The basics (for users)
After your administrator sets up
secretshare, they'll give you a command to run to initially configure your client. It'll look something like this:
$ secretshare config --endpoint [https://your-secretshare-server] --bucket [your-bucket-name] --bucket-region [aws-region-name] --auth-key [your-auth-key]
This will create a config file and an auth key file in your home directory, called
.secretshare.key. Ideally, you'll never have to think about these files again.
Sending a secret
To send a secret file to someone, use
$ secretshare send /path/to/supersecret.txt
This will output a
secretshare receive command. Just copy that, and paste it into an email, chat, or what-have-you.
The file will disappear in 24-48 hours. If the recipient doesn't download it in time, you'll have to re-send it.
Receiving a secret
To download a secret that someone wants to send you, use
$ secretshare receive [a big long key string]
This will download the file to your working directory. If it's already been 24-48 hours since the file was sent to you, it may already have expired. In that case, you'll have to ask the sender to re-send it.
Server setup (for admins)
Installing from a package (recommended)
If you are running Debian or Ubuntu:
curl -L 'https://apt.waucka.net/apt-key.gpg' | sudo apt-key add - sudo sh -c 'echo "deb http://apt.waucka.net/secretshare/ stable main" > /etc/apt/sources.list.d/secretshare.list' sudo apt update sudo apt install secretshare-server
This should work on any reasonably recent version of Debian or Ubuntu.
- Clone the repository.
- Enter the docker directory.
docker build -t secretshare .
- Push the image to the Docker repository of your choice or run it locally. You will need to set the environment variables listed below:
SECRETSHARE_BUCKET-- the name of the S3 bucket you will use
SECRETSHARE_BUCKET_REGION-- the region where the above bucket is located
SECRETSHARE_SECRET_KEY-- make something up (pwgen is good for this)
SECRETSHARE_AWS_KEY_ID-- the AWS key ID for an IAM user that has the privileges listed in the policy template
SECRETSHARE_AWS_SECRET_KEY-- the AWS secret key for the IAM user
Installing from a prebuilt binary
Prebuilt binaries are available on the releases page. Just download one and then follow the instructions below, starting at step 5.
Building and installing from source
Build on a machine with the same CPU architecture as the one you'll be deploying to.
- Clone the repository.
make native. If you want to give it a particular version name, set the
SECRETSHARE_VERSIONenvironment variable. The binaries will end up in
build/native. You can cross-compile the server and CLI client using
make osx, or
make windows, but the GUI client cannot be cross-compiled.
- [OPTIONAL] Run
./setup.sh. This sets up your config files and environment for building (or developing) secretshare. It also creates or configures the S3 bucket and AWS credentials that secretshare will use. It outputs a
secretshare configcommand that you'll need to give to your users; save this!
/usr/local/binon the target server. Copy
/etc/secretshare-server.jsonon the same server and make any necessary changes. Make sure it's readable only by the user that
secretshare-serveris going to run as.
- Configure secretshare-server to start on boot, run as an unprivileged user, and restart if it crashes. If you are using systemd, use secretshare-server.service. You will need to create the
You should also put HTTPS in front of
secretshare-server. See the nginx documentation for a walkthrough of putting an HTTPS-enabled proxy in front of an application.
Your users will need to run
secretshare config --endpoint $SECRETSHARE_SERVER_URL --bucket-region $BUCKET_REGION --bucket $BUCKET_NAME --auth-key $AUTH_KEY using the values from your secretshare-server.json file.
secretshare client to your users
If you built from source, you'll find client binaries for OS X, Linux, and Windows in the
build directory. Send them out to your users, and have your users run the
secretshare config command above.
Otherwise, point your users at the release page or the APT repository. Those who are comfortable with the command line should install the
secretshare binary or the
secretshare-cli Debian package. Those who prefer a GUI should install the
secretshare-gui binary or the
secretshare-gui Debian package.
Compile or download, then put the
secretshare executable somewhere in your
If you want the command-line client, then grab the
secretshare binary. If you want the GUI, then grab the
If you are on Debian or Ubuntu, you can use the APT repository. If you want the command-line client, then install the
secretshare-cli package. If you want the GUI, then install the
On a Mac, you may want to use secretshare.dmg to install the GUI version. Please note that neither the DMG nor the .app bundle are signed, so you will need to configure macOS to allow unsigned software to run.
- Write an initscript or systemd unit to launch secretshare-server as an unprivileged user
You will need to run the server as an appropriately privileged user. See policy_template.json for an AWS policy template for an AWS policy that has the needed privileges. It should only need PutObject and PutObjectACL, but the others may be needed in the future (especially DeleteObject and ListBucket).
What goes on under the hood
Suppose you run
secretshare send foobar.txt. What happens?
- The secretshare client generates a random AES key and an object ID based on that key (but not mappable back to that key)
- The secretshare client contacts the secretshare server and requests a new upload "ticket".
- The secretshare server generates a pre-signed S3 upload URL for a metadata bundle and the file itself.
- The secretshare client generates a metadata bundle (containing the secret's size and filename), encrypts it with the generated AES key in CBC mode, and uploads it to S3 using the pre-signed URL for metadata. The filename on S3 is
- The secretshare client encrypts
foobar.txtwith the generated AES key in CBC mode and uploads it to S3 using the pre-signed URL. The filename on S3 is
/$ID. The file is encrypted on-the-fly, so large files can be encrypted without using an inordinate amount of memory.
- The secretshare client prints the ID, the key, and the S3 URL for the file.
Now suppose somebody runs
secretshare receive $KEY,
$KEY is the key from the previous command. What happens?
- The secretshare client downloads the metadata bundle from S3 and decrypts it.
- The secretshare client downloads the file from S3 and decrypts it, naming it according to the name in the metadata bundle. If a file with that name already exists, it will prompt the user before overwriting it. It decrypts the file on-the-fly, so large files can be decrypted without using an inordinate amount of memory.
To set up your dev environment initially, you'll want to run
make as described in steps 1 & 2 of Building and installing from source. This will ask for some AWS credentials to do the initial setup.
To run tests, first you need to run
glide install. And then run
credmgr on. And then run
source test_env. And then run
make test. Optionally, you can just run
go test github.com/waucka/secretshare/commonlib to run the unit tests for encryption and decryption.
make test runs this in addition to the functional tests.
If you have not made any changes, then no special action is needed when distributing the binary. If you are packaging for a Linux distribution (especially Debian), you may need to patch GetSourceLocation in commonlib/sourcelocation.go to return a different URL.
If you have made changes to secretshare, please ensure that the output of GetSourceLocation in commonlib/sourcelocation.go is correct. If you are hosting your version on GitHub, all you need to do is change SourceUrlPrefix to the location of your fork in GitHub. If you are not, then you may need to alter GetSourceLocation appropriately.
Many thanks to my employer, Exosite, which gives its employees the freedom to open-source broadly useful tools like this.