Crate kyberlib

source ·
Expand description

KyberLib 🦀

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 it 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 Logo

Features

KyberLib offers various features to customize its behavior and security level:

FeatureDescription
kyber512Enables Kyber512 mode, providing a security level roughly equivalent to AES-128.
kyber1024Enables Kyber1024 mode, offering a security level roughly equivalent to AES-256.
90sActivates 90’s mode, which uses SHA2 and AES-CTR as a replacement for SHAKE. This may provide hardware speedups on certain architectures.
avx2On x86_64 platforms, enables the optimized AVX2 version. This flag causes a compile error on other architectures.
wasmEnables support for compiling to WASM targets.
nasmUses Netwide Assembler (NASM) AVX2 code instead of GNU Assembler (GAS) for portability. Requires a NASM compiler: https://www.nasm.us/
zeroizeAutomatically zeroes out key exchange structs on drop using the zeroize crate
stdEnables the standard library (std).

Usage

To optimize for x86 platforms, enable the avx2 feature and set the following RUSTFLAGS:

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

Import the library into your Rust project as follows:

use kyberlib::*;

Key Encapsulation

Generate key pairs and encapsulate a shared secret between two parties:


// Generate Keypair for Bob
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 the shared secret using the ciphertext sent by Alice
let shared_secret_bob = decapsulate(&ciphertext, &keys_bob.secret)?;

// Verify that both parties share the same secret
assert_eq!(shared_secret_alice, shared_secret_bob);

Unilaterally Authenticated Key Exchange

Perform a unilaterally authenticated key exchange between two parties:

let mut rng = rand::thread_rng();

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

// Generate Keypairs for Alice and Bob
let alice_keys = keypair(&mut rng)?;
let bob_keys = keypair(&mut rng)?;

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

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

// Alice confirms the server response and retrieves the shared secret
alice.client_confirm(server_send)?;

// Both Alice and Bob now have the same shared secret
assert_eq!(alice.shared_secret, bob.shared_secret);

Mutually Authenticated Key Exchange

Perform a mutually authenticated key exchange between two parties:

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_send = bob.server_receive(
  client_init, &alice_keys.public, &bob_keys.secret, &mut rng
)?;

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

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

Errors

The KyberLibError enum handles errors with two variants:

  • InvalidInput: Occurs when one or more byte inputs to a function are incorrectly sized. This typically happens when two parties use different security levels while attempting to negotiate a key exchange.
  • Decapsulation: This error indicates that the ciphertext could not be authenticated, and the shared secret was not successfully decapsulated.

Re-exports

Modules

  • API for the KyberLib library.
  • Error types for the KyberLib library.
  • Key encapsulation module for the KyberLib library.
  • Key exchange structs for the KyberLib library.
  • Logging utilities for debugging
  • Macro utilities for the KyberLib library.
  • Parameters for the KyberLib library.
  • Random number generators for the KyberLib library.
  • Symmetric key encapsulation module for the KyberLib library.

Macros

  • Asserts that a given expression is true. Panics if the assertion fails.
  • Shorthand macros to create Log instances with different log levels.
  • Shorthand macros to create Log instances with different log levels.
  • Shorthand macros to create Log instances with different log levels.
  • Shorthand macro to create a Log with the given log level.
  • Returns the maximum of the given values.
  • Returns the minimum of the given values.

Traits

  • A marker trait used to indicate that an RngCore or BlockRngCore implementation is supposed to be cryptographically secure.
  • The core of a random number generator.