Crate pqc_kyber 

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:

Feature	Description
kyber512	Enables kyber512 mode, with a security level roughly equivalent to AES-128.
kyber1024	Enables kyber1024 mode, with a security level roughly equivalent to AES-256.
90s	90’s mode uses SHA2 and AES-CTR as a replacement for SHAKE. This may provide hardware speedups on certain architectures.
avx2	On x86_64 platforms enable the optimized version. This flag is will cause a compile error on other architectures.
wasm	For compiling to WASM targets.
nasm	Uses Netwide Assembler avx2 code instead of GAS for portability. Requires a nasm compiler: https://www.nasm.us/
zeroize	This will zero out the key exchange structs on drop using the zeroize crate
std	Enable 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

KyberError

Error types for the failure modes

Constants

AKE_INIT_BYTES

Mutual Key Exchange Initiation Byte Length

AKE_RESPONSE_BYTES

Mutual Key Exchange Response Byte Length

KYBER_90S

A boolean flag for whether 90’s mode is activated.

KYBER_CIPHERTEXTBYTES

Size in bytes of the Kyber ciphertext

KYBER_K

The security level of Kyber

KYBER_PUBLICKEYBYTES

Size in bytes of the Kyber public key

KYBER_SECRETKEYBYTES

Size in bytes of the Kyber secret key

KYBER_SSBYTES

Size of the shared key

KYBER_SYMBYTES

UAKE_INIT_BYTES

Unilateral Key Exchange Initiation Byte Length

UAKE_RESPONSE_BYTES

Unilateral Key Exchange Response Byte Length

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 Aliases

AkeSendInit

Bytes to send when initiating a mutual key exchange

AkeSendResponse

Bytes to send when responding to a mutual key exchange

Decapsulated

Decapsulated ciphertext

Encapsulated

Result of encapsulating a public key which includes the ciphertext and shared secret

PublicKey

Kyber public key

SecretKey

Kyber secret key

SharedSecret

Kyber Shared Secret

UakeSendInit

Bytes to send when initiating a unilateral key exchange

UakeSendResponse

Bytes to send when responding to a unilateral key exchange