Skip to main content

Crate frodo_kem

Crate frodo_kem 

Source
Expand description

§RustCrypto Frodo-KEM

Crate Docs Build Apache2/MIT licensed MSRV

A pure rust implementation of

It’s submission was included in NIST’s PQ Round 3 competition, and is now being standardized at ISO.

§⚠️ Security Warning

This crate has been tested against the test vectors provided by the FrodoKEM team and been rigorously tested for correctness, performance, and security. It has also been tested against opensafequatum’s liboqs library to compatibility and correctness.

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!

§Details

This crate provides the following FrodoKEM algorithms:

  • FrodoKEM-640-AES ✅
  • FrodoKEM-976-AES ✅
  • FrodoKEM-1344-AES ✅
  • FrodoKEM-640-SHAKE ✅
  • FrodoKEM-976-SHAKE ✅
  • FrodoKEM-1344-SHAKE ✅
  • eFrodoKEM-640-AES ✅
  • eFrodoKEM-976-AES ✅
  • eFrodoKEM-1344-AES ✅
  • eFrodoKEM-640-SHAKE ✅
  • eFrodoKEM-976-SHAKE ✅
  • eFrodoKEM-1344-SHAKE ✅

eFrodoKEM is a variant of FrodoKEM that is meant to be used one-time only. Using more than once is considered a security risk.

When in doubt use the FrodoKEM algorithm variants.

§Expanding matrix A

§NOTE on AES

To speed up AES, there are a few options available:

  • RUSTFLAGS="--cfg aes_armv8" cargo build --release ensures that the ARMv8 AES instructions are used if available.
  • frodo-kem = { version = "0.3", features = ["openssl"] } uses the openssl crate for AES.

By default, the aes feature auto-detects the best AES implementation for your platform for x86 and x86_64, but not on ARMv8 where it defaults to the software implementation as of this writing. To enable the ARMv8 AES instructions, the aes_armv8 feature is enabled in the .cargo/config file in this crate.

Enabling openssl and aesni provides the fastest Aes algorithms.

openssl tends to be faster than the aes rust crate implementation by about 10-15% on Armv8.

§NOTE on SHAKE

Shake auto detects the best implementation for your platform or like AES you can enable openssl for it also.

On Armv8, the rust shake implementation is faster than the openssl implementation by about 22-25%.

§Serialization

This crate has been tested against the following serde compatible formats:

  • serde_bare
  • postcard
  • serde_cbor
  • serde_json
  • serde_yaml
  • toml

§Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

§License

Licensed under

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§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::Algorithm;
use getrandom::{SysRng, rand_core::UnwrapErr};

let mut rng = UnwrapErr(SysRng);
let alg = Algorithm::FrodoKem640Shake;
let (ek, dk) = alg.generate_keypair(&mut rng);
let (ct, enc_ss) = alg.encapsulate_with_rng(&ek, &mut rng).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::Algorithm;
use getrandom::{SysRng, rand_core::{Rng, UnwrapErr}};

let mut rng = UnwrapErr(SysRng);
let alg = Algorithm::FrodoKem1344Shake;
let params = alg.params();
let (ek, dk) = alg.generate_keypair(&mut rng);
// Key is known, generate
let aes_256_key = vec![3u8; params.message_length];
let mut salt = vec![0u8; params.salt_length];
rng.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();

// 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