Merge pull request #33 from sebastienrousseau/feat/kyberlib

v0.0.5

Author: sebastienrousseau

Cargo.lock

@@ -30,31 +30,36 @@ license = "MIT OR Apache-2.0"
 name = "kyberlib"
 readme = "README.md"
 repository = "https://github.com/sebastienrousseau/kyberlib"
-version = "0.0.4"
+version = "0.0.5"
 
 [dependencies]
+# Dependencies for the library
 aes = { version = "0.8.4", optional = true }
 ctr = { version = "0.9.2", optional = true }
+pqc_core = { version = "0.3.0", features = ["zero"]}
 rand = { version = "0.8.5", default-features = false, features = ["getrandom"] }
 rand_core = { version = "0.6.4",  default-features = false }
 rlg = "0.0.4"
 sha2 = { version = "0.10.8", optional = true }
 tokio = { version = "1.37.0", optional = true }
 wasm-bindgen = "0.2.92"
+zeroize = { version = "1.7.0", features = ["derive"] }
 
 [dev-dependencies]
+# Dependencies for testing
 criterion = "0.5.1"
-rand = "0.8.5"
 wasm-bindgen-test = "0.3.42"
 
 # benchmarking = ["criterion"]
 
 [build-dependencies]
+# Dependencies for the build script
 cc = {version = "1.0.97", optional = true }
 nasm-rs = {version = "0.3.0", optional = true }
 
 [lib]
-crate-type = ["cdylib", "rlib"]
+# Metadata about the library
+crate-type = ["cdylib", "rlib", "staticlib"]
 name = "kyberlib"
 path = "src/lib.rs"
 
@@ -108,12 +113,12 @@ std = []
 
 ## Warn
 # box_pointers = "warn"
-# missing_copy_implementations = "warn"
-# missing_docs = "warn"
-# unstable_features = "warn"
+missing_copy_implementations = "warn"
+missing_docs = "warn"
+unstable_features = "warn"
 # unused_crate_dependencies = "warn"
 # unused_extern_crates = "warn"
-# unused_results = "warn"
+unused_results = "warn"
 
 ## Allow
 bare_trait_objects = "allow"

Cargo.toml

@@ -18,17 +18,9 @@ A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography.
 <center>
 <!-- markdownlint-enable MD033 MD041 -->
 
-[![Made With Rust][made-with-rust-badge]][05]
-[![Crates.io][crates-badge]][07]
-[![Lib.rs][libs-badge]][09]
-[![Docs.rs][docs-badge]][08]
-[![License][license-badge]][02]
-
-• [Website][00]
-• [Documentation][08]
-• [Report Bug][03]
-• [Request Feature][03]
-• [Contributing Guidelines][04]
+[![Made With Love][made-with-rust]][05] [![Crates.io][crates-badge]][07] [![Lib.rs][libs-badge]][09] [![Docs.rs][docs-badge]][08] [![License][license-badge]][02] [![Codecov][codecov-badge]][15]
+
+• [Website][00] • [Documentation][08] • [Report Bug][03] • [Request Feature][03] • [Contributing Guidelines][04]
 
 <!-- markdownlint-disable MD033 MD041 -->
 </center>
@@ -38,7 +30,7 @@ A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography.
 
 ## Overview 📖
 
-KyberLib is a robust Rust library designed for CRYSTALS-Kyber Post-Quantum Cryptography, offering strong security guarantees. This library is compatible with `no_std`, making it suitable for embedded devices and avoids memory allocations. Additionally, it contains reference implementations with no unsafe code and provides an optimized AVX2 version by default on x86_64 platforms. You can also compile it to WebAssembly (WASM) using wasm-bindgen.
+KyberLib is a robust Rust library designed for **CRYSTALS-Kyber Post-Quantum Cryptography**, offering strong security guarantees. This library is compatible with `no_std`, making it suitable for embedded devices and avoids memory allocations. Additionally, it contains reference implementations with no unsafe code and provides an optimized AVX2 version by default on x86_64 platforms. You can also compile it to WebAssembly (WASM) using wasm-bindgen.
 
 ## Features ✨
 
@@ -73,7 +65,7 @@ It takes just a few minutes to get up and running with `kyberlib`.
 ### Requirements
 
 The minimum supported Rust toolchain version is currently Rust
-**1.56.0** or later (stable).
+**1.60** or later (stable).
 
 ### Installation
 
@@ -95,7 +87,7 @@ To use the `kyberlib` library in your project, add the following to your
 
 ```toml
 [dependencies]
-kyberlib = "0.0.4"
+kyberlib = "0.0.5"
 ```
 
 Add the following to your `main.rs` file:
@@ -113,6 +105,8 @@ For optimisations on x86 platforms enable the `avx2` feature and the following R
 export RUSTFLAGS="-C target-feature=+aes,+avx2,+sse2,+sse4.1,+bmi2,+popcnt"
 ```
 
+## Crate Features 📦
+
 ### Key Encapsulation
 
 ```rust
