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

§Macros

The KyberLib crate provides several macros to simplify common cryptographic operations:

See the macros module documentation for more details and usage examples.

§Errors

The KyberLibError enum handles errors with 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).

Re-exports§

Modules§

  • api
    API for the KyberLib library.
  • error
    Error types for the KyberLib library.
  • kem
    Key encapsulation module for the KyberLib library.
  • kex
    Key exchange structs for the KyberLib library.
  • macros
    Macro utilities for the KyberLib library.
  • params
    Parameters for the KyberLib library.
  • reference
    Reference implementation for the KyberLib library.
  • rng
    Random number generators for the KyberLib library.
  • symmetric
    Symmetric key encapsulation module for the KyberLib library.
  • wasm
    WebAssembly bindings for the KyberLib library.

Macros§

Traits§

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