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 Kyber764 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.
reference	On x86_64 platforms the optimized version is used by default. Enabling this feature will force usage of the reference codebase. This is unnecessary on other architectures
wasm	For compiling to WASM targets.

Usage

use pqc_kyber::*;

The higher level structs will be appropriate for most use-cases. Both unilateral or mutually authenticated key exchanges are possible.

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

Mutual authentication follows the same workflow but with additional keys passed to the functions:

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

Key Encapsulation

Lower level functions for using the Kyber algorithm directly.

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

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
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
encapsulate	Encapsulates a public key returning the ciphertext to send and the shared secret
keypair	Keypair generation with a provided RNG.

Type Definitions

AkeSendInit	Bytes to send when initiating a mutual key exchange
AkeSendResponse	Bytes to send when responding to a mutual key exchange
Decapsulated	The result of decapsulating a ciphertext which produces a shared secret when confirmed
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