Subrosa Documentation

Subrosa is an implementation of Shamir’s Secret Sharing.

Tutorial

You can split the secret using split_secret() into shares. For this you need the secret as a byte string, you need the number of shares you want and the threshold - how many shares should be necessary to recover the secret.

For this example the secret will be the byte string b’supersecretpassword’, we will create three shares and two of them should be required to recover the secret.

>>> shares = split_secret(b'supersecretpassword', 2, 3)

split_secret returns a list of Share objects. We can store these objects in a file or a database as a byte string, which we create using the bytes() function.

>>> binary_shares = [bytes(share) for share in shares]

The byte strings have roughly the same length as the secret. They’re also versioned, so that the format can be changed in the future but old shares can still be easily supported by future versions.

If you’re retrieving these shares as byte strings, you can turn them back into objects using Share.from_bytes().

>>> shares = [Share.from_bytes(share) for share in binary_shares]

To recover the secret simply pass at least as many shares to recover_secret() as you’ve defined should be required for this, when splitting the secret.

>>> recover_secret(shares[:2])
b'supersecretpassword'

API Reference

subrosa.split_secret(secret, threshold, share_count)

Splits up the secret, a byte string, into share_count shares from which the secret can be recovered with at least threshold shares.

Returns a list of Share objects, each representing a share.

Parameters:
  • secret – The secret byte string to be split up.
  • threshold – The number of shares shall be needed to recover the secret. This value must be in the range 2 <= threshold < 256.
  • share_count – The number of shares to be returned. This value must be in the range threshold <= share_count < 256.

A ValueError will be raised, if secret is an empty string or if threshold or share_count has a value outside of the allowed range.

subrosa.recover_secret(shares)

Recovers a secret from the given shares, provided at least as many as threshold shares are provided.

If not enough shares are provided or the shares are incompatible (cannot possibly refer to the same secret) a ValueError is raised.

subrosa.add_share(shares, x)

Returns a new (or reconstructed) share for an already shared secret.

Assuming you’ve split up some secret into three shares, these shares will be the shares 1, 2 and 3:

>>> shares = split_secret(b'secret', 2, 3)
>>> [share.x for share in shares]
[1, 2, 3]

You can then create a new fourth share or recreate a share you may have lost:

>>> add_share(shares, 4).x
4
>>> add_share(shares[1:], 1).x
1

Take care to keep track of which shares are in circulation, to make sure that you’re generating shares that are actually new.

Parameters:x – The share to be returned. This value must be in the range 1 <= x < 256.

If not enough shares are provided (as defined by the threshold when splitting the secret) or the shares are incompatible (don’t refer to the same secret) a ValueError is raised.

class subrosa.Share(threshold, x, ys)

Represents a share of a secret.

Can be turned into a byte string using bytes(). Use this along with from_bytes() to store shares.

classmethod from_bytes(bytestring)

Returns a Share instance given a byte string representation of a share.

This method will raise a NotImplementedError, if the byte string was generated with a newer version of this library (or the byte string is not a valid share.)

This method will raise a ValueError, if the byte string is not a valid share.

Additional Information