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§

pub use error::KyberLibError;
pub use params::KYBER_90S;
pub use params::KYBER_CIPHERTEXT_BYTES;
pub use params::KYBER_PUBLIC_KEY_BYTES;
pub use params::KYBER_SECRET_KEY_BYTES;
pub use params::KYBER_SECURITY_PARAMETER;
pub use params::KYBER_SHARED_SECRET_BYTES;
pub use params::KYBER_SYM_BYTES;
pub use api::*;
pub use kex::*;

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§

kyberlib_ake_client_confirm
Decapsulates and authenticates the shared secret from the output of kyberlib_ake_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_assert
Asserts that a given expression is true. Panics if the assertion fails.
kyberlib_decrypt_message
Generates a shared secret for a given cipher text and private key.
kyberlib_encrypt_message
Generates cipher text and a shared secret for a given public key.
kyberlib_generate_key_pair
Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.
kyberlib_max
Returns the maximum of the given values.
kyberlib_min
Returns the minimum of the given values.
kyberlib_uake_client_confirm
Decapsulates and authenticates the shared secret from the output of kyberlib_uake_server_receive().
kyberlib_uake_client_init
Initiates a Unilaterally Authenticated Key Exchange.
kyberlib_uake_server_receive
Handles the output of a kyberlib_uake_client_init() request.

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.