Crate cosmian_kyber

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:

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.

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

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