Ruby Docs : http://www.rubydoc.info/gems/tss
This code is new and has not yet been tested in production. Use at your own risk. The share format and interface should be fairly stable now but should not be considered fully stable until v1.0.0 is released.
This Ruby gem implements Threshold Secret Sharing, as specified in the Network Working Group Internet-Draft submitted by D. McGrew (draft-mcgrew-tss-03.txt).
Threshold Secret Sharing (TSS) provides a way to generate N shares
from a value, so that any M of those shares can be used to
reconstruct the original value, but any M-1 shares provide no
information about that value. This method can provide shared access
control on key material and other secrets that must be strongly
protected.
This threshold secret sharing method is based on polynomial interpolation in GF(256) and also provides a robust format for the storage and transmission of shares.
The sharing format is Robust Threshold Secret Sharing (RTSS) as described in the Internet-Draft. RTSS is a binary data format and a method for ensuring that any secrets recovered are identical to the secret that was originally shared.
This implementation supports RTSS digest types for NONE, SHA1, and
SHA256. SHA256 is the recommended digest. In the RTSS scheme a digest of
the original secret is concatenated with the secret itself prior to the splitting
of the secret into shares. Later, this digest is compared with any secret recovered
by recombining shares. If the hash of the recovered secret does not match the
original hash stored in the shares the secret will not be returned. The verifier
hash for the secret is not available to shareholders prior to recombining shares.
The specification also addresses the optional implementation of a MAGIC_NUMBER and
advanced error correction schemes. These extras are not currently implemented.
No time for docs? Here is how to get going in a minute, using the
command line or Ruby, with the default 3 out of 5 secret sharing.
$ echo 'secret unicode characters ½ ♥ 💩' | tss split -O /tmp/shares.txt
$ tss combine -I /tmp/shares.txt
RECOVERED SECRET METADATA
*************************
hash : 6d1bc4242998bc170d35d374ebdf39295b271db900de25d249563a4622f113e0
hash_alg : SHA256
identifier : 6b02cfcfc24a2b50
process_time : 0.55ms
threshold : 3
secret :
secret unicode characters ½ ♥ 💩$ bundle exec bin/console
> require 'tss'
=> false
> shares = TSS.split(secret: 'my deep dark secret')
=> ["tss~v1~506168fade769236~3~NTA2MTY4ZmFkZTc2OTIzNgIDAEEBIM39jPGXFz4zKCObWgp2zQmCuUx92-VUf48FWQFqnLF3bw6VtVjYK7JRfESZIREdzhWcQuTQVuGKazxWRK27Tg==",
"tss~v1~506168fade769236~3~NTA2MTY4ZmFkZTc2OTIzNgIDAEEC1E8YyDhp5NeZvF6vHeUT6HoiU0AgoF69jyjNRbtcIi1YoymJTau1rJP-3nQXOofaB2LgnAhJpbB8vrID9WTKgQ==",
"tss~v1~506168fade769236~3~NTA2MTY4ZmFkZTc2OTIzNgIDAEEDmfvFIKybg8nO9Q9fZ5wARgHFngFQdrbk_arFEbc7s5HedTjzkoZYLlV8xnywt4AVAHAO0nSLY3C7iJPifH5VYA==",
"tss~v1~506168fade769236~3~NTA2MTY4ZmFkZTc2OTIzNgIDAEEEiBoCoHycMNTS5yQEU8_Sc7eVlIZOJP1-ka_7MPTlC1p2DyNdGvQxy3pBFZyH8WXAY9ICBxiZRDCJisFrebviAg==",
"tss~v1~506168fade769236~3~NTA2MTY4ZmFkZTc2OTIzNgIDAEEFxa7fSOhuV8qFrnX0KbbB3cxyWcc-8hUn4y3zZPiCmubw2TInxdncSbzDDZQgfGIPZMDsSWRbgvBOvOCK8KF94w=="]
> secret = TSS.combine(shares: shares)
=> {:hash=>"f1b91fef6a7535a974d3644c3eac16d2c907720c981290214d5d1db7cdb724af",
:hash_alg=>"SHA256",
:identifier=>"506168fade769236",
:process_time=>0.94,
:secret=>"my deep dark secret",
:threshold=>3}
> puts secret[:secret]
my deep dark secret
=> nilWhile this implementation has not yet had a formal security review, the cryptographic underpinnings were carefully specified in an IETF draft document authored by a noted cryptographer. I have reached out to individuals respected in the field for their work in implementing cryptographic solutions to help review this code.
I've read draft-mcgrew-tss-03 and then took a look at your code. Impressive! Nice docs, clean easy-to-read code. I'd use constant-time comparison for hashes [resolved : 254ecab], but apart from that I have nothing to add. Good job!
-- Dmitry Chestnykh (@dchest)
[v0.1.0 : 4/13/2016]
All that being said, if your threat model includes a Nation State Actor the security of this particular code should probably not be your primary concern.
-
Don't split large texts. Instead, split the much smaller encryption keys that protect encrypted large texts. Supply the encrypted files and the shares separately to recipients. Threshold secret sharing can be very slow at splitting and recombining very large bodies of text, especially when combined with a large number of shares. Every byte of the secret must be processed
num_sharestimes. -
Don't treat shares like encrypted data, but instead like the encryption keys that unlock the data. Shares are keys, and need to be protected as such. There is nothing to slow down an attacker if they have access to enough shares.
-
If you send keys by email, or some other insecure channel, then your email provider, or any entity with access to their data, now also has the keys to your data. They just need to collect enough keys to meet the threshold. Sending enough shares to recreate a secret through any single provider offers no more security than sending the key itself.
-
Use public key cryptography to encrypt secret shares with the public key of each individual recipient. This can protect the share data from unwanted use while in transit or at rest. OpenPGP would be one such tool for encrypting shares to send safely.
-
Put careful thought into how you want to distribute shares. It often makes sense to give individuals more than one share.
There is pretty extensive inline documentation. You can view the latest auto-generated docs at http://www.rubydoc.info/gems/tss
TSS is continuously integration tested on a number of Ruby versions. See the file
.travis.yml in the root of this repository for the currently tested versions.
Add this line to your application's Gemfile:
gem 'tss', '~> 0.4'And then execute:
$ bundleOr install it yourself as:
$ gem install tssThe TSS gem is cryptographically signed. To be sure the gem you install hasn’t been tampered with you can install it using the following method:
Add my public key (if you haven’t already) as a trusted certificate
# Caveat: Gem certificates are trusted globally, such that adding a
# cert.pem for one gem automatically trusts all gems signed by that cert.
gem cert --add <(curl -Ls https://raw.github.com/grempe/tss-rb/master/certs/gem-public_cert_grempe_2026.pem)
To install, it is possible to specify either HighSecurity or MediumSecurity
mode. Since the tss gem depends on one or more gems that are not cryptographically
signed you will likely need to use MediumSecurity. You should receive a warning
if any signed gem does not match its signature.
# All dependent gems must be signed and verified.
gem install tss -P HighSecurity
# All signed dependent gems must be verified.
gem install tss -P MediumSecurity
# Same as above, except Bundler only recognizes
# the long --trust-policy flag, not the short -P
bundle --trust-policy MediumSecurity
You can learn more about security and signed Ruby Gems.
Most, if not all, of the commits and tags to the repository for this code are
signed with my PGP/GPG code signing key. I have uploaded my code signing public
keys to GitHub and you can now verify those signatures with the GitHub UI.
See this list of commits
and look for the Verified tag next to each commit. You can click on that tag
for additional information.
You can also clone the repository and verify the signatures locally using your own GnuPG installation. You can find my certificates and read about how to conduct this verification at https://www.rempe.us/keys/.
When you install the gem a simple tss command-line interface (CLI)
is also installed and should be available on your $PATH.
The CLI is a user interface for splitting and combining secrets. You can
see the full set of options available with tss help, tss help split,
or tss help combine.
A secret to be split can be provided using one of three
different input methods; STDIN, a path to a file, or when prompted
interactively. In all cases the secret should be UTF-8 or
US-ASCII encoded text and be no larger than 65,535 Bytes
(including header and hash verification bytes).
Each method for entering a secret may have pros and cons from a security perspective. You need to understand what threat model you want to protect against in order to choose wisely. Here are a few examples for how to split a secret.
Example : STDIN
Can read the secret from STDIN and write the split shares to a file. Be
cautioned that this method may leave command history which may contain your
secret.
echo 'a secret' | tss split -O /tmp/shares.txt
Example : --input-file
Can read the secret from a file and write the split shares to STDOUT. Be
cautioned that storing the secret on a filesystem may expose you to certain
attacks since it can be hard to fully erase files once written.
$ cat /tmp/secret.txt
my secret
$ tss split -I /tmp/secret.txt
tss~v1~8b66eb89ee25a46c~3~OGI2NmViODllZTI1YTQ2YwIDACsBqgQvwFhKboLMAmYwF5_CvaUwM8pmqUipbMRzakdbP53WJa-E6tf2nl2M
tss~v1~8b66eb89ee25a46c~3~OGI2NmViODllZTI1YTQ2YwIDACsCk1EU-HwvC6pjvQ5wDas221Qs4A7TtJNpi-Su8hxOqrsCSQ8t11aiQUpm
tss~v1~8b66eb89ee25a46c~3~OGI2NmViODllZTI1YTQ2YwIDACsDVCwbS0EGF03btYwqqVuk7S0z-nSinHtPpsFaFm5dys85j3JlK-yCVNyP
tss~v1~8b66eb89ee25a46c~3~OGI2NmViODllZTI1YTQ2YwIDACsEPUzgi8CDn4ix1dLQTQDj2yTdeeQcZAvGuMyQ_H7EepN6WO_KB1DuqTxm
tss~v1~8b66eb89ee25a46c~3~OGI2NmViODllZTI1YTQ2YwIDACsF-jHvOP2qg28J3VCK6fBx7V3CY55tTOPglelkGAzXGudBnpKC--rOvKqP
Example : interactive
Can read the secret interactively from a terminal and write the split shares
to STDOUT. This method is more secure since the secret will not be stored
in the command shell history or in a file on a filesystem that is hard to
erase securely. It does not protect you from simple keylogger attacks though.
$ tss split
Enter your secret, enter a dot (.) on a line by itself to finish :
secret > the vault password is:
secret > V0ulT!
secret > .
tss~v1~1f8532a9d185efc4~3~MWY4NTMyYTlkMTg1ZWZjNAIDAD8BJkMvkHUGPQk1HQr_jVj9JkhavJVkdeFDEtRAf8O6vjksCjMMjiyuUL0bOD7vDnmdrzHK8QVymXU5vnjAREs=
tss~v1~1f8532a9d185efc4~3~MWY4NTMyYTlkMTg1ZWZjNAIDAD8CJpiKCEtSfmugr_gbvEIBs2M2sZfHxuZsBuPpB35OGeyWmGZCyJCNu0W2z3abkV1Q8uTPvT75YYRpw6BcdvQ=
tss~v1~1f8532a9d185efc4~3~MWY4NTMyYTlkMTg1ZWZjNAIDAD8DdLPAuEg1Ng7hkoKFQmmL-lkILWvQiQ15JELFLJz-PvdZucDCqS-X6QAIbwWE3u2XrTgsH1kmIvpMeZhzfPk=
tss~v1~1f8532a9d185efc4~3~MWY4NTMyYTlkMTg1ZWZjNAIDAD8EJT1XJ-DeOXuE3JD6VpZk79945_peSk1ij1Mk5ql-l2jkv85yGBbyH0VIBmJp2WsEMmESZqTsQ9kKB-0Ljq8=
tss~v1~1f8532a9d185efc4~3~MWY4NTMyYTlkMTg1ZWZjNAIDAD8FdxYdl-O5cR7F4epkqL3upuVGewZJBaZ3rfIIzUvOsHMrnmjyeanoTQD2phF2ltvDbb3xxMMzAKcvvdUkhKI=
You can use the CLI to enter shares in order to recover a secret. Of course
you will need at least the number of shares necessary as determined
by the threshold when your shares were created. The threshold is visible
as the third field in every HUMAN formatted share.
As with splitting a secret, there are also three methods of getting the shares
into the CLI. STDIN, a path to a file containing shares, or interactively.
Here are some simple examples of using each:
Example : STDIN
$ echo 'a secret' | tss split | tss combine
RECOVERED SECRET METADATA
*************************
hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
hash_alg : SHA256
identifier : fff58c38b14734f3
process_time : 0.34ms
threshold : 3
secret :
a secret
Example : --input-file
$ echo 'a secret' | tss split -O /tmp/shares.txt
$ tss combine -I /tmp/shares.txt
RECOVERED SECRET METADATA
*************************
hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
hash_alg : SHA256
identifier : ae2983e30e0471fe
process_time : 0.47ms
threshold : 3
secret :
a secret
Example : interactive
$ cat /tmp/shares.txt
# THRESHOLD SECRET SHARING SHARES
# 2017-01-29T02:01:00Z
# https://github.com/grempe/tss-rb
tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoBbga2N__A9QOleLhC5R5b7stJ26iMPNpQ95YpmK-tWIrd-CYcrXGmcys=
tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoCGXsZkLOG7uDOVN1Zn46pqftX4noA8LfXugg14KBfSggYP9fw4Ce10YA=
tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoDFl3cwi80fpdh-I9eK3kNa8V9OlXX1Wx8y5a6bk2S0TDJzocr-1C3TWs=
tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoEEspmyzmbnrSr7v41FFlHVTqQ6dx4aho8q5T1CBHQbNimdCv3gVXS50I=
tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoFHeyjmaUpDsMEQqwyoK7jlwS6MfOvT8GX2gp6hvwd9-B3hXssmiLQe6k=
$ tss combine
Enter shares, one per line, and a dot (.) on a line by itself to finish :
share> tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoBbga2N__A9QOleLhC5R5b7stJ26iMPNpQ95YpmK-tWIrd-CYcrXGmcys=
share> tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoCGXsZkLOG7uDOVN1Zn46pqftX4noA8LfXugg14KBfSggYP9fw4Ce10YA=
share> tss~v1~b9f7f87bc83fd89b~3~YjlmN2Y4N2JjODNmZDg5YgIDACoDFl3cwi80fpdh-I9eK3kNa8V9OlXX1Wx8y5a6bk2S0TDJzocr-1C3TWs=
share> .
RECOVERED SECRET METADATA
*************************
hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
hash_alg : SHA256
identifier : b9f7f87bc83fd89b
process_time : 1.22ms
threshold : 3
secret :
a secret
The basic usage is as follows using the arguments described below.
shares = TSS.split(secret: secret,
threshold: threshold,
num_shares: num_shares,
identifier: identifier,
hash_alg: hash_alg,
padding: true)All arguments are passed as keys in a single Hash.
The secret (required) value must be provided as a String with either
a UTF-8 or US-ASCII encoding. The Byte length must be <= 65,486. You can
test this beforehand with 'my string secret'.bytes.to_a.length. Keep in mind
that this length also includes padding and the verification hash so your
secret may need to be shorter depending on the settings you choose.
Internally, the secret String will be converted to and processed as an Array
of Bytes. e.g. 'foo'.bytes.to_a
The num_shares and threshold values are Integers representing the total
number of shares desired, and how many of those shares are required to
re-create a secret. Both arguments must be Integers with a value
between 1-255 inclusive. The num_shares value must be
greater-than-or-equal-to the threshold value. If you don't pass in
these options they will be set to threshold = 3 and num_shares = 5 by default.
The identifier is a 1-16 Byte String that will be embedded in
each output share and should uniquely identify a secret. All shares output
from the same secret splitting operation will have the same identifier. This
value can be retrieved easily from a share header and should be assumed to be
known to shareholders. Nothing that leaks information about the secret should
be used as an identifier. If an identifier is not set, it will default
to the output of SecureRandom.hex(8) which is 8 random hex bytes (16 characters).
The hash_alg is a String that represents which cryptographic one-way
hash function should be embedded in shares. The hash is used to verify
that the re-combined secret is a match for the original at creation time.
The value of the hash is not available to shareholders until a secret is
successfully re-combined. The hash is calculated from the original secret
and then combined with it prior to secret splitting. This means that the hash
is protected the same way as the secret. The algorithm used is
secret || hash(secret). You can use one of NONE, SHA1, or SHA256.
The format arg takes an uppercase String Enum with either 'HUMAN' (default) or
'BINARY' values. This instructs the output of a split to either provide an
array of binary octet strings (a standard RTSS format for interoperability), or
a human friendly URL Safe Base 64 encoded version of that same binary output.
The HUMAN format can be easily shared in a tweet, email, or even a URL. The
HUMAN format is prefixed with tss~VERSION~IDENTIFIER~THRESHOLD~ to make it
easier to visually compare shares and see if they have matching identifiers and
if you have enough shares to reach the threshold.
The padding arg accepts a Boolean to indicate whether to apply PKCS#7
padding to the secret string. This is applied and removed automatically
by default and padding defaults to a block size of 16 bytes. You probably
never need to use this option to turn it off unless you are trying to
trade shares with the Python implementation.
Since TSS share data is essentially the same size as the original secret (with a known size header), the padding applied to smaller secrets may help mask the exact size of the secret itself from an attacker. Padding is not part of the RTSS spec so other TSS clients won't strip off the padding and may fail when recombining shares.
secret = 'foo bar baz'
threshold = 3
num_shares = 5
identifier = SecureRandom.hex(8)
hash_alg = 'SHA256'
format = 'HUMAN'
s = TSS.split(secret: secret, threshold: threshold, num_shares: num_shares, identifier: identifier, hash_alg: 'SHA256', format: format)
=> ["tss~v1~79923b087dab7fa2~3~Nzk5MjNiMDg3ZGFiN2ZhMgIDADEB2qA6IYq8yOGlPAl0B4MgRsVazZMWGLwRNgGMPKutOYbB0gjkVHNqbNYl-0l1f98W",
"tss~v1~79923b087dab7fa2~3~Nzk5MjNiMDg3ZGFiN2ZhMgIDADECvjwdUHc8MzqvIllR2Rj9TnnlN_2eRUzH6MUsd8ncua4jpXQ3FgM1hUmLHmrgHq0u",
"tss~v1~79923b087dab7fa2~3~Nzk5MjNiMDg3ZGFiN2ZhMgIDADEDAvNIUZ_hiftofyog257YDWds4q9MP14-rDCxQsauUyxqBtzur6Ch5-rSCHRPt4Dv",
"tss~v1~79923b087dab7fa2~3~Nzk5MjNiMDg3ZGFiN2ZhMgIDADEEF7zGEx0GSC6YLgVD6xcQispDCO_JTUSDFbsbpalopakh0FmTfmO-JJKGQSlJb1il",
"tss~v1~79923b087dab7fa2~3~Nzk5MjNiMDg3ZGFiN2ZhMgIDADEFq3OTEvXb8u9fc3Yy6ZE1ydTK3b0bN1Z6UU6GkKYaTytoc_FKx8AqRjHfVzfmxnVk"]
secret = TSS.combine(shares: s)
=> {:hash=>"dbd318c1c462aee872f41109a4dfd3048871a03dedd0fe0e757ced57dad6f2d7",
:hash_alg=>"SHA256",
:identifier=>"79923b087dab7fa2",
:process_time=>0.92,
:secret=>"foo bar baz",
:threshold=>3}The basic usage is:
secret = TSS.combine(shares: shares)All arguments are passed as keys in a single Hash. The return value is either
a Hash (with the :secret key being most important and other metadata provided
for informational purposes), or an TSS::Error Exception if the secret could
not be created and verified with its hash.
shares: (required) : Must be provided as an Array of encoded Share Byte Strings.
You must provide at least threshold shares as specified when the secret was
split. Providing too few shares will result in a TSS::ArgumentError exception
being raised. There are a large number of verifications that are performed on
shares provided to make sure they are valid and consistent with each other. An
Exception will be raised if any of these tests fail.
select_by: : If the number of shares provided as input to the secret
reconstruction operation is greater than the threshold M, then M
of those shares are selected for use in the operation. The method
used to select the shares can be chosen with the select_by: argument
which takes the following values as options:
select_by: 'FIRST' : If X shares are required by the threshold and more than X
shares are provided, then the first X shares in the Array of shares provided
will be used. All others will be discarded and the operation will fail if
those selected shares cannot recreate the secret.
select_by: 'SAMPLE' : If X shares are required by the threshold and more than X
shares are provided, then X shares will be randomly selected from the Array
of shares provided. All others will be discarded and the operation will
fail if those selected shares cannot recreate the secret.
select_by: 'COMBINATIONS' : If X shares are required, and more than X shares are
provided, then all possible combinations of the threshold number of shares
will be tried to see if the secret can be recreated.
Warning
This COMBINATIONS flexibility comes with a cost. All combinations of
threshold shares must be generated before processing. Due to the math
associated with combinations it is possible that the system would try to
generate a number of combinations that could never be generated or processed
in many times the life of the Universe. This option can only be used if the
possible combinations for the number of shares and the threshold needed to
reconstruct a secret result in a number of combinations that is small enough
to have a chance at being processed. If the number of combinations will be too
large an Exception will be raised before processing has even started. The default
maximum number of combinations that will be tried is 1,000,000.
Fun Fact
If 255 total shares are available, and the threshold value is 128, it would result in
2884329411724603169044874178931143443870105850987581016304218283632259375395
possible combinations of 128 shares that could be tried. That is almost as
many combinations (2.88 * 10^75) as there are Atoms in the Universe (10^80).
If the combine operation does not result in a secret being successfully
extracted, then a TSS::Error exception will be raised.
A great short read on big numbers is On the (Small) Number of Atoms in the Universe
Almost all methods in the program have strict contracts associated with them
that enforce argument presence, types, and value boundaries. This contract checking
is provided by the excellent Ruby Contracts gem. If a contract violation occurs a ParamContractError Exception will be raised.
The splitting and combining operations may also raise the following exception types:
TSS::NoSecretError, TSS::InvalidSecretHashError,
TSS::ArgumentError, TSS::Error
All Exceptions should include hints as to what went wrong in the
#message attribute.
TSS provides shares in a binary data format with the following fields, and
by default this binary data is wrapped in a 'HUMAN' text format:
Identifier. This field contains 16 octets. It identifies the secret
with which a share is associated. All of the shares associated
with a particular secret MUST use the same value Identifier. When
a secret is reconstructed, the Identifier fields of each of the
shares used as input MUST have the same value. The value of the
Identifier should be chosen so that it is unique, but the details
on how it is chosen are left as an exercise for the reader. The
characters a-zA-Z0-9.-_ are allowed in the identifier.
Hash Algorithm Identifier. This field contains a single octet that
indicates the hash function used in the RTSS processing, if any.
A value of 0 indicates that no hash algorithm was used, no hash
was appended to the secret, and no RTSS check should be performed
after the reconstruction of the secret.
Threshold. This field contains a single octet that indicates the
number of shares required to reconstruct the secret. This field
MUST be checked during the reconstruction process, and that
process MUST halt and return an error if the number of shares
available is fewer than the value indicated in this field.
Share Length. This field is two octets long. It contains the number
of octets in the Share Data field, represented as an unsigned
integer in network byte order.
Share Data. This field has a length that is a variable number of
octets. It contains the actual share data.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Identifier |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hash Alg. Id. | Threshold | Share Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: :
: Share Data :
: :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This data format has been tested for binary compatibility with the seb-m/tss Python implementation of TSS. There are test cases to ensure it remains compatible.
To make tss friendlier to use when sending shares to others, an enhanced
text wrapper around the RTSS binary data format is provided.
Shares formatted this way can easily be shared via most any communication channel.
The HUMAN data format is simply the same RTSS binary data, URL Safe Base64
encoded, and prefixed with a String thet contains tilde ~ separated elements.
The ~ is used as it is compatible with the URL Safe data and the allowed
characters in the rest of the human format string.
tss~VERSION~IDENTIFIER~THRESHOLD~BASE64_ENCODED_BINARY_SHARE
A typical share with this format looks like:
tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQB10mUbJPQZ94WpgKC2kKivfnSpCHTMr6BajbwzqOrvyMCpH0=
The amount of time it takes to split or combine secrets grows significantly as
the size of the secret and the total num_shares and threshold increase.
Splitting a secret with the maximum size of 2**16 - 2 (65,534) Bytes and
the maximum 255 shares may take an unreasonably long time to run. Splitting
and Combining involves at least num_shares**secret_bytes operations so
larger values can quickly result in huge processing time. If you need to
split large secrets into a large number of shares you should consider
running those operations in a background worker process or thread for
best performance. For example a 64kb file split into 255 shares,
with a threshold of 255 (the max for all three settings), can take
20 minutes to split and another 20 minutes to combine using a modern CPU.
A reasonable set of values seems to be what I'll call the 'rule of 64'. If you
keep the secret <= 64 Bytes, the threshold <= 64, and the num_shares <= 64
you can do a round-trip split and combine operation in ~250ms. These should
be very reasonable and secure max values for most use cases, even as part of a
web request response cycle. Remember, its recommended to split encryption keys,
not plaintext.
There are some simple benchmark tests to exercise things with rake bench.
After checking out the repo, run bin/setup to install dependencies. Then,
run rake test to run the tests. You can also run bin/console for an
interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install.
You can run the Command Line Interface (CLI) in development
with bundle exec bin/tss.
The formal release process can be found in RELEASE.md
Bug reports and pull requests are welcome on GitHub at https://github.com/grempe/tss-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
(c) 2016-2017 Glenn Rempe <[email protected]> (https://www.rempe.us/)
The gem is available as open source under the terms of the MIT License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE.txt file for the specific language governing permissions and limitations under the License.
This code is an implementation of the Threshold Secret Sharing, as specified in the Network Working Group Internet-Draft submitted by D. McGrew (draft-mcgrew-tss-03.txt). This code would not have been possible without this very well designed and documented specification. Many examples of the relevant text from the specification have been used as comments to annotate this source code.
Great respect to Sébastien Martini (@seb-m) for his seb-m/tss Python implementation of TSS. It was invaluable as a real-world reference implementation of the TSS Internet-Draft.