From def37b067e3ea65a39aee7e03f13c833a6260df6 Mon Sep 17 00:00:00 2001 From: poing Date: Sun, 24 Mar 2024 10:49:55 +0900 Subject: [PATCH] Readme updates --- CONTRIBUTING.md | 6 +- README.md | 218 ++++++------------------------------------------ 2 files changed, 29 insertions(+), 195 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac867fe..6024526 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ js2pysecrets welcomes contributions from the community. -**You need PYTHON3!** +**You need Node.js and Python3!** This instructions are for linux base systems. (Linux, MacOS, BSD, etc.) ## Setting up your own fork of this repo. @@ -21,6 +21,10 @@ then activate it with `source .venv/bin/activate`. Run `make install` to install the project in develop mode. +## Install the Node.js package + +Run `npm install` to install `secrets.js-grempe` + ## Run the tests to ensure everything is working Run `make test` to run the tests. diff --git a/README.md b/README.md index 0f3329d..f63818c 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ # About -`js2pysecrets` is a port of the [`secrets.js-grempe`](https://github.com/grempe/secrets.js) JavaScript package to Python. +`js2pysecrets` is a port of the [`secrets.js`](https://github.com/grempe/secrets.js) JavaScript package to Python. This package allows for cross-platform compatible shares, *generated using [Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)*, to seamlessly interoperate between JavaScript and Python. @@ -87,210 +87,40 @@ comb = secrets.combine(shares[:2]) //convert back to UTF string: comb = secrets.hex2str(comb) -print(comb === pw) # => False +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 +print(comb == pw) # => True ``` ---- +## License -This is a `Python` implementation of [Shamir's threshold secret sharing scheme](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing), based **and compatible with** the `JavaScript` fork of `secrets.js` [*maintained by `grempe`*](https://github.com/grempe/secrets.js). Which is orginally based on the code created by `amper5and` on Github. The [original secrets.js can be found there](https://github.com/amper5and/secrets.js/). - -## Status - -The project is intended to create a `Python` version that is compatible with `secrets.js`. It's currently in the **DEVELOPMENT** stage and the framework is being built to *effectively* test and run the `JavaScript` from within the `Python` environment. - -All of the `JavaScript` functions can be called from *within* the `Python` environment. However, **there are limitations**! Most notably, you can **ONLY** call a single function, so some of the utility provided by the `JavaScript` version is not available. *In many cases, isn't even necessary*. - -Combing of shares is not working *yet*... - -### Requirements - -**`Node`** is **required**. - -To use this project in it's current state **and for testing**, `Node` is required on the system. `Node` is always required for testing. It's used to run the `JavaScript` in the local environment. - -## JavaScript Wrapper - -The `JavaScript` wrapper **is not** intended to allow subsequent commands. It spawns an *indvidual* `subprocess` of `Node` for each function called. - -```python -from js2pysecrets import setRNG, random - -setRNG('testRandom') # Output: True - -# New subprocess defaults to 'nodeCryptoRandomBytes' RNG -random(32) # Output: '24c177c8' -random(32) # Output: '89535434' -random(32) # Output: '306e0c23' -``` - -While the `Javascript` *does* have code to allow subsequent commands, the only **INTENDED** use is to force the use of `testRandom` for testing purposes. This can be accomplished by over-riding the function with the key-word argument `test=True`. - -```python -from js2pysecrets import random - -random(32, test=True) # Output: '075bcd15' -random(32, test=True) # Output: '075bcd15' -random(32, test=True) # Output: '075bcd15' -``` - -Additional commands **could** be added on a *case-by-case* basis, support is included in the wrapper. But the intention of the wrapper is mainly to assist testing of a full `Python` implementation to confirm `100%` compatibility with the `JavaScript` version. - -## 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: - -**Not everything is working yet...** - -```python -import js2pysecrets - -# generate a 512-bit key -# key = js2pysecrets.random(512) // => key is a hex string -key = js2pysecrets.random(512) -print(key) - -# split into 10 shares with a threshold of 5 -# shares = js2pysecrets.share(key, 10, 5) -# => shares = ['801xxx...xxx','802xxx...xxx','803xxx...xxx','804xxx...xxx','805xxx...xxx'] -shares = js2pysecrets.share(key, 10, 5) -print(shares) - -# // combine 4 shares -# var comb = secrets.combine(shares.slice(0, 4)) -# console.log(comb === key) // => false -# -# // combine 5 shares -# comb = secrets.combine(shares.slice(4, 9)) -# console.log(comb === key) // => true -# -# // combine ALL shares -# comb = secrets.combine(shares) -# console.log(comb === key) // => true -# -# // create another share with id 8 -# var newShare = secrets.newShare(8, shares) // => newShare = '808xxx...xxx' -# -# // reconstruct using 4 original shares and the new share: -# comb = secrets.combine(shares.slice(1, 5).concat(newShare)) -# console.log(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: - -**Things really start to break here...** -*Big and reversed endianness for the `JS` str2hex* - -```python -import js2pysecrets - -# var pw = "<>" -pw = "<>" - -# convert the text into a hex string -# jsHex = secrets.str2hex(pw) // => hex string -jsHex = js2pysecrets.str2hex(pw) -print(jsHex) - -# Notice how the JS uses an unconventional str2hex method -pyHex = pw.encode('utf-16').hex().lstrip('fe') # Stripped off the BOM -print(pyHex) - -# split into 5 shares, with a threshold of 3 -# shares = js2pysecrets.share(jsHex, 5, 3) -shares = js2pysecrets.share(jsHex, 5, 3) -print(shares) - -# // combine 2 shares: -# var comb = secrets.combine(shares.slice(1, 3)) -# -# //convert back to UTF string: -# comb = secrets.hex2str(comb) -# console.log(comb === pw) // => false -# -# // combine 3 shares: -# comb = secrets.combine([shares[1], shares[3], shares[4]]) -# -# //convert back to UTF string: -# comb = secrets.hex2str(comb) -# console.log(comb === pw) // => true -``` - -## Install it from PyPI - -```bash -# not published yet - still in development -# pip install js2pysecrets -``` - -## Usage - -```py -import js2pysecrets - -js2pysecrets.rand(32) -js2pysecrets.share('10AF', 6, 3) -``` +`js2pysecrets` is released under the MIT License. See the `LICENSE` file. ## Development and Testing Read the [CONTRIBUTING.md](CONTRIBUTING.md) file. - - ----- -# Python Project Template - -A low dependency and really simple to start project template for Python Projects. - -See also -- [Flask-Project-Template](https://github.com/rochacbruno/flask-project-template/) for a full feature Flask project including database, API, admin interface, etc. -- [FastAPI-Project-Template](https://github.com/rochacbruno/fastapi-project-template/) The base to start an openapi project featuring: SQLModel, Typer, FastAPI, JWT Token Auth, Interactive Shell, Management Commands. - -### HOW TO USE THIS TEMPLATE - -> **DO NOT FORK** this is meant to be used from **[Use this template](https://github.com/rochacbruno/python-project-template/generate)** feature. - -1. Click on **[Use this template](https://github.com/rochacbruno/python-project-template/generate)** -3. Give a name to your project - (e.g. `my_awesome_project` recommendation is to use all lowercase and underscores separation for repo names.) -3. Wait until the first run of CI finishes - (Github Actions will process the template and commit to your new repo) -4. If you want [codecov](https://about.codecov.io/sign-up/) Reports and Automatic Release to [PyPI](https://pypi.org) - On the new repository `settings->secrets` add your `PYPI_API_TOKEN` and `CODECOV_TOKEN` (get the tokens on respective websites) -4. Read the file [CONTRIBUTING.md](CONTRIBUTING.md) -5. Then clone your new project and happy coding! - -> **NOTE**: **WAIT** until first CI run on github actions before cloning your new project. - -### What is included on this template? - -- ๐Ÿ–ผ๏ธ Templates for starting multiple application types: - * **Basic low dependency** Python program (default) [use this template](https://github.com/rochacbruno/python-project-template/generate) - * **Flask** with database, admin interface, restapi and authentication [use this template](https://github.com/rochacbruno/flask-project-template/generate). - **or Run `make init` after cloning to generate a new project based on a template.** -- ๐Ÿ“ฆ A basic [setup.py](setup.py) file to provide installation, packaging and distribution for your project. - Template uses setuptools because it's the de-facto standard for Python packages, you can run `make switch-to-poetry` later if you want. -- ๐Ÿค– A [Makefile](Makefile) with the most useful commands to install, test, lint, format and release your project. -- ๐Ÿ“ƒ Documentation structure using [mkdocs](http://www.mkdocs.org) -- ๐Ÿ’ฌ Auto generation of change log using **gitchangelog** to keep a HISTORY.md file automatically based on your commit history on every release. -- ๐Ÿ‹ A simple [Containerfile](Containerfile) to build a container image for your project. - `Containerfile` is a more open standard for building container images than Dockerfile, you can use buildah or docker with this file. -- ๐Ÿงช Testing structure using [pytest](https://docs.pytest.org/en/latest/) -- โœ… Code linting using [flake8](https://flake8.pycqa.org/en/latest/) -- ๐Ÿ“Š Code coverage reports using [codecov](https://about.codecov.io/sign-up/) -- ๐Ÿ›ณ๏ธ Automatic release to [PyPI](https://pypi.org) using [twine](https://twine.readthedocs.io/en/latest/) and github actions. -- ๐ŸŽฏ Entry points to execute your program using `python -m ` or `$ js2pysecrets` with basic CLI argument parsing. -- ๐Ÿ”„ Continuous integration using [Github Actions](.github/workflows/) with jobs to lint, test and release your project on Linux, Mac and Windows environments. - -> Curious about architectural decisions on this template? read [ABOUT_THIS_TEMPLATE.md](ABOUT_THIS_TEMPLATE.md) -> If you want to contribute to this template please open an [issue](https://github.com/rochacbruno/python-project-template/issues) or fork and send a PULL REQUEST. - -[โค๏ธ Sponsor this project](https://github.com/sponsors/rochacbruno/) - +## To Do + +- Restructure and split into seterate modules + - Move the backend functions outside the main module +- Restructure and clean-up the tests + +## Changelog + +- 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](https://squidfunk.github.io/mkdocs-material/) + - Converted `secrets.js` 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](https://github.com/rochacbruno/python-project-template) \ No newline at end of file