Metadata-Version: 2.1
Name: pygfssss
Version: 1.0.0
Summary: Python implementation of Shamir's Secret Sharing Scheme, using polynomials over GF(256)
Home-page: https://github.com/trianglee/pygfssss
Author: Nimrod Zimerman
Author-email: zimerman@fastmail.fm
License: Apache License 2.0
Platform: UNKNOWN
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# Overview

`pygfssss` is a Python 3 implementation of [Shamir's Secret Sharing Scheme](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing),
using polynomials over GF(256).

Shamir's Secret Sharing can be used to split a secret into multiple shares. A specified threshold amount of
shares can be used to reconstruct the original secret.

Having less than the threshold amount of shares doesn't provide any information on the secret (aside of
its size).

# Origins

`pygfssss` is heavily based on Mathias Herberts' PySSSS (https://github.com/hbs/PySSSS), extended with
the following features -
* Python 3 (only) support.
* Single X value used per share - for all bytes (instead of a different X value for every byte).
* Code simplified and clarified somewhat.
* Command line tool (`pygfssss`) provided.
* Compatibility with [`gfshare`](http://manpages.ubuntu.com/manpages/focal/man7/gfshare.7.html) -
  using 0x11d prime polynomial, `pygfsplit`/`pygfcombine` command line tools provided.
* Unit tests coverage.

# Installation

`pygfssss` is provided as a standard Python package. It can be installed with standard Python tools.

For example, Linux installation in a virtualenv directly from GitHub -

```
python -m virtualenv venv
venv/bin/python -m pip install git+https://github.com/trianglee/pygfssss
```

`pygfssss` runs on Linux and Windows.

# `pygfssss` Command Line Tool

`pygfssss` can be used to split and combine.

To split secret.txt into 5 shares, where any 3 are needed to reconstruct -

```
cat secret.txt | venv/bin/pygfssss split 3 5
```

(each output line is a different share).

To combine some of these shares back into the secret -

```
cat share1.txt share3.txt share5.txt | venv/bin/pygfssss combine
```

(if an insufficient number of shares is provided, the output would be random).

# `gfshare` Compatibility

[`gfshare`](http://manpages.ubuntu.com/manpages/focal/man7/gfshare.7.html) is a de-facto standard of
Shamir's Secret Sharing Scheme for Linux.

`pygfsplit` and `pygfcombine` of `pygfssss` are compatible with `gfsplit` and `gfcombine` 
of `gfshare`. Shares generated by `gfsplit` can be combined using `pygfcombine` 
and shares generated by `pygfsplit` can be combined using `gfcombine`.

This cross-compatibility allows users of both packages to know they have a reliable alternative 
implementation from a different source.

`pygfssss` command line tool generated shares are **not** directly compatible with `gfshare`, 
but it is trivial to convert them to be `gfshare` shares manually if needed -

1. The first byte (two digits) of each share is the file extension (in decimal format).
2. The rest of the bytes are the contents (in binary representation).

The following `bash` script can convert a set of `pygfssss` shares to a set of `gfshare` shares -

```
cat shares.txt |                                                             
while read in; do                                                            
  # Get share number from first two digits.                                  
  SHARE_NUM_HEX=$(echo "$in" | cut -c1-2)                                    
  # Convert it to decimal.                                                   
  SHARE_NUM_DEC=$((16#$SHARE_NUM_HEX))                                       
  # Pad with leading zeros.                                                  
  SHARE_NUM=$(printf "%03d" $SHARE_NUM_DEC)                                  
  # Convert the rest of the share bytes to binary and write to share file.   
  echo "$in" | cut -c3- | xxd -r -p > share.$SHARE_NUM                       
done                                                                         
```

# License

`pygfssss` is released under the Apache License, Version 2.


