mlkem.auxiliary

This module is only relevant to the pure python implementation and does not apply to the default (C extension) implementation of this package.

mlkem.auxiliary.crypto

class mlkem.auxiliary.crypto.XOF

An eXtendable-Output Function that provides an incremental API for SHAKE-128.

absorb(string: bytes) → None

Inject data into SHAKE-128 and update the context.

Args:: string (bytes): The data being injected.

squeeze(length: int) → bytes

Extract output bytes from SHAKE-128 and update the context.

Args:: length (int): The number of bytes to extract.
returns:: bytes:n The extracted bytes.

mlkem.auxiliary.crypto.g(c: bytes) → tuple[bytes, bytes]

An alias for the SHA3-512 hash function.

The resulting 64 byte output is split into two 32 bytes values.

Args:: s (bytes): The input to be hashed.
Returns:: tuple[bytes, bytes]: The digest of the input, split into two equal-sized values.

mlkem.auxiliary.crypto.h(s: bytes) → bytes

An alias for the SHA3-256 hash function.

Args:: s (bytes): The input to be hashed.
Returns:: bytes: The digest of the input.

mlkem.auxiliary.crypto.j(s: bytes) → bytes

An alias for the SHAKE-256 hash function.

Args:: s (bytes): The input to be hashed.
Returns:: bytes: A 32 byte digest of the input.

mlkem.auxiliary.crypto.prf(eta: int, s: bytes, b: bytes) → bytes

A pseudorandom function based on SHAKE-256.

Args:: eta (int): A parameter of the ML-KEM instance.

s (bytes): A seed of 32 bytes.

b (bytes): The byte encoding of a counter.
Returns:: bytes: 64 * eta pseudorandom bytes.

mlkem.auxiliary.general

mlkem.auxiliary.general.bits_to_bytes(bits: list[int]) → list[int]

Converts a bit array (of a length that is a multiple of 8) into an array of bytes.

Bytes are represented as unsigned numbers in the range [0, 255]. Bits are either 0 or 1.

Args:: bits (list[int]): The bit array (of a length that is a multiple of 8).
Returns:: list[int]: The array of bytes equivalent to the bit array.

mlkem.auxiliary.general.byte_decode(d: int, b: bytes) → list[Zm]

Decode bytes into a list of integers.

Bytes are parsed as d-bit integers, with \(1 \le d \le 12\).

Args:: d (int): The bit size of the integers in the list.

b (bytes): The byte-encoding of an integer list.
Returns:: list[mlkem.math.field.Zm]: The decoded integer list. If d=12 then the field order is mlkem.math.constants.q, otherwise it is 2**d.

mlkem.auxiliary.general.byte_encode(d: int, f: list[Zm]) → bytes

Encode a list of integers into bytes.

The integers are all interpreted as d-bits in size, with \(1 \le d \le 12\).

Args:: d (int): The bit size of the integers in the list.

f (list[mlkem.math.field.Zm]): The integer list. If d=12 then the field order is mlkem.math.constants.q, otherwise it is 2**d.
Returns:: bytes: The byte-encoding of the integer list.

mlkem.auxiliary.general.bytes_to_bits(byts: list[int]) → list[int]

Converts a byte array into an array of bits.

Bytes are represented as unsigned numbers in the range [0, 255]. Bits are either 0 or 1.

Args:: byts (list[int]): The byte array.
Returns:: list[int]: The array of bits equivalent to the byte array.

mlkem.auxiliary.general.compress(d: int, x: Zm) → Zm

Map an element from \(\mathbb{Z}_q\) to \(\mathbb{Z}_{2^d}\).

Note that \(q\) is 12 bits and \(d\) must be less than 12 bits, so this operation is always lossy.

Args:: d (int): The number of bits (0 < d < 12) to compress x to.

x (mlkem.math.field.Zm): An element of \(\mathbb{Z}_q\).
Returns:: mlkem.math.field.Zm: x compressed to an element of \(\mathbb{Z}_{2^d}\).

mlkem.auxiliary.general.decompress(d: int, y: Zm) → Zm

Map an element from \(\mathbb{Z}_{2^d}\) to \(\mathbb{Z}_q\).

Args:: d (int): The number of bits (0 < d < 12) to decompress x from.

x (mlkem.math.field.Zm): An element of \(\mathbb{Z}_{2^d}\).
Returns:: mlkem.math.field.Zm: x decompressed to an element of \(\mathbb{Z}_q\).

mlkem.auxiliary.ntt

mlkem.auxiliary.ntt.multiply_ntt(f_: PolynomialRing, g_: PolynomialRing) → PolynomialRing

Computes the product (in the ring \(T_q\)) of two NTT representations.

Note that f_.representation and g_.representation must be RingRepresentation.NTT, otherwise a ValueError will be raised.

Args:

f_ (mlkem.math.polynomial_ring.PolynomialRing): A multiplication operand.

f_ (mlkem.math.polynomial_ring.PolynomialRing): A multiplication operand.

Returns:: mlkem.math.polynomial_ring.PolynomialRing: The polynomial \(\hat{h} (\in T_q) = \hat{f} \cdot \hat{g}\).

mlkem.auxiliary.ntt.ntt(f: PolynomialRing) → PolynomialRing

Computes the NTT representation \(\hat{f}\) of the given polynomial \(f \in R_q\).

Note that f.representation must be RingRepresentation.STANDARD, otherwise a ValueError will be raised.

Args:: f (mlkem.math.polynomial_ring.PolynomialRing): The polynomial to perform the transform on.
Return:: mlkem.math.polynomial_ring.PolynomialRing: The NTT representation of f.

mlkem.auxiliary.ntt.ntt_inv(f_: PolynomialRing) → PolynomialRing

Computes the polynomial \(f \in R_q\) that corresponds to the NTT representation \(\hat{f} \in T_q\).

Note that f_.representation must be RingRepresentation.NTT, otherwise a ValueError will be raised.

Args:: f_ (mlkem.math.polynomial_ring.PolynomialRing): The polynomial to perform the transform on.
Return:: mlkem.math.polynomial_ring.PolynomialRing: The standard representation of f_.

mlkem.auxiliary.sampling

mlkem.auxiliary.sampling.sample_ntt(b: bytes) → PolynomialRing

Take a seed and two indices and sample a pseudorandom elements in \(T_q\).

Args:: b (bytes): A 32-byte seed concatenated with two one byte indices as seed + i0 + i1.
Returns:: mlkem.math.polynomial_ring.PolynomialRing: A polynomial in NTT representation.

mlkem.auxiliary.sampling.sample_poly_cbd(eta: int, b: bytes) → PolynomialRing

Take a seed and output a sample from the distribution \(\mathcal{D}_{\eta}(R_q)\).

The distribution \(\mathcal{D}_{\eta}(R_q)\) is a special distribution of polynomials in \(R_q\) with small coefficients. These are used as “noise” (or, for those familiar with *LWE terminology, “error”) terms in the ML-KEM algorithm.

Args:: eta (int): A parameter of the ML-KEM instance determining the distribution of the noise.

b (bytes): A 64 * eta-byte seed.
Returns:: mlkem.math.polynomial_ring.PolynomialRing: A polynomial with small coefficients.