{"id":22281328,"url":"https://github.com/argyle-software/kyber","last_synced_at":"2025-05-16T03:04:21.464Z","repository":{"id":45506773,"uuid":"369428655","full_name":"Argyle-Software/kyber","owner":"Argyle-Software","description":"A rust implementation of the Kyber post-quantum KEM","archived":false,"fork":false,"pushed_at":"2024-03-20T15:39:37.000Z","size":3272,"stargazers_count":211,"open_issues_count":22,"forks_count":42,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-16T03:04:16.254Z","etag":null,"topics":["cryptography","key-exchange-algorithm","post-quantum","post-quantum-kem","wasm"],"latest_commit_sha":null,"homepage":"https://docs.rs/pqc_kyber/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Argyle-Software.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"contributing.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mberry","ko_fi":"mberry","tidelift":"cargo/pqc_kyber"}},"created_at":"2021-05-21T05:57:31.000Z","updated_at":"2025-05-13T20:44:28.000Z","dependencies_parsed_at":"2024-06-19T13:26:25.129Z","dependency_job_id":"57aac16a-8cfc-4d19-aa03-f4cb2ddd3cb2","html_url":"https://github.com/Argyle-Software/kyber","commit_stats":{"total_commits":441,"total_committers":8,"mean_commits":55.125,"dds":"0.27210884353741494","last_synced_commit":"476e22c1a1ed579f3030e1ae46077036dc384d7f"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Argyle-Software%2Fkyber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Argyle-Software%2Fkyber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Argyle-Software%2Fkyber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Argyle-Software%2Fkyber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Argyle-Software","download_url":"https://codeload.github.com/Argyle-Software/kyber/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"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":["cryptography","key-exchange-algorithm","post-quantum","post-quantum-kem","wasm"],"created_at":"2024-12-03T16:17:16.746Z","updated_at":"2025-05-16T03:04:16.452Z","avatar_url":"https://github.com/Argyle-Software.png","language":"Rust","funding_links":["https://github.com/sponsors/mberry","https://ko-fi.com/mberry","https://tidelift.com/funding/github/cargo/pqc_kyber"],"categories":[],"sub_categories":[],"readme":"\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./kyber.png\"/\u003e\n\u003c/p\u003e\n\n\n# Kyber\n[![Build Status](https://github.com/Argyle-Software/kyber/actions/workflows/kat.yml/badge.svg)](https://github.com/Argyle-Software/kyber/actions)\n[![Crates](https://img.shields.io/crates/v/pqc-kyber)](https://crates.io/crates/pqc-kyber)\n[![NPM](https://img.shields.io/npm/v/pqc-kyber?color=yellow)](https://www.npmjs.com/package/pqc-kyber)\n[![License](https://img.shields.io/crates/l/pqc_kyber)](https://github.com/Argyle-Software/kyber/blob/master/LICENSE-MIT)\n[![dependency status](https://deps.rs/crate/pqc_kyber/latest/status.svg)](https://deps.rs/crate/pqc_kyber)\n\nA rust implementation of the Kyber algorithm, a KEM standardised by the NIST Post-Quantum Standardization Project.\n\nThis library:\n* Is no_std compatible and needs no allocator, suitable for embedded devices. \n* Reference files contain no unsafe code and are written in pure rust.\n* On x86_64 platforms offers an avx2 optimized version, which includes assembly from the C reference repo. \n* Compiles to WASM using wasm-bindgen and has a ready-to-use binary published on NPM.\n\n\nSee the [**features**](#features) section for different options regarding security levels and modes of operation. The default security setting is kyber768.\n\nIt is recommended to use Kyber in a hybrid system alongside a traditional key exchange algorithm such as X25519. \n\nPlease also read the [**security considerations**](#security-considerations) before use.\n\n**Minimum Supported Rust Version: 1.56.0**\n\n---\n\n## Installation\n\n```shell\ncargo add pqc_kyber\n```\n\n## Usage \n\n```rust\nuse pqc_kyber::*;\n```\n\nFor optimisations on x86 platforms enable the `avx2` feature and the following RUSTFLAGS:\n\n```shell\nexport RUSTFLAGS=\"-C target-feature=+aes,+avx2,+sse2,+sse4.1,+bmi2,+popcnt\"\n```\n\n---\n\n### Key Encapsulation\n\n```rust\n// Generate Keypair\nlet keys_bob = keypair(\u0026mut rng)?;\n\n// Alice encapsulates a shared secret using Bob's public key\nlet (ciphertext, shared_secret_alice) = encapsulate(\u0026keys_bob.public, \u0026mut rng)?;\n\n// Bob decapsulates a shared secret using the ciphertext sent by Alice \nlet shared_secret_bob = decapsulate(\u0026ciphertext, \u0026keys_bob.secret)?;\n\nassert_eq!(shared_secret_alice, shared_secret_bob);\n```\n\n---\n\n### Unilaterally Authenticated Key Exchange\n```rust\nlet mut rng = rand::thread_rng();\n\n// Initialize the key exchange structs\nlet mut alice = Uake::new();\nlet mut bob = Uake::new();\n\n// Generate Bob's Keypair\nlet bob_keys = keypair(\u0026mut rng)?;\n\n// Alice initiates key exchange\nlet client_init = alice.client_init(\u0026bob_keys.public, \u0026mut rng)?;\n\n// Bob authenticates and responds\nlet server_response = bob.server_receive(\n  client_init, \u0026bob_keys.secret, \u0026mut rng\n)?;\n\n// Alice decapsulates the shared secret\nalice.client_confirm(server_response)?;\n\n// Both key exchange structs now have the same shared secret\nassert_eq!(alice.shared_secret, bob.shared_secret);\n```\n\n---\n\n### Mutually Authenticated Key Exchange\nFollows the same workflow except Bob requires Alice's public keys:\n\n```rust\nlet mut alice = Ake::new();\nlet mut bob = Ake::new();\n\nlet alice_keys = keypair(\u0026mut rng)?;\nlet bob_keys = keypair(\u0026mut rng)?;\n\nlet client_init = alice.client_init(\u0026bob_keys.public, \u0026mut rng)?;\n\nlet server_response = bob.server_receive(\n  client_init, \u0026alice_keys.public, \u0026bob_keys.secret, \u0026mut rng\n)?;\n\nalice.client_confirm(server_response, \u0026alice_keys.secret)?;\n\nassert_eq!(alice.shared_secret, bob.shared_secret);\n```\n\n---\n\n## Errors\nThe KyberError enum has two variants:\n\n* **InvalidInput** - One or more inputs to a function are incorrectly sized. A possible cause of this is two parties using different security levels while trying to negotiate a key exchange.\n\n* **Decapsulation** - The ciphertext was unable to be authenticated. The shared secret was not decapsulated.\n\n* **RandomBytesGeneration** - Error trying to fill random bytes (i.e external (hardware) RNG modules can fail).\n\n---\n\n## Features\n\nIf no security level is specified then kyber768 is used by default as recommended by the authors. It is roughly equivalent to AES-192.  Apart from the two security levels, all other features can be combined as needed. For example:\n\n```toml\n[dependencies]\npqc_kyber = {version = \"0.7.1\", features = [\"kyber512\", \"90s\", \"avx2\"]}\n```\n\n\n| Feature   | Description |\n|-----------|------------|\n| std | Enable the standard library |\n| kyber512  | Enables kyber512 mode, with a security level roughly equivalent to AES-128.|\n| kyber1024 | Enables kyber1024 mode, with a security level roughly equivalent to AES-256.  A compile-time error is raised if more than one security level is specified.|\n| 90s | Uses AES256 in counter mode and SHA2 as a replacement for SHAKE. This can provide hardware speedups in some cases.|\n| 90s-fixslice | Uses a fixslice implementation of AES256 by RustCrypto, this provides greater side-channel attack resistance, especially on embedded platforms |\n| avx2 | On x86_64 platforms enable the optimized version. This flag is will cause a compile error on other architectures. |\n| wasm | For compiling to WASM targets|\n| nasm | Uses Netwide Assembler avx2 code instead of GAS for portability. Requires a nasm compiler: https://www.nasm.us/ | \n| zeroize | This will zero out the key exchange structs on drop using the [zeroize](https://docs.rs/zeroize/latest/zeroize/) crate |\n| benchmarking |  Enables the criterion benchmarking suite |\n---\n\n## Testing\n\nThe [run_all_tests](tests/run_all_tests.sh) script will traverse all possible codepaths by running a matrix of the security levels, variants and crate features.\n\nKnown Answer Tests require deterministic rng seeds, enable `kyber_kat` in `RUSTFLAGS`to use them. \nUsing this outside of `cargo test` will result in a compile-time error. \nThe test vector files are quite large, you will need to build them yourself from the C reference code. \nThere's a helper script to do this [here](./tests/KAT/build_kats.sh). \n\n```bash\n# This example runs the basic tests for kyber768\ncargo test\n\n# This runs the KATs for kyber512 in 90's mode\nRUSTFLAGS='--cfg kyber_kat' cargo test --features \"kyber512 90s\"\n```\n\nSee the [testing readme](./tests/readme.md) for more comprehensive info.\n\n---\n\n## Benchmarking\n\nUses criterion for benchmarking. If you have GNUPlot installed it will generate statistical graphs in `./target/criterion/`.\n\nYou will need to enable the `benchmarking` feature.\n\nSee the [benchmarking readme](./benches/readme.md) for information on correct usage.\n\n---\n\n## Fuzzing\n\nThe fuzzing suite uses honggfuzz, installation and instructions are on the [fuzzing](./fuzz/readme.md) page. \n\n---\n\n## WebAssembly\n\nThis library has been compiled into web assembly and published as a npm package. Usage instructions are here:\n\nhttps://www.npmjs.com/package/pqc-kyber\n\nWhich is also located here in the [wasm readme](./pkg/readme.md)\n\nTo install:\n\n```shell\nnpm i pqc-kyber\n```\n\nTo compile the wasm files yourself you need to enable the `wasm` feature.\n\nFor example, using [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/):\n\n```shell\nwasm-pack build -- --features wasm\n```\n\nWhich will export the wasm, javascript and  typescript files into [./pkg/](./pkg/readme.md). \n\nTo compile a different variant into a separate folder: \n```shell\nwasm-pack build --out-dir pkg_kyber512/ -- --features \"wasm kyber512\" \n```\n\nThere is also a basic html demo in the [www](./www/readme.md) folder.\n \nFrom the www folder run: \n\n```shell\nnpm run start\n```\n\n---\n\n## Security Considerations \n\nWhile much care has been taken porting from the C reference codebase, this library has not undergone any third-party security auditing nor can any guarantees be made about the potential for underlying vulnerabilities in LWE cryptography or potential side-channel attacks arising from this implementation.\n\nKyber is relatively new, it is advised to use it in a hybrid key exchange system alongside a traditional algorithm like X25519 rather than by itself. \n\nFor further reading the IETF have a draft construction for hybrid key exchange in TLS 1.3:\n\nhttps://www.ietf.org/archive/id/draft-ietf-tls-hybrid-design-04.html\n\nYou can also see how such a system is implemented [here](https://github.com/openssh/openssh-portable/blob/a2188579032cf080213a78255373263466cb90cc/kexsntrup761x25519.c) in C by OpenSSH\n\nPlease use at your own risk.\n\n---\n\n## About\n\nKyber is an IND-CCA2-secure key encapsulation mechanism (KEM), whose security is based on the hardness of solving the learning-with-errors (LWE) problem over module lattices. It is the final standardised algorithm resulting from the [NIST post-quantum cryptography project](https://csrc.nist.gov/Projects/Post-Quantum-Cryptography).\n\nThe official website: https://pq-crystals.org/kyber/\n\nAuthors of the Kyber Algorithm: \n\n* Roberto Avanzi, ARM Limited (DE)\n* Joppe Bos, NXP Semiconductors (BE)\n* Léo Ducas, CWI Amsterdam (NL)\n* Eike Kiltz, Ruhr University Bochum (DE)\n* Tancrède Lepoint, SRI International (US)\n* Vadim Lyubashevsky, IBM Research Zurich (CH)\n* John M. Schanck, University of Waterloo (CA)\n* Peter Schwabe, Radboud University (NL)\n* Gregor Seiler, IBM Research Zurich (CH)\n* Damien Stehle, ENS Lyon (FR)\n\n---\n\n### Contributing \n\nContributions welcome. For pull requests create a feature fork and submit it to the development branch. More information is available on the [contributing page](./contributing.md)\n\n---\n\n### Alternatives\n\nThe PQClean project has rust bindings for their Kyber C codebase:\n\nhttps://github.com/rustpq/pqcrypto\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fargyle-software%2Fkyber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fargyle-software%2Fkyber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fargyle-software%2Fkyber/lists"}