Crate pqc_kyber

source ·
Expand description

Kyber

A rust implementation of the Kyber algorithm

This library:

  • Is no_std compatible and uses no allocations, suitable for embedded devices.
  • The reference files contain no unsafe code.
  • On x86_64 platforms uses an optimized avx2 version by default.
  • Compiles to WASM using wasm-bindgen.

Features

If no security level is set then kyber768 is used, this is roughly equivalent to AES-196. See below for setting other levels. A compile-time error is raised if more than one level is specified. Besides that all other features can be mixed as needed:

FeatureDescription
kyber512Enables kyber512 mode, with a security level roughly equivalent to AES-128.
kyber1024Enables kyber1024 mode, with a security level roughly equivalent to AES-256.
90s90’s mode uses SHA2 and AES-CTR as a replacement for SHAKE. This may provide hardware speedups on certain architectures.
avx2On x86_64 platforms enable the optimized version. This flag is will cause a compile error on other architectures.
wasmFor compiling to WASM targets.
nasmUses Netwide Assembler avx2 code instead of GAS for portability. Requires a nasm compiler: https://www.nasm.us/
zeroizeThis will zero out the key exchange structs on drop using the zeroize crate
stdEnable the standard library

Usage

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"

use pqc_kyber::*;
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);

Higher level functions offering unilateral or mutual authentication

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

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

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

Follows the same workflow except Bob requires Alice’s public key

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 KyberError enum handles errors. It has two variants:

  • InvalidInput - One or more byte inputs to a function are incorrectly sized. A likely 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

Structs

  • Ake
    Used for mutually authenticated key exchange between two parties.
  • Keypair
    A public/secret keypair for use with Kyber.
  • Uake
    Used for unilaterally authenticated key exchange between two parties.

Enums

Constants

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.

Functions

  • decapsulate
    Decapsulates ciphertext with a secret key, the result will contain a KyberError if decapsulation fails
  • derive
    Deterministically derive a keypair from a seed as specified in draft-schwabe-cfrg-kyber.
  • encapsulate
    Encapsulates a public key returning the ciphertext to send and the shared secret
  • keypair
    Keypair generation with a provided RNG.
  • public
    Extracts public key from private key.

Type Definitions