Crate safe_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.
• 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.
wasm	For compiling to WASM targets.
zeroize	This will zero out the key exchange structs on drop using the zeroize crate
std	Enable the standard library

Usage

use safe_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_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
  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