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::OsRng;

let alg = Algorithm::FrodoKem640Shake;
let (ek, dk) = alg.try_generate_keypair(OsRng).unwrap();
let (ct, enc_ss) = alg.try_encapsulate_with_rng(&ek, OsRng).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 ISO Standard Annex.

use frodo_kem_rs::Algorithm;
use rand_core::{TryRngCore, OsRng};

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

// Ephemeral method, no salt required
let alg = Algorithm::EphemeralFrodoKem1344Shake;
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.

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