Crate frodo_kem_rs 

Usage

The standard safe method for FrodoKEM is to use Algorithm, encapsulate a randomly generated value, and decapsulate it on the other side.

use frodo_kem_rs::Algorithm;
use rand_core::{CryptoRng, UnwrapErr};
use rand::rngs::SysRng;

let alg = Algorithm::FrodoKem640Shake;
let (ek, dk) = alg.generate_keypair(UnwrapErr(SysRng));
let (ct, enc_ss) = alg.encapsulate_with_rng(&ek, UnwrapErr(SysRng)).unwrap();
let (dec_ss, msg) = alg.decapsulate(&dk, &ct).unwrap();

assert_eq!(enc_ss, dec_ss);

If the message is known, it can be passed to the encapsulate. encapsulate will error if the message is not the correct size. This method also requires a salt for non-ephemeral algorithms, and the salt is considered public information.

Ephemeral variants are meant to be used one-time only and thus do not require a salt.

☢️️ WARNING: HAZARDOUS ☢️

It is considered unsafe to use Ephemeral algorithms more than once. For more information, see Clause 14 of ISO/IEC 18033-2:2006/Amd 2:2026.

use frodo_kem_rs::Algorithm;
use rand::rngs::SysRng;
use rand_core::{Rng, UnwrapErr};

let alg = Algorithm::FrodoKem1344Shake;
let params = alg.params();
let (ek, dk) = alg.generate_keypair(UnwrapErr(SysRng));
// Key is known, generate
let aes_256_key = vec![3u8; params.message_length];
let mut salt = vec![0u8; params.salt_length];
UnwrapErr(SysRng).fill_bytes(&mut salt);
let (ct, enc_ss) = alg.encapsulate(&ek, &aes_256_key, &salt).unwrap();
let (dec_ss, dec_msg) = alg.decapsulate(&dk, &ct).unwrap();

assert_eq!(enc_ss, dec_ss);
assert_eq!(&aes_256_key[..], dec_msg.as_slice());

// Ephemeral method: use a dedicated ephemeral keypair and no salt.
let alg = Algorithm::EphemeralFrodoKem1344Shake;
let (ek, dk) = alg.generate_keypair(UnwrapErr(SysRng));
let (ct, enc_ss) = alg.encapsulate(&ek, &aes_256_key, []).unwrap();
let (dec_ss, dec_msg) = alg.decapsulate(&dk, &ct).unwrap();

assert_eq!(enc_ss, dec_ss);
assert_eq!(&aes_256_key[..], dec_msg.as_slice());

Features

Each algorithm can be conditionally included/excluded as needed.

The structs used in this crate all optionally support the serde feature.

Custom

To create a custom implementation of FrodoKEM, use the hazmat feature, to access the necessary traits and models for creating a custom implementation. Be warned, this is not recommended unless you are sure of what you are doing.

Re-exports

pub use kem::DecapsulationKey as KemDecapsulationKey;

pub use kem::EncapsulationKey as KemEncapsulationKey;

Modules

kem

Implementations of the traits from the kem crate.

Structs

AlgorithmParams

The algorithm underlying parameters

Ciphertext

A FrodoKEM ciphertext key

DecryptionKey

A FrodoKEM secret key

EncryptionKey

A FrodoKEM public key

SharedSecret

A FrodoKEM shared secret

Enums

Algorithm

The supported FrodoKem algorithms

Error

The errors that can occur for FrodoKEM

Type Aliases

FrodoResult

The result type for FrodoKEM