3 releases

0.0.3 Dec 25, 2023
0.0.2 Nov 21, 2023
0.0.1 Nov 18, 2023

#483 in Cryptography

Download history 4/week @ 2023-12-25 2/week @ 2024-02-19 29/week @ 2024-02-26 8/week @ 2024-03-11 52/week @ 2024-04-01

60 downloads per month

MIT/Apache

290KB
6.5K SLoC

Rust 5K SLoC // 0.0% comments GNU Style Assembly 625 SLoC // 0.1% comments Assembly 606 SLoC // 0.0% comments Bitbake 99 SLoC // 0.0% comments

kyberlib's logo

kyberlib

A Robust Rust Library for CRYSTALS-Kyber Post-Quantum Cryptography.

Made With Rust Crates.io Lib.rs Docs.rs License

WebsiteDocumentationReport BugRequest FeatureContributing Guidelines

divider

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.

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

See Documentation for full API details.

Divider

Getting Started 🚀

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).

Installation

To install kyberlib, you need to have the Rust toolchain installed on your machine. You can install the Rust toolchain by following the instructions on the Rust website.

Once you have the Rust toolchain installed, you can install kyberlib using the following command:

cargo install kyberlib

Divider

Usage 📖

To use the kyberlib library in your project, add the following to your Cargo.toml file:

[dependencies]
kyberlib = "0.0.3"

Add the following to your main.rs file:

extern crate kyberlib;
use kyberlib::*;

then you can use the functions in your application code.

For optimisations on x86 platforms enable the avx2 feature and the following RUSTFLAGS:

export RUSTFLAGS="-C target-feature=+aes,+avx2,+sse2,+sse4.1,+bmi2,+popcnt"

Key Encapsulation

// Generate Keypair
let keys_bob = keypair(&mut rng)?;

// Alice encapsulates a shared secret using Bob's public key
let (ciphertext, shared_secret_alice) = encapsulate(&keys_bob.public, &mut rng)?;

// Bob decapsulates a shared secret using the ciphertext sent by Alice
let shared_secret_bob = decapsulate(&ciphertext, &keys_bob.secret)?;

assert_eq!(shared_secret_alice, shared_secret_bob);

Unilaterally Authenticated Key Exchange

let mut rng = rand::thread_rng();

// Initialize the key exchange structs
let mut alice = Uake::new();
let mut bob = Uake::new();

// Generate Bob's Keypair
let bob_keys = keypair(&mut rng)?;

// Alice initiates key exchange
let client_init = alice.client_init(&bob_keys.public, &mut rng)?;

// Bob authenticates and responds
let server_response = bob.server_receive(
  client_init, &bob_keys.secret, &mut rng
)?;

// Alice decapsulates the shared secret
alice.client_confirm(server_response)?;

// Both key exchange structs now have the same shared secret
assert_eq!(alice.shared_secret, bob.shared_secret);

Mutually Authenticated Key Exchange

Follows the same workflow except Bob requires Alice's public keys:

let mut alice = Ake::new();
let mut bob = Ake::new();

let alice_keys = keypair(&mut rng)?;
let bob_keys = keypair(&mut rng)?;

let client_init = alice.client_init(&bob_keys.public, &mut rng)?;

let server_response = bob.server_receive(
  client_init, &alice_keys.public, &bob_keys.secret, &mut rng
)?;

alice.client_confirm(server_response, &alice_keys.secret)?;

assert_eq!(alice.shared_secret, bob.shared_secret);

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.
  • 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).

Divider

Examples

To get started with kyberlib, you can use the examples provided in the examples directory of the project.

To run the examples, clone the repository and run the following command in your terminal from the project root directory.

Example 1: Implements an authenticated key exchange protocol

Alice and Bob exchange public keys to derive a shared secret in a way that authenticates each party.

Run the following command in your terminal from the project root directory.

cargo run --example ake

Example 2: Demonstrates key encapsulation and decapsulation

