{"id":27193705,"url":"https://github.com/lattice-based-cryptography/mlkem-fips203","last_synced_at":"2025-04-09T18:58:11.704Z","repository":{"id":279292731,"uuid":"936891439","full_name":"lattice-based-cryptography/mlkem-fips203","owner":"lattice-based-cryptography","description":"Rust implementation of module-lattice key encapsulation mechanism (ML-KEM) as specified in FIPS 203.","archived":false,"fork":false,"pushed_at":"2025-04-04T10:57:58.000Z","size":132,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T11:17:25.984Z","etag":null,"topics":["fips-203","ml-kem","module-lwe"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lattice-based-cryptography.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-02-21T21:50:59.000Z","updated_at":"2025-04-04T10:58:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"523bbe6d-78b4-45fa-ac62-6389fae9a47e","html_url":"https://github.com/lattice-based-cryptography/mlkem-fips203","commit_stats":null,"previous_names":["lattice-based-cryptography/ml-kem","lattice-based-cryptography/mlkem-fips203"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lattice-based-cryptography%2Fmlkem-fips203","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lattice-based-cryptography%2Fmlkem-fips203/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lattice-based-cryptography%2Fmlkem-fips203/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lattice-based-cryptography%2Fmlkem-fips203/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lattice-based-cryptography","download_url":"https://codeload.github.com/lattice-based-cryptography/mlkem-fips203/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094374,"owners_count":21046765,"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":["fips-203","ml-kem","module-lwe"],"created_at":"2025-04-09T18:58:08.590Z","updated_at":"2025-04-09T18:58:11.684Z","avatar_url":"https://github.com/lattice-based-cryptography.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mlkem-fips203\n\n![example workflow](https://github.com/lattice-based-cryptography/ml-kem/actions/workflows/basic.yml/badge.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)\n[![Crates.io](https://img.shields.io/crates/v/mlkem-fips203.svg)](https://crates.io/crates/mlkem-fips203)\n\n### Description\n\nRust implementation of module-lattice key encapsulation mechanism (ML-KEM) as specified in FIPS 203. Includes all parameters sets (MLKEM512, MLKEM768, MLKEM1024).\n\n### FIPS 203\n\nNIST post-quantum cryptography standard finalized on Aug. 13th, 202: https://csrc.nist.gov/pubs/fips/203/final\n\n### Disclaimer\n\nThis is not secure. It is not written in constant-time nor resistant to other side-channel attacks. This is intended for educational use and not for real-world applications.\n\n### Usage\n\n In the `src` directory,\n\n`cargo build`\n\nTo build the binary.\n\n`cargo test`\n\n- Performs `keygen`, `encrypt`, `decrypt` for a test message.\n- Performs `keygen`, `encaps`, `decaps` to encapsulate and decapsulate keys.\n- Sets the DRBG seed and generates random bytes using DRBG.\n- Runs doctests for every public function.\n\n`cargo bench`\n\nRuns the three benchmarks for `keygen`, `encaps`, `decaps`.\n\n`cargo run`\n\nRuns the main file which performs a basic PKE `keygen`, `encrypt`, `decrypt` for a random message, and `keygen`, `encaps`, `decaps`.\n\n### Parameters\n\nA global parameter `q=3329`, the Kyber prime, is set. The polynomial size is set to `n=256`. We work over the ring `R_q = Z_q[x]/(x^n+1)`.\n\n### MLKEM Parameter Comparison  \n\n| params     | k  | eta_1 | eta_2 | d_u | d_v |  \n|------------|----|-------|-------|-----|-----|  \n| **MLKEM512**  | 2  | 3     | 2     | 10  | 4   |  \n| **MLKEM768**  | 3  | 2     | 2     | 10  | 4   |  \n| **MLKEM1024** | 4  | 2     | 2     | 11  | 5   |  \n\n#### Parameter Descriptions:\n\n- **k**: Module rank  \n- **eta_1, eta_2**: Control the `cbd` width (centered binomial distribution) for randomness  \n- **d_u, d_v**: Compression \u0026 encoding parameters\n\n### NTT\n\nWe briefly note that this implementation uses a specialized NTT which does not require a `512`th root of unity (which does not exist in `Z_q` since 512 does not divide `3328`). \n\nOn pg. 24 of the FIPS 203 standard paper, they describe that one may use the Chinese remainder theorem to write the ring R_q as a sum of `128` quadratic factors. This ring `T_q` is isomorphic to `R_q`, but we can perform the NTT with only a `256`th root of unity by pairing coefficients.\n\n### Passing by reference\n\nOn pg. 6 of the FIPS 203 paper, they note that there is no \"passing by reference\". We only use cloning when we need to copy values to pass as parameters.\n\n### Polynomials\n\nWe use the `Polynomial\u003ci64\u003e` type. This is not ideal (pun intended), and could be replaced by a custom type which implements the many polynomial methods we use in `utils.rs`.\n\n### Example\n\n```\nuse mlkem_fips203::ml_kem::MLKEM;\nuse mlkem_fips203::parameters::Parameters;\n\n// run the basic keygen/encaps/decaps\nlet (ek, dk) = mlkem.keygen(); // Generate public and private keys for KEM\nlet (shared_k,c) = match mlkem.encaps(ek) { // encapsulate the shared key, handling potential errors\n    Ok(ciphertext) =\u003e ciphertext,\n    Err(e) =\u003e panic!(\"Encryption failed: {}\", e),\n};\nlet shared_k_decaps = match mlkem.decaps(dk,c) { // decapsulate the shared key, handling potential errors\n    Ok(decapsulated_shared_key) =\u003e decapsulated_shared_key,\n    Err(e) =\u003e panic!(\"Decryption failed: {}\", e),\n };\n assert_eq!(shared_k, shared_k_decaps); // check if the decapsulated shared key matches the original shared key\n```\n\n### Error handling\n\nAs specified in FIPS 203, we handle errors for both `encaps` and `decaps`. We use a `Result\u003cT,E\u003e` return type.\n\n### Benchmarks\n\nAll benchmarks were averaged over at least 100 runs using the `criterion` benchmarking crate.\n\n MLKEM | keygen    | encaps    | decaps    |\n-------|-----------|-----------|-----------|\n 512   | 239.00 µs | 362.94 µs | 513.25 µs |\n 768   | 394.09 µs | 528.75 µs | 745.37 µs |\n 1024  | 526.46 µs | 711.49 ms | 987.81 µs |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flattice-based-cryptography%2Fmlkem-fips203","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flattice-based-cryptography%2Fmlkem-fips203","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flattice-based-cryptography%2Fmlkem-fips203/lists"}