KyberLib: Uncover Essential Installation Prerequisites

Welcome to KyberLib User Guide. Get started with our Robust Rust library designed for CRYSTALS-Kyber Post-Quantum Cryptography (PQC) and compatible with no_std.

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.

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

Usage

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

[dependencies]
kyberlib = "0.0.2"

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

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

Documentation

For comprehensive information and resources related to KyberLib, we invite you to explore our extensive documentation.

Detailed guides, API references, and examples are available on docs.rs ⧉, where you’ll find in-depth material to support your development needs.

For library-specific details and to access our collection of Rust libraries, visit lib.rs ⧉.

Additionally, you can explore crates.io ⧉ to find a wide range of Rust crates, which include the necessary tools and libraries to enhance your projects.

These resources are designed to provide you with the most up-to-date and thorough information to assist in your development endeavours.