@@ -177,32 +171,38 @@ alice.client_confirm(server_response, &alice_keys.secret)?;
 assert_eq!(alice.shared_secret, bob.shared_secret);
 ```
 
-## Macros
+## Macros 🦀
 
 The KyberLib crate provides several macros to simplify common cryptographic operations:
 
-- `kyberlib_assert!`: Asserts that a given expression is true. Panics if the assertion fails.
-- `kyberlib_min!`: Returns the minimum of the given values.
-- `kyberlib_max!`: Returns the maximum of the given values.
-- `kyberlib_generate_key_pair!`: Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.
-- `kyberlib_encrypt_message!`: Generates cipher text and a shared secret for a given public key.
-- `kyberlib_decrypt_message!`: Generates a shared secret for a given cipher text and private key. 
-- `kyberlib_uake_client_init!`: Initiates a Unilaterally Authenticated Key Exchange.
-- `kyberlib_uake_server_receive!`: Handles the output of a `kyberlib_uake_client_init()` request.
-- `kyberlib_uake_client_confirm!`: Decapsulates and authenticates the shared secret from the output of `kyberlib_uake_server_receive()`.
-- `kyberlib_ake_client_init!`: Initiates a Mutually Authenticated Key Exchange.
-- `kyberlib_ake_server_receive!`: Handles and authenticates the output of a `kyberlib_ake_client_init()` request.
-- `kyberlib_ake_client_confirm!`: Decapsulates and authenticates the shared secret from the output of `kyberlib_ake_server_receive()`.
-
-See the [macros module documentation](https://docs.rs/kyberlib/latest/kyberlib/macros/index.html) for more details and usage examples.
+- [`kyberlib_generate_key_pair!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_generate_key_pair.html): Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.
+
+- [`kyberlib_encrypt_message!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_encrypt_message.html): Generates cipher text and a shared secret for a given public key.
+
+- [`kyberlib_decrypt_message!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_decrypt_message.html): Generates a shared secret for a given cipher text and private key.
+
+- [`kyberlib_uake_client_init!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_client_init.html): Initiates a Unilaterally Authenticated Key Exchange.
+
+- [`kyberlib_uake_server_receive!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_server_receive.html): Handles the output of a `kyberlib_uake_client_init()` request.
+
+- [`kyberlib_uake_client_confirm!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_client_confirm.html): Decapsulates and authenticates the shared secret from the output of `kyberlib_uake_server_receive()`.
+
+- [`kyberlib_ake_client_init!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_ake_client_init.html): Initiates a Mutually Authenticated Key Exchange.
+
+- [`kyberlib_ake_server_receive!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_server_receive.html): Handles and authenticates the output of a `kyberlib_ake_client_init()` request.
+
+- [`kyberlib_ake_client_confirm!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_ake_client_confirm.html): Decapsulates and authenticates the shared secret from the output of `kyberlib_ake_server_receive()`.
+
+See the [macros module documentation](https://docs.rs/kyberlib/latest/kyberlib/index.html#macros) for more details and usage examples.
 
 ## Errors
 
 The KyberLibError enum has two variants:
 
 - **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.
+- **InvalidKey** - Error when generating keys.
 - **Decapsulation** - The ciphertext was unable to be authenticated. The shared secret was not decapsulated.
-- **RandomBytesGeneration** - Error trying to fill random bytes (i.e external (hardware) RNG modules can fail).
+- **RandomBytesGeneration** - Error trying to fill random bytes (i.e., external (hardware) RNG modules can fail).
 
 ## Examples
 
@@ -244,7 +244,7 @@ cargo run --example uake
 
 ### Platform support
 
-`kyberlib` is supported and tested on MacOS, Linux, and Windows. The [GitHub Actions][10] shows the platforms in which the `kyberlib` library tests are run.
+`kyberlib` supports a variety of CPU architectures. It is supported and tested on MacOS, Linux, and Windows.
 
 ### Documentation
 
@@ -258,8 +258,10 @@ backward compatibility, `kyberlib` follows [semantic versioning][06].
 
 ## License 📝
 
-The project is licensed under the terms of Apache License, Version 2.0 and the
-MIT license.
+KyberLib is distributed under the terms of both the MIT license and the
+Apache License (Version 2.0).
+
+See [LICENSE-APACHE][01] and [LICENSE-MIT][02] for details.
 
 ## Contribution 🤝
 
@@ -289,24 +291,25 @@ A special thank you goes to the [Rust Reddit][12] community for
 providing a lot of useful suggestions on how to improve this project.
 
 [00]: https://kyberlib.com/ "KyberLib, A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography"
-[01]: https://kura.pro/common/images/elements/divider.svg "Divider"
-[02]: http://opensource.org/licenses/MIT "KyberLib license"
+[01]: http://opensource.org/licenses/Apache-2.0 "Apache License, Version 2.0"
+[02]: http://opensource.org/licenses/MIT "MIT License"
 [03]: https://github.com/sebastienrousseau/kyberlib/kyberlib/issues "KyberLib Issues"
 [04]: https://github.com/sebastienrousseau/kyberlib/kyberlib/blob/main/CONTRIBUTING.md "KyberLib Contributing Guidelines"
 [05]: https://github.com/sebastienrousseau/kyberlib/kyberlib/graphs/contributors "KyberLib Contributors"
 [06]: http://semver.org/ "SemVer"
 [07]: https://crates.io/crates/kyberlib "KyberLib on Crates.io"
 [08]: https://docs.rs/kyberlib "KyberLib on Docs.rs"
 [09]: https://lib.rs/crates/kyberlib "KyberLib on Lib.rs"
-[10]: https://github.com/sebastienrousseau/kyberlib/kyberlib/actions "KyberLib on GitHub Actions"
 [11]: https://www.rust-lang.org/policies/code-of-conduct "KyberLib Code of Conduct"
 [12]: https://www.reddit.com/r/rust/ "Reddit"
 [13]: https://www.rust-lang.org/learn/get-started "Rust"
 [14]: https://github.com/Argyle-Software/kyber "Kyber from Argyle-Software"
+[15]: https://codecov.io/gh/sebastienrousseau/kyberlib "Codecov"
 
-[crates-badge]: https://img.shields.io/crates/v/kyberlib.svg?style=for-the-badge 'Crates.io badge'
+[crates-badge]: https://img.shields.io/crates/v/kyberlib.svg?style=for-the-badge 'Crates.io'
+[codecov-badge]: https://img.shields.io/codecov/c/github/sebastienrousseau/kyberlib?style=for-the-badge&token=oEisyTucB5 'Codecov'
 [divider]: https://kura.pro/common/images/elements/divider.svg "divider"
-[docs-badge]: https://img.shields.io/docsrs/kyberlib.svg?style=for-the-badge 'Docs.rs badge'
-[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.1-orange.svg?style=for-the-badge 'Lib.rs badge'
-[license-badge]: https://img.shields.io/crates/l/kyberlib.svg?style=for-the-badge 'License badge'
-[made-with-rust-badge]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust badge'
+[docs-badge]: https://img.shields.io/docsrs/kyberlib.svg?style=for-the-badge 'Docs.rs'
+[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.5-orange.svg?style=for-the-badge 'Lib.rs'
+[license-badge]: https://img.shields.io/crates/l/kyberlib.svg?style=for-the-badge 'License'
+[made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust'

README.md

@@ -40,30 +40,6 @@ A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography
 
 A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography
 
-## Features ✨
-
-### Core Features
-
-- **`no_std` compatible**: No dependence on the Rust standard library
-- **Avoid allocations**: Uses stack-based data structures only
-- **Configurable**: Features to enable different parameter sets
-- **Optimised x86_64**: Uses assembly for performance-critical code, including an optimised AVX2 version by default.
-- **Safe code**: Reference implementations have no `unsafe` blocks
-- **WebAssembly Support**: Can be compiled to WASM using wasm-bindgen.
-
-### Advanced Features
-
-- **Allocation-free Guarantee**: KyberLib guarantees all its core cryptography operations are free of heap allocations.
-- **Assembly Optimizations**: The x86_64 assembly implementations use AVX2 instructions for high performance.
-- **Security**: KyberLib contains no unsafe code in its public API surface.
-
-## Functionality 📚
-
-- **Key Generation**: Create public/private key pairs
-- **Encapsulation**: Encapsulate a shared secret with a public key
-- **Decapsulation**: Decapsulate a shared secret with a private key
-- **Key Exchange**: Perform authenticated key exchanges
-
 [0]: https://kyberlib.com/
 [2]: http://opensource.org/licenses/MIT
 [3]: https://github.com/sebastienrousseau/kyberlib/kyberlib/issues
@@ -73,11 +49,10 @@ A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography
 [8]: https://docs.rs/kyberlib
 [9]: https://lib.rs/crates/kyberlib
 
-[banner]: https://via.placeholder.com/1500x500.png/000000/FFFFFF?text=kyberlib "kyberlib's banner"
 [crates-badge]: https://img.shields.io/crates/v/kyberlib.svg?style=for-the-badge 'Crates.io badge'
 [divider]: https://via.placeholder.com/1024x1.png/d8dee4/FFFFFF?text=− "kyberlib's divider"
 [docs-badge]: https://img.shields.io/docsrs/kyberlib.svg?style=for-the-badge 'Docs.rs badge'
-[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.1-orange.svg?style=for-the-badge 'Lib.rs badge'
+[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.5-orange.svg?style=for-the-badge 'Lib.rs badge'
 [license-badge]: https://img.shields.io/crates/l/kyberlib.svg?style=for-the-badge 'License badge'
 [made-with-rust-badge]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust badge'