{"id":25257882,"url":"https://github.com/antonkueltz/ml-kem","last_synced_at":"2025-06-22T13:03:30.942Z","repository":{"id":275194852,"uuid":"925374026","full_name":"AntonKueltz/ml-kem","owner":"AntonKueltz","description":"Module-Lattice-Based Key Encapsulation Mechanism (FIPS-203) implemented in python","archived":false,"fork":false,"pushed_at":"2025-02-09T21:53:14.000Z","size":1157,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-22T13:02:50.582Z","etag":null,"topics":["c","crystals-kyber","fips-203","key-encapsulation-mechanism","kyber","learning-with-errors","module-lattices","post-quantum-cryptography","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AntonKueltz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-31T18:54:43.000Z","updated_at":"2025-02-09T21:53:17.000Z","dependencies_parsed_at":"2025-06-22T13:02:57.039Z","dependency_job_id":null,"html_url":"https://github.com/AntonKueltz/ml-kem","commit_stats":null,"previous_names":["antonkueltz/ml-kem"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/AntonKueltz/ml-kem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Fml-kem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Fml-kem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Fml-kem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Fml-kem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntonKueltz","download_url":"https://codeload.github.com/AntonKueltz/ml-kem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Fml-kem/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261296904,"owners_count":23137216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","crystals-kyber","fips-203","key-encapsulation-mechanism","kyber","learning-with-errors","module-lattices","post-quantum-cryptography","python"],"created_at":"2025-02-12T06:50:49.618Z","updated_at":"2025-06-22T13:03:25.927Z","avatar_url":"https://github.com/AntonKueltz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI](https://img.shields.io/pypi/v/mlkem.svg)](https://pypi.org/project/mlkem/)\n[![ReadTheDocs](https://readthedocs.org/projects/mlkem/badge/?version=latest)](https://mlkem.readthedocs.io/en/latest/?badge=latest)\n\n# Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM)\nAn implementation of the module-lattice-based key encapsulation mechanism (ML-KEM)\nas described in [FIPS-203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf).\nAt this time the package is in alpha and _SHOULD NOT_ be considered for real-world\ncryptographic applications.\n\n# Usage\n\nThe interface follows the one defined in section 7 of the standard for the functions KeyGen,\nEncaps and Decaps.\n\n```python\nfrom mlkem.ml_kem import ML_KEM\n\nml_kem = ML_KEM()\nek, dk = ml_kem.key_gen()  # encapsulation and decapsulation key\nk, c = ml_kem.encaps(ek)  # shared secret key and ciphertext\nk_ = ml_kem.decaps(dk, c)  # shared secret key\n```\n\nIn a less contrived scenario, Alice might run KeyGen and send the encapsulation key\nto Bob. Bob would then run Encaps and generate a shared secret key and a ciphertext.\nBob would send the ciphertext to Alice, who would derive the shared secret key from the\nciphertext. Alice and Bob can then use the shared secret key to generate additional\nsecret material by passing it to a KDF, use the shared secret to directly key a symmetric\ncipher like AES, etc.\n\n### Implementations\n\nThe package includes includes a pure python implementation of the K-PKE function\n(`mlkem.k_pke.K_PKE`) and an implementation that leverages C extensions\n(`mlkem.fast_k_pke.Fast_K_PKE`). The implementations have interchangeable interfaces\nand can be selected in their wrapper class `mlkem.ml_kem.ML_KEM` by setting the\n`fast` param to `True` for C extensions and `False` for pure python. The default\nimplementation is the one using C extensions and is recommended for all production\nscenarios (note that at this time _neither_ should be considered for real-world\ncryptographic applications as the security of the implementations has not been\nthoroughly assessed).\n\n```python\nfrom mlkem.ml_kem import ML_KEM\nfrom mlkem.parameter_set import ML_KEM_768\n\nML_KEM(ML_KEM_768, fast=True)  # C extensions\nML_KEM(ML_KEM_768, fast=False)  # Pure python\n```\n\nBoth implementations are self contained and portable (assuming you have 8 bits per byte\non your system) with no dependencies on third party libraries in either the C or python\ncode.\n\n### Randomness\n\nNIST requires that an approved RBG (random bit generator) be used as the source of randomness\nfor all operations requiring randomness. The `ML_KEM` class allows a function that takes an\ninteger and returns bytes to be passed as the `randomness` parameter to its constructor. By\ndefault, the `secrets.token_bytes` function is used. This function is acceptable for\ncryptographic applications, however, the underlying implementation may not be NIST approved.\nA custom, NIST-approved function can be passed as well. All that is required is that it conform\nto the signature `f(int) -\u003e bytes`.\n\n```python\nfrom mlkem.ml_kem import ML_KEM\nfrom nist_approved_rbgs import my_rbg  # has type Callable[[int], bytes]\n\nML_KEM(randomness=my_rbg)\n```\n\n### Parameter Sets\n\nNIST recommends the ML-KEM-768 parameter set, which offers 192 bit security. ML-KEM-512\nand ML-KEM-1024 are also available, which provide 128 and 256 bit security respectively.\nML-KEM-768 is used by default in this package. Thus, the two instantiations below are\nequivalent -\n\n```python\nfrom secrets import token_bytes\nfrom mlkem.ml_kem import ML_KEM\nfrom mlkem.parameter_set import ML_KEM_768\n\nML_KEM()\nML_KEM(parameters=ML_KEM_768, randomness=token_bytes, fast=True)\n```\n\n# Development\n\nAs a prerequisite, `uv` is required for this project\n\n    pip install uv\n\nBuild the C extensions\n\n    uv run python setup.py build_ext --inplace\n\nRun the test suite\n\n    uv run pytest\n\nBuild the docs\n\n    uv run make -C docs html\n\n# Performance\n\nBelow are some benchmarks for each parameter set, running on an 2021 M1 MacBook Pro and python3.13\n```\n===== C Extensions =====\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_512 took 0.544 seconds\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_768 took 0.794 seconds\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_1024 took 1.095 seconds\n===== Pure Python =====\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_512 took 32.670 seconds\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_768 took 51.277 seconds\n1000 KeyGen, Encaps and Decaps operations with parameter set ML_KEM_1024 took 72.187 seconds\n```\n\nYou can also run the benchmark yourself as well\n\n```bash\nuv run benchmark  # for local development\npython -m mlkem.benchmark  # for pip installed package\n```\n\nThe performance of the C extensions is _significantly_ faster (benchmark shows ~60-70x). The\npython implementation is primarily included for those  that wish to explore and interactively\ndebug the algorithm using pure python tooling.\n\n# References\n\n* [FIPS-203: Module-Lattice-Based Key-Encapsulation Mechanism Standard](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf)\n* [CRYSTALS-Kyber: a CCA-secure module-lattice-based KEM](https://eprint.iacr.org/2017/634.pdf)\n* [Kyber terminates](https://cryptojedi.org/papers/terminate-20230516.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonkueltz%2Fml-kem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonkueltz%2Fml-kem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonkueltz%2Fml-kem/lists"}