poing / js2pysecrets

Python implementation based on grempe/secrets.js with a focus on cross-compatibility.

About

js2pysecrets is a port of the secrets.js-grempe JavaScript package to Python.

This package allows for cross-platform compatible shares, generated using Shamir's Secret Sharing, to seamlessly interoperate between JavaScript and Python.

Function names and arguments used in the JavaScript package have been maintained for consistency and maintainability.

The functionality is essentially the same as the JavaScript package, with an exception around random number generation. Python doesn't have to adapt to different environments for random number generation like the JavaScript does.

For additional details, see the documentation.

Installation and Usage

Install the PyPI package:

pip install js2pysecrets

Import the library:

import js2pysecrets as secrets

Examples

Divide a 512-bit key, expressed in hexadecimal form, into 10 shares, requiring that any 5 of them are necessary to reconstruct the original key:

import js2pysecrets as secrets

# generate a 512-bit key
key = secrets.random(512) 
print(key) # => key is a hex string

# split into 10 shares with a threshold of 5
shares = secrets.share(key, 10, 5)
print(shares) # => ['801xxx...xxx','802xxx...xxx', ... ,'809xxx...xxx','80axxx...xxx']

# combine 4 shares
comb = secrets.combine(shares[:4])
print(comb == key) # => False

# combine 5 shares
comb = secrets.combine(shares[:5])
print(comb == key) # => True

# combine ALL shares
comb = secrets.combine(shares)
print(comb == key) # => True

# create another share with id 8
new_share = secrets.newShare(8, shares)
print(new_share) # => '808xxx...xxx'

# reconstruct using 4 original shares and the new share:
comb = secrets.combine(shares[:4] + [new_share])
print(comb == key) # => True

Divide a password containing a mix of numbers, letters, and other characters, requiring that any 3 shares must be present to reconstruct the original password:

import js2pysecrets as secrets

pw = "<<PassWord123>>"

# convert the text into a hex string
pwHex = secrets.str2hex(pw)
print(pwHex) # => hex string

# split into 5 shares, with a threshold of 3
shares = secrets.share(pwHex, 5, 3)
print(shares) # => ['801xxx...xxx','802xxx...xxx', ... ,'804xxx...xxx','805xxx...xxx']

# combine 2 shares:
comb = secrets.combine(shares[:2])

# convert back to UTF string:
comb = secrets.hex2str(comb)
print(comb == pw) # => False

# combine 3 shares:
comb = secrets.combine([shares[1], shares[3], shares[4]])

# convert back to UTF string:
comb = secrets.hex2str(comb)
print(comb == pw) # => True

License

js2pysecrets is released under the MIT License. See the LICENSE file.

Development and Testing

Read the CONTRIBUTING.md file.

To Do

• Restructure and clean-up the tests
• Documentation

Changelog

• 0.1.x

  • Cleaned up the code an some tests

• 0.0.x

  • Documentation, documentation, documentation...
  • Configured automatic release to PyPI
  • Converted secrets.js¹ to Python
  • Disabled the tests_win GitHub action, #24
  • Moved docs to use Material for MkDocs
  • Converted secrets.js-grempe Jasmine tests to pytest versions
  • Added package.json as a stub
  • Built Node.js wrapper for testing
  • Enable CodeCov
  • Started with the Python Project Template

Footnotes

1. secrets.js-grempe and secrets.js are basically the same. The difference is the execution environment, JavaScript or Node.js. ↩

js2pysecrets's Issues

secrets.js: Windows Testing: UTF8 Failure

After converting tests from secrets.js, found tests_win in the GitHub workflow is failing UTF8 tests. It appears to be caused by Windows defaulting to CP-1252 encoding.

Since these are converted tests from the secrets.js package, going to apply a workaround to skip the failed tests.

Will focus efforts on dealing with the UTF8 if/when issue are encountered affect the Python implementation.

Workaround

Currently skipping the windows testing.

@pytest.mark.skipif(
    sys.platform.startswith("win"), reason="Windows defaults to CP-1252"
)
def test_with_UTF8():
    ...

@pytest.mark.skipif(
    sys.platform.startswith("win"), reason="Windows defaults to CP-1252"
)
def test_initialization():
    ...