crypto::mlkem
mlkem: Module-Lattice-Based Key-Encapsulation Mechanism
This module implements ML-KEM, a quantum-resistant key encapsulation method (formerly known as Kyber), as specified in NIST FIPS 203.
A typical encapsulation round trip generates a decapsulation key, derives the corresponding encapsulation key, encapsulates a shared key, and decapsulates it again:
let dk: dk768 = @undefined;
dk768_gen(&dk);
let ek: ek768 = @undefined;
dk768_ek(&dk, &ek);
let ciphertext: [CT768SZ]u8 = @undefined;
let enc_key: [SHAREDKEYSZ]u8 = @undefined;
ek768_encap(&ek, ciphertext[..], enc_key[..]);
let dec_key: [SHAREDKEYSZ]u8 = @undefined;
dk768_decap(&dk, ciphertext[..], dec_key[..]);
The shared keys in enc_key and dec_key are equal after successful decapsulation. Failed decapsulations generate a pseudorandom invalid secret as part of implicit rejection.
This is a low-level module which implements cryptographic primitives. Direct use of cryptographic primitives is not recommended for non-experts, as incorrect use of these primitives can easily lead to the introduction of security vulnerabilities. Non-experts are advised to use the high-level operations available in the top-level crypto:: module.
Be advised that Hare's cryptography implementations have not been audited.
Index
Types
type dk768;
type ek768;
type dk768_ikey;
type ek768_ikey;
type field_element;
type ntt_element;
type ring_element;
Constants
def CT768SZ: size = 1088;
def EK768SZ: size = 1184;
def SEEDSZ: size = 64;
def SHAREDKEYSZ: size = 32;
Functions
fn dk768_decap(key: *dk768, ciphertext: []u8, out: []u8) void;
fn dk768_ek(key: *dk768, out: *ek768) void;
fn dk768_from_seed(out: *dk768, seed: []u8) void;
fn dk768_gen(out: *dk768) void;
fn dk768_seed(key: *dk768, out: []u8) void;
fn ek768_decode(key: *ek768, encoded: []u8) (void | errors::invalid);
fn ek768_encap(key: *ek768, ciphertext: []u8, out: []u8) void;
fn ek768_encode(key: *ek768, out: []u8) void;
Types
type dk768
type dk768 = struct {
d: [32]u8,
z: [32]u8,
rho: [32]u8,
h: [32]u8,
ek: ek768_ikey,
dk: dk768_ikey,
};
Secret key used to decapsulate a shared key from a ciphertext.
type ek768
type ek768 = struct {
rho: [32]u8,
h: [32]u8,
ik: ek768_ikey,
};
Public key used to produce ciphertexts to be decapsulated by the corresponding dk768.
type dk768_ikey
Show undocumented member
type dk768_ikey = struct {
s: [K]ntt_element,
};
type ek768_ikey
Show undocumented member
type ek768_ikey = struct {
t: [K]ntt_element,
a: [K * K]ntt_element,
};
type field_element
Show undocumented member
type field_element = u16;
type ntt_element
Show undocumented member
type ntt_element = [N]field_element;
type ring_element
Show undocumented member
type ring_element = [N]field_element;
Constants
def CT768SZ
def CT768SZ: size = 1088;
The size of a ciphertext produced by ML-KEM-768.
def EK768SZ
def EK768SZ: size = 1184;
The size of an ML-KEM-768 encapsulation key.
def SEEDSZ
def SEEDSZ: size = 64;
The size of a seed used to generate a decapsulation key.
def SHAREDKEYSZ
def SHAREDKEYSZ: size = 32;
The size of a shared key produced by ML-KEM.
Functions
fn dk768_decap
fn dk768_decap(key: *dk768, ciphertext: []u8, out: []u8) void;
Generates a secret key from a ciphertext and decapsulation key.
fn dk768_ek
fn dk768_ek(key: *dk768, out: *ek768) void;
Return the public encapsulation key necessary to produce ciphertexts.
fn dk768_from_seed
fn dk768_from_seed(out: *dk768, seed: []u8) void;
Initializes a decapsulation key from a 64-byte seed. The seed must be uniformly random.
fn dk768_gen
fn dk768_gen(out: *dk768) void;
Generate a new decapsulation key, drawing random bytes from a secure source.
The decapsulation key must be kept secret.
fn dk768_seed
fn dk768_seed(key: *dk768, out: []u8) void;
Return the decapsulation key as a 64-byte seed in the "d || z" form.
The decapsulation key must be kept secret.
fn ek768_decode
fn ek768_decode(key: *ek768, encoded: []u8) (void | errors::invalid);
Parse an encapsulation key from its encoded form.
fn ek768_encap
fn ek768_encap(key: *ek768, ciphertext: []u8, out: []u8) void;
Generate a shared key and an associated ciphertext from an encapsulation key, drawing random bytes from a secure source.
The shared key must be kept secret.
fn ek768_encode
fn ek768_encode(key: *ek768, out: []u8) void;
Return the encapsulation key as serialized bytes.