Alice generates a keypair. Bob encapsulates a secret using Alice's public key. Alice decapsulates the secret using her private key. This allows secure communication.

Run the following command in your terminal from the project root directory.

cargo run --example kem

Example 3: Implements an unauthenticated key exchange protocol

Alice and Bob exchange public information to derive a shared secret without authenticating each other. Provides confidentiality but not authentication.

Run the following command in your terminal from the project root directory.

cargo run --example uake

Divider

Platform support

kyberlib is supported and tested on the following platforms:

Tier 1 platforms 🏆

Operating System Target Description
Linux aarch64-unknown-linux-gnu 64-bit Linux systems on ARM architecture
Windows i686-pc-windows-gnu 32-bit Windows systems using the GNU toolchain
Windows i686-pc-windows-msvc 32-bit Windows systems using the Microsoft Visual C toolchain
Linux i686-unknown-linux-gnu 32-bit Linux systems (kernel 3.2+, glibc 2.17+)
macOS x86_64-apple-darwin 64-bit macOS systems (10.7 Lion or later)
Windows x86_64-pc-windows-gnu 64-bit Windows systems using the GNU toolchain
Windows x86_64-pc-windows-msvc 64-bit Windows systems using the Microsoft Visual C toolchain
Linux x86_64-unknown-linux-gnu 64-bit Linux systems (kernel 2.6.32+, glibc 2.11+)

Tier 2 platforms 🥈

Operating System Target Description
Linux aarch64-apple-darwin 64-bit macOS on Apple Silicon
Windows aarch64-pc-windows-msvc 64-bit Windows on ARM architecture using the Microsoft Visual C toolchain
Linux aarch64-unknown-linux-musl 64-bit Linux on ARM architecture with musl libc
Linux arm-unknown-linux-gnueabi ARMv6 Linux systems (kernel 3.2, glibc 2.17)
Linux arm-unknown-linux-gnueabihf ARMv7 Linux systems, hardfloat (kernel 3.2, glibc 2.17)
Linux armv7-unknown-linux-gnueabihf ARMv7 Linux systems, hardfloat (kernel 3.2, glibc 2.17)
Linux powerpc-unknown-linux-gnu PowerPC Linux systems (kernel 3.2, glibc 2.17)
Linux powerpc64-unknown-linux-gnu PowerPC64 Linux systems (kernel 3.2, glibc 2.17)
Linux powerpc64le-unknown-linux-gnu PowerPC64le Linux systems (kernel 3.2, glibc 2.17)
Linux riscv64gc-unknown-linux-gnu RISC-V Linux systems (kernel 3.2, glibc 2.17)
Linux s390x-unknown-linux-gnu s390x Linux systems (kernel 3.2, glibc 2.17)
Linux x86_64-unknown-freebsd 64-bit FreeBSD systems on x86-64 architecture
Linux x86_64-unknown-linux-musl 64-bit Linux systems (kernel 2.6.32+, musl libc)

The GitHub Actions shows the platforms in which the kyberlib library tests are run.

Divider

Documentation

Info: Please check out our website for more information. You can find our documentation on docs.rs, lib.rs and crates.io.

Semantic Versioning Policy 🚥

For transparency into our release cycle and in striving to maintain backward compatibility, kyberlib follows semantic versioning.

Divider

License 📝

The project is licensed under the terms of Apache License, Version 2.0 and the MIT license.

Divider

Contribution 🤝

We welcome all people who want to contribute. Please see the contributing instructions for more information.

Contributions in any form (issues, pull requests, etc.) to this project must adhere to the Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Divider

Acknowledgements 💙

A big thank you to all the awesome contributors of kyberlib for their help and support.

This repo is a fork of the innovative Rust implementation of the Kyber post-quantum KEM from Argyle-Software/kyber. We are deeply grateful for the inspiration and contribution of the original project, which has provided a solid foundation for our work and study. Thank you! You can find the original repo here.

A special thank you goes to the Rust Reddit community for providing a lot of useful suggestions on how to improve this project.

Dependencies

~39–600KB
~11K SLoC