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. |
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
- Used for mutually authenticated key exchange between two parties.
- A public/secret keypair for use with Kyber.
- Used for unilaterally authenticated key exchange between two parties.
Enums
- Error types for the failure modes
Constants
- Mutual Key Exchange Initiation Byte Length
- Mutual Key Exchange Response Byte Length
- A boolean flag for whether 90’s mode is activated.
- Size in bytes of the Kyber ciphertext
- The security level of Kyber
- Size in bytes of the Kyber public key
- Size in bytes of the Kyber secret key
- Size of the shared key
- Unilateral Key Exchange Initiation Byte Length
- Unilateral Key Exchange Response Byte Length
Traits
- A marker trait used to indicate that an
RngCore
orBlockRngCore
implementation is supposed to be cryptographically secure. - The core of a random number generator.
Functions
- Decapsulates ciphertext with a secret key, the result will contain a KyberError if decapsulation fails
- Deterministically derive a keypair from a seed as specified in draft-schwabe-cfrg-kyber.
- Encapsulates a public key returning the ciphertext to send and the shared secret
- Keypair generation with a provided RNG.
- Extracts public key from private key.
Type Definitions
- Bytes to send when initiating a mutual key exchange
- Bytes to send when responding to a mutual key exchange
- Decapsulated ciphertext
- Result of encapsulating a public key which includes the ciphertext and shared secret
- Kyber public key
- Kyber secret key
- Kyber Shared Secret
- Bytes to send when initiating a unilateral key exchange
- Bytes to send when responding to a unilateral key exchange