# `fips203` Python module
This Python module provides an implementation of FIPS 203, the
Module-Lattice-based Key Encapsulation Mechanism Standard.
The underlying mechanism is intended to offer "post-quantum"
asymmetric encryption and decryption.
## Example
The following example shows using the standard ML-KEM algorithm to
produce identical 32-byte shared secrets:
```
from fips203 import ML_KEM_512
(encapsulation_key, decapsulation_key) = ML_KEM_512.keygen()
(ciphertext, shared_secret_1) = encapsulation_key.encaps()
shared_secret_2 = decapsulation_key.decaps(ciphertext)
assert(shared_secret_1 == shared_secret_2)
```
Key generation can also be done deterministically, by passing a
`SEED_SIZE`-byte seed (the concatenation of d and z) to `keygen`:
```
from fips203 import ML_KEM_512, Seed
seed1 = Seed() # Generate a random seed
(ek1, dk1) = ML_KEM_512.keygen(seed1)
seed2 = Seed(b'\x00'*ML_KEM_512.SEED_SIZE) # This seed is clearly not a secret!
(ek2, dk2) = ML_KEM_512.keygen(seed2)
```
Encapsulation keys, decapsulation keys, seeds, and ciphertexts can all
be serialized by accessing them as `bytes`, and deserialized by
initializing them with the appropriate size bytes object.
A serialization example:
```
from fips203 import ML_KEM_768
seed = Seed()
(ek,dk) = ML_KEM_768.keygen(seed)
with open('encapskey.bin', 'wb') as f:
f.write(bytes(ek))
with open('decapskey.bin', 'wb') as f:
f.write(bytes(dk))
with open('seed.bin', 'wb') as f:
f.write(bytes(seed)
```
A deserialization example, followed by use:
```
import fips203
with open('encapskey.bin', 'b') as f:
ekdata = f.read()
ek = fips203.EncapsulationKey(ekdata)
(ct, ss) = ek.Encaps()
```
The expected sizes (in bytes) of the different objects in each
parameter set can be accessed with `EK_SIZE`, `DK_SIZE`, `CT_SIZE`,
`SEED_SIZE`, and `SS_SIZE`:
```
from fips203 import ML_KEM_768
print(f"ML-KEM-768 Ciphertext size (in bytes) is {ML_KEM_768.CT_SIZE}")
```
## Implementation Notes
This is a wrapper around libfips203, built from the Rust fips203-ffi crate.
If that library is not installed in the expected path for libraries on
your system, any attempt to use this module will fail.
This module should have reasonable type annotations and docstrings for
the public interface. If you discover a problem with type
annotations, or see a way that this kind of documentation could be
improved, please report it!
## See Also
- https://doi.org/10.6028/NIST.FIPS.203.ipd
- https://github.com/integritychain/fips203
## Bug Reporting
Please report issues at https://github.com/integritychain/fips203/issues
Raw data
{
"_id": null,
"home_page": null,
"name": "fips203",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "cryptography, encryption, FIPS, FIPS203, KEM, lattice, module-lattice, post-quantum",
"author": null,
"author_email": "Daniel Kahn Gillmor <dkg@fifthhorseman.net>",
"download_url": "https://files.pythonhosted.org/packages/d3/2c/699fbac865ec94ad04c94913bfc0a6d013d8de5bb50bced044c054857d3a/fips203-0.4.1.tar.gz",
"platform": null,
"description": "# `fips203` Python module\n\nThis Python module provides an implementation of FIPS 203, the\nModule-Lattice-based Key Encapsulation Mechanism Standard.\n\nThe underlying mechanism is intended to offer \"post-quantum\"\nasymmetric encryption and decryption.\n\n## Example\n\nThe following example shows using the standard ML-KEM algorithm to\nproduce identical 32-byte shared secrets:\n\n```\nfrom fips203 import ML_KEM_512\n\n(encapsulation_key, decapsulation_key) = ML_KEM_512.keygen()\n(ciphertext, shared_secret_1) = encapsulation_key.encaps()\nshared_secret_2 = decapsulation_key.decaps(ciphertext)\nassert(shared_secret_1 == shared_secret_2)\n```\n\n\nKey generation can also be done deterministically, by passing a\n`SEED_SIZE`-byte seed (the concatenation of d and z) to `keygen`:\n\n```\nfrom fips203 import ML_KEM_512, Seed\n\nseed1 = Seed() # Generate a random seed\n(ek1, dk1) = ML_KEM_512.keygen(seed1)\n\nseed2 = Seed(b'\\x00'*ML_KEM_512.SEED_SIZE) # This seed is clearly not a secret!\n(ek2, dk2) = ML_KEM_512.keygen(seed2)\n```\n\n\nEncapsulation keys, decapsulation keys, seeds, and ciphertexts can all\nbe serialized by accessing them as `bytes`, and deserialized by\ninitializing them with the appropriate size bytes object.\n\nA serialization example:\n\n```\nfrom fips203 import ML_KEM_768\n\nseed = Seed()\n(ek,dk) = ML_KEM_768.keygen(seed)\nwith open('encapskey.bin', 'wb') as f:\n f.write(bytes(ek))\nwith open('decapskey.bin', 'wb') as f:\n f.write(bytes(dk))\nwith open('seed.bin', 'wb') as f:\n f.write(bytes(seed)\n```\n\nA deserialization example, followed by use:\n\n```\nimport fips203\n\nwith open('encapskey.bin', 'b') as f:\n ekdata = f.read()\n\nek = fips203.EncapsulationKey(ekdata)\n(ct, ss) = ek.Encaps()\n```\n\nThe expected sizes (in bytes) of the different objects in each\nparameter set can be accessed with `EK_SIZE`, `DK_SIZE`, `CT_SIZE`,\n`SEED_SIZE`, and `SS_SIZE`:\n\n```\nfrom fips203 import ML_KEM_768\n\nprint(f\"ML-KEM-768 Ciphertext size (in bytes) is {ML_KEM_768.CT_SIZE}\")\n```\n\n## Implementation Notes\n\nThis is a wrapper around libfips203, built from the Rust fips203-ffi crate.\n\nIf that library is not installed in the expected path for libraries on\nyour system, any attempt to use this module will fail.\n\nThis module should have reasonable type annotations and docstrings for\nthe public interface. If you discover a problem with type\nannotations, or see a way that this kind of documentation could be\nimproved, please report it!\n\n## See Also\n\n- https://doi.org/10.6028/NIST.FIPS.203.ipd\n- https://github.com/integritychain/fips203\n\n## Bug Reporting\n\nPlease report issues at https://github.com/integritychain/fips203/issues\n",
"bugtrack_url": null,
"license": null,
"summary": "ML-KEM (FIPS203) -- asymmetric, quantum-secure encryption",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/integritychain/fips203/tree/main/ffi/python",
"Issues": "https://github.com/integritychain/fips203/issues",
"Repository": "https://github.com/integritychain/fips203.git"
},
"split_keywords": [
"cryptography",
" encryption",
" fips",
" fips203",
" kem",
" lattice",
" module-lattice",
" post-quantum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2acaf27ec8192f3669a20b6b178e711a09ed51da4bc12fb0d69b7e4482054280",
"md5": "585c658a1e911184b1be66488af14319",
"sha256": "4943691af72bec7214982a492a625f1dd069f440a9aec901fde9f8c4c500ef22"
},
"downloads": -1,
"filename": "fips203-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "585c658a1e911184b1be66488af14319",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6353,
"upload_time": "2024-10-17T21:56:21",
"upload_time_iso_8601": "2024-10-17T21:56:21.832310Z",
"url": "https://files.pythonhosted.org/packages/2a/ca/f27ec8192f3669a20b6b178e711a09ed51da4bc12fb0d69b7e4482054280/fips203-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d32c699fbac865ec94ad04c94913bfc0a6d013d8de5bb50bced044c054857d3a",
"md5": "31dac6815bfca71ab820d59e4b0296d4",
"sha256": "62bb232bab2e2917d926d0d36ae37f3a31d47c72e98121f314635cbb6b43faca"
},
"downloads": -1,
"filename": "fips203-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "31dac6815bfca71ab820d59e4b0296d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5430,
"upload_time": "2024-10-17T21:56:23",
"upload_time_iso_8601": "2024-10-17T21:56:23.104124Z",
"url": "https://files.pythonhosted.org/packages/d3/2c/699fbac865ec94ad04c94913bfc0a6d013d8de5bb50bced044c054857d3a/fips203-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 21:56:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "integritychain",
"github_project": "fips203",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fips203"
}