| Name | thRSAhold JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Hybrid RSA Threshold Encryption Library |
| upload_time | 2024-11-23 12:49:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | GPLv3 |
| keywords |
threshold
encryption
rsa
aes
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Threshold RSA Encryption Library
ThRSAhold is a compact Python library that implements a hybrid RSA threshold encryption scheme for arbitrary plaintext length.
Threshold encryption is an asymmetric encryption scheme where a *public key* is used to encrypt a plaintext message. However, there exist no single *private key* to decrypt a ciphertext. Instead, the decryption requires the collaboration of at least *k* of private key share holders, where *k* and the total number of key share holders *l* is defined during key generation.
If the plaintext is too long for the RSA key size (2048 bit by default), thRSAhold uses an hybrid encryption scheme, where an AES key is generated and prepended to the plaintext. This AES key is used to encrypt the excess plaintext in GCM mode. All plaintexts are padded with PKCS#1 v1.5.
The implementation of the key generation, threshold RSA encryption and decryption, follows the description of threshold signatures in Victor Shoup's paper titled "Practical Threshold Signatures" [1].
One advantage of thRSAhold is that encryption can be performed by any standard RSA and AES implementation, which enable fast encryption through e.g., openssl. See the [README](https://github.com/eric-wagner/thRSAhold/blob/main/src/openssl/README.md) in the ```openssl``` directory on [GitHub](https://github.com/eric-wagner/thRSAhold) for a thRSAhold-compatible openssl implementation of the encryption procedure in C.
**Warning:** This implementation is not side-channel resilient or memory-safe and has not been audited. It should thus not be used for commercial applications!
## Getting Started
The easiest way to getting started is to just download thRSAhold via pip:
```
pip install thRSAhold
```
Alternatively, you can also download the source code of thRSAhold on [GitHub](https://github.com/eric-wagner/thRSAhold). In that case make sure that `pycryptodome` is installed:
This library was tested with `pycryptodome` version 3.20.0.
## Example
A simple example of encrypting and decrypting a short message with thRSAhold. Note that privkeys should most likely be securely distributed to different entities, which locally compute the decryption shares that can then be verified and combined by anyone knowing the public key.
```
import thRSAhold
plaintext = b"A short test message."
k = 5 # threshold of required shares
l = 10 # amount of shares
pubkey, privkeys = thRSAhold.generate_key_shares(k, l)
ciphertext = pubkey.encrypt(plaintext)
shares = []
for i in range(k):
s = privkeys[i].compute_share( ciphertext )
shares.append(s)
for share in shares:
pubkey.verify_zkp(share, ciphertext)
plaintext = pubkey.combine_shares(shares, ciphertext)
print( plaintext )
```
## Functionality
In the following, the functionalities of the different thRSAhold components are described in more detail.
### Key generation
To generate the *public encryption key* and the *private decryption key shares*, thRSAhold offers the ```generate_key_shares(k,l)``` function. The parameter *k* denotes how many *decryption shares* are required for decryption, and the parameter *l* denotes how many *private decryption key* shares exist. The function returns one ```PublicKey``` object and a list of *l* ```PrivateKey``` objects.
At this time, thRSAhold does not support distributed key generation.
### Class: PublicKey
> encrypt(plaintext)
> - plaintext - the plaintext bytes to be encrypted
> - Returns: the encrypted plaintext (ciphertext)
> serialize(self)
> - Returns: a serialized string of the ```PublicKey``` object
> deserialize(cls, key)
> - key - a serialized ```PublicKey``` object
> - Returns: a ```PublicKey``` object
> to_file(self, path)
> - path - path of the file where the ```PublicKey``` object should be stored
> from_file(cls, path)
> - path - path of the file where the ```PublicKey``` object is stored
> - Returns: a PublicKey object
> to_pem_file(self, path)
> - path - path of the file where the ```PublicKey``` object should be stored in .pem format
> to_der_file(self, path)
> - path - path of the file where the ```PublicKey``` object object should be stored in .der format
> verify_zkp(self, share, ciphertext)
> - share - a ```DecryptionShare``` object
> - ciphertext - the ciphertext
> - Returns: True if the decryption share is authentic, False otherwise
> combine_shares(self, shares, ciphertext)
> - shares - a least of at least *k* authentic ```DecryptionShare``` objects, each generated from a different ```PrivateKey```
> - ciphertext - the ciphertext
> - Returns: the plaintext
### Class: PrivateKey
> compute_share(self, ciphertext)
> - ciphertext - the ciphertext
> - Returns: a ```DecryptionShare``` object
> serialize(self)
> - Returns: a serialized string of the ```PrivateKey``` object
> deserialize(cls, key)
> - key - a serialized ```PrivateKey``` object
> - Returns: a ```PrivateKey``` object
> to_file(self, path)
> - path - path of the file where the ```PrivateKey``` object should be stored
> from_file(cls, path)
> - path - path of the file where the ```PrivateKey``` object is stored
> - Returns: a ```PrivateKey``` object
### Class: DecryptionShare
> serialize(self)
> - Returns: a serialized string of the ```DecryptionShare``` object
> deserialize(cls, key)
> - key - a serialized ```DecryptionShare``` object
> - Returns: a ```DecryptionShare``` object
> to_file(self, path)
> - path - path of the file where the ```DecryptionShare``` object should be stored
> from_file(cls, path)
> - path - path of the file where the ```DecryptionShare``` object is stored
> - Returns: a ```DecryptionShare``` object
## Contact
Eric Wagner - eric.wagner@fkie.fraunhofer.de
## References
[1] Shoup, V. Practical Threshold Signatures. In International Conference on
the Theory and Applications of Cryptographic Techniques (2000), Springer,
pp. 207–220.
Raw data
{
"_id": null,
"home_page": null,
"name": "thRSAhold",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "threshold, encryption, RSA, AES",
"author": null,
"author_email": "Eric Wagner <eric.wagner@fkie.fraunhofer.de>",
"download_url": "https://files.pythonhosted.org/packages/bc/73/f64f171f9a90c2fd215afe0273d182e51f3bcfa8abbef41c9093e3eaa3b8/thrsahold-0.1.0.tar.gz",
"platform": null,
"description": "# Threshold RSA Encryption Library\n\nThRSAhold is a compact Python library that implements a hybrid RSA threshold encryption scheme for arbitrary plaintext length. \n\nThreshold encryption is an asymmetric encryption scheme where a *public key* is used to encrypt a plaintext message. However, there exist no single *private key* to decrypt a ciphertext. Instead, the decryption requires the collaboration of at least *k* of private key share holders, where *k* and the total number of key share holders *l* is defined during key generation.\n\nIf the plaintext is too long for the RSA key size (2048 bit by default), thRSAhold uses an hybrid encryption scheme, where an AES key is generated and prepended to the plaintext. This AES key is used to encrypt the excess plaintext in GCM mode. All plaintexts are padded with PKCS#1 v1.5.\n\nThe implementation of the key generation, threshold RSA encryption and decryption, follows the description of threshold signatures in Victor Shoup's paper titled \"Practical Threshold Signatures\" [1].\n\nOne advantage of thRSAhold is that encryption can be performed by any standard RSA and AES implementation, which enable fast encryption through e.g., openssl. See the [README](https://github.com/eric-wagner/thRSAhold/blob/main/src/openssl/README.md) in the ```openssl``` directory on [GitHub](https://github.com/eric-wagner/thRSAhold) for a thRSAhold-compatible openssl implementation of the encryption procedure in C.\n\n**Warning:** This implementation is not side-channel resilient or memory-safe and has not been audited. It should thus not be used for commercial applications! \n\n## Getting Started\n\nThe easiest way to getting started is to just download thRSAhold via pip:\n```\npip install thRSAhold\n```\n\nAlternatively, you can also download the source code of thRSAhold on [GitHub](https://github.com/eric-wagner/thRSAhold). In that case make sure that `pycryptodome` is installed:\n\nThis library was tested with `pycryptodome` version 3.20.0.\n\n## Example\n\nA simple example of encrypting and decrypting a short message with thRSAhold. Note that privkeys should most likely be securely distributed to different entities, which locally compute the decryption shares that can then be verified and combined by anyone knowing the public key.\n\n```\nimport thRSAhold\n\nplaintext = b\"A short test message.\"\n\nk = 5 # threshold of required shares\nl = 10 # amount of shares\n\npubkey, privkeys = thRSAhold.generate_key_shares(k, l)\n\nciphertext = pubkey.encrypt(plaintext)\n\nshares = []\nfor i in range(k):\n s = privkeys[i].compute_share( ciphertext )\n shares.append(s)\n\nfor share in shares:\n pubkey.verify_zkp(share, ciphertext)\n\nplaintext = pubkey.combine_shares(shares, ciphertext)\n\nprint( plaintext )\n```\n\n## Functionality\n\nIn the following, the functionalities of the different thRSAhold components are described in more detail.\n\n### Key generation\n\nTo generate the *public encryption key* and the *private decryption key shares*, thRSAhold offers the ```generate_key_shares(k,l)``` function. The parameter *k* denotes how many *decryption shares* are required for decryption, and the parameter *l* denotes how many *private decryption key* shares exist. The function returns one ```PublicKey``` object and a list of *l* ```PrivateKey``` objects.\n\nAt this time, thRSAhold does not support distributed key generation.\n\n### Class: PublicKey\n\n> encrypt(plaintext)\n> - plaintext - the plaintext bytes to be encrypted\n> - Returns: the encrypted plaintext (ciphertext)\n\n> serialize(self)\n> - Returns: a serialized string of the ```PublicKey``` object\n\n> deserialize(cls, key)\n> - key - a serialized ```PublicKey``` object\n> - Returns: a ```PublicKey``` object\n\n> to_file(self, path)\n> - path - path of the file where the ```PublicKey``` object should be stored \n\n> from_file(cls, path)\n> - path - path of the file where the ```PublicKey``` object is stored \n> - Returns: a PublicKey object\n\n> to_pem_file(self, path)\n> - path - path of the file where the ```PublicKey``` object should be stored in .pem format \n\n> to_der_file(self, path)\n> - path - path of the file where the ```PublicKey``` object object should be stored in .der format \n \n> verify_zkp(self, share, ciphertext)\n> - share - a ```DecryptionShare``` object\n> - ciphertext - the ciphertext\n> - Returns: True if the decryption share is authentic, False otherwise\n\n> combine_shares(self, shares, ciphertext)\n> - shares - a least of at least *k* authentic ```DecryptionShare``` objects, each generated from a different ```PrivateKey```\n> - ciphertext - the ciphertext\n> - Returns: the plaintext\n\n\n### Class: PrivateKey\n\n> compute_share(self, ciphertext)\n> - ciphertext - the ciphertext\n> - Returns: a ```DecryptionShare``` object\n\n> serialize(self)\n> - Returns: a serialized string of the ```PrivateKey``` object\n\n> deserialize(cls, key)\n> - key - a serialized ```PrivateKey``` object\n> - Returns: a ```PrivateKey``` object\n\n> to_file(self, path)\n> - path - path of the file where the ```PrivateKey``` object should be stored \n\n> from_file(cls, path)\n> - path - path of the file where the ```PrivateKey``` object is stored \n> - Returns: a ```PrivateKey``` object\n\n### Class: DecryptionShare\n\n> serialize(self)\n> - Returns: a serialized string of the ```DecryptionShare``` object\n\n> deserialize(cls, key)\n> - key - a serialized ```DecryptionShare``` object\n> - Returns: a ```DecryptionShare``` object\n\n> to_file(self, path)\n> - path - path of the file where the ```DecryptionShare``` object should be stored \n\n> from_file(cls, path)\n> - path - path of the file where the ```DecryptionShare``` object is stored \n> - Returns: a ```DecryptionShare``` object\n\n## Contact\n\nEric Wagner - eric.wagner@fkie.fraunhofer.de\n\n## References\n\n[1] Shoup, V. Practical Threshold Signatures. In International Conference on\nthe Theory and Applications of Cryptographic Techniques (2000), Springer,\npp. 207\u2013220.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Hybrid RSA Threshold Encryption Library",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/eric-wagner/thRSAhold"
},
"split_keywords": [
"threshold",
" encryption",
" rsa",
" aes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93e4851b22c7b26faab52487fbee8563d548dee11aeddcbaec47368cd8cdda88",
"md5": "02bd9e2a41d52808b9e5bdb0875be5f7",
"sha256": "b5dd6b4f4805b51e34529b0a9bcfacd9f8be29e349b069733af8530363b7277b"
},
"downloads": -1,
"filename": "thRSAhold-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02bd9e2a41d52808b9e5bdb0875be5f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18781,
"upload_time": "2024-11-23T12:49:20",
"upload_time_iso_8601": "2024-11-23T12:49:20.956891Z",
"url": "https://files.pythonhosted.org/packages/93/e4/851b22c7b26faab52487fbee8563d548dee11aeddcbaec47368cd8cdda88/thRSAhold-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bc73f64f171f9a90c2fd215afe0273d182e51f3bcfa8abbef41c9093e3eaa3b8",
"md5": "f60ac16fa6b7b7a341141d1c404aa550",
"sha256": "b0d756681c27ec62c5bbcb96c77080c13372dd1b438682d18190687290458250"
},
"downloads": -1,
"filename": "thrsahold-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f60ac16fa6b7b7a341141d1c404aa550",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18785,
"upload_time": "2024-11-23T12:49:22",
"upload_time_iso_8601": "2024-11-23T12:49:22.311110Z",
"url": "https://files.pythonhosted.org/packages/bc/73/f64f171f9a90c2fd215afe0273d182e51f3bcfa8abbef41c9093e3eaa3b8/thrsahold-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 12:49:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eric-wagner",
"github_project": "thRSAhold",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "thrsahold"
}
