shamir

README

Shamir

A CLI frontend for Hashicorp Vault's Shamir's Secret Sharing implementation. This allows you to split a secret into x shares, and then combine them back into a single secret using any y of those shares with y <= x.

$ shamir split secret.txt # default: split into 5 shares where you need any 3 to restore the secret (numbers configurable)

$ shamir restore shares.txt # shares.txt should contain at least 3 newline separated shares from above

Table of Contents

• Table of Contents
• Background
• Install
• Usage
  • Split
  • Restore
• Related Efforts
• Maintainers
• Contributing
• License

Background

Extra care needs to be taken when dealing with secrets. Therefore, this tiny tool is designed to be:

• credible - It uses Hashicorp Vault's Shamir's Secret Sharing implementation.
• minimal - It only uses Go's standard library besides the above dependency.
• approachable - The 131 LoC should be quick and easy to audit yourself.

Further it's:

• configurable - You can configure the number of shares and the number of shares needed to restore the secret.
• composable - You can pipe stdin to it and use it in scripts.

Write programs that do one thing and do it well. - Douglas McIlroy

Install

When you are dealing with secrets I would recommend compiling the code yourself instead of relying on a binary distribution:

go install github.com/dennis-tra/shamir@latest

Make sure the $GOPATH/bin is in your PATH variable to access the installed shamir executable.

Usage

Split

Let's imagine you have confidential data in a file called secret.txt. You could then run any of the following commands:

$ shamir split secret.txt
$ shamir split -shares 10 -threshold 5 secret.txt
$ cat secret.txt | shamir split

The CLI exposes the following options:

• -shares - The number of shares to split the secret into.
• -threshold - The number of shares needed to restore the secret.

Example:

$ echo "My very secret secret." | shamir split -shares 4 -threshold 3
gU3GKbSg3CpSHtC+04y8OH9mtIdiq2tm
GXmZfZhoqRAgzGO+fULXEXfDusDJuCcX
ByQs4+phvdU2zXzMjYvjA+7qLLTke8Uk
9dV1XA0pJV2RDzLYh6qwKzjxJ+iBrd9W

Each line corresponds to one share of which you need any three to restore the original message.

To create separate files for each share, pipe shamir to the unix split command:

$ echo "My very secret secret." | shamir split -shares 4 -threshold 3 | split -l 1 - share_

-l 1 means to split after each line, - means to use stdin and share_ is the prefix for the files. The above command will create 4 files named share_aa, share_ab, share_ac and share_ad.

Restore

Let's imagine you have a file called shares.txt which contains more than threshold shares of your secret separated by newlines. You could then run any of the following commands:

$ shamir restore shares.txt
$ cat shares.txt | shamir restore

Example:

$ echo "9dV1XA0pJV2RDzLYh6qwKzjxJ+iBrd9W\nByQs4+phvdU2zXzMjYvjA+7qLLTke8Uk" | shamir restore # not enough shares
VL_��n�!�m5��Π8
$ echo "9dV1XA0pJV2RDzLYh6qwKzjxJ+iBrd9W\nByQs4+phvdU2zXzMjYvjA+7qLLTke8Uk\ngU3GKbSg3CpSHtC+04y8OH9mtIdiq2tm" | shamir restore
My very secret secret.

Note the \n characters in the echo command to separate the shares from above. Share ordering is not relevant.

Related Efforts

• kinvolk/go-shamir - A small CLI tool for Shamir's Secret Sharing written in Go, using Vault's Shamir implementation

Maintainers

@dennis-tra.

Contributing

Feel free to dive in! Open an issue or submit PRs.

License

Apache 2.0 © Dennis Trautwein