Table of Contents

Interface IKem

Namespace
CryptoHives.Foundation.Security.Cryptography.Kem
Assembly
CryptoHives.Foundation.Security.Cryptography.dll

Defines a Key Encapsulation Mechanism (KEM).

public interface IKem : IDisposable
Inherited Members

Remarks

A KEM provides three operations: key generation, encapsulation, and decapsulation. Encapsulation produces a shared secret and a ciphertext that can be sent to the holder of the corresponding decapsulation key, who can recover the same shared secret.

Common KEM algorithms:

  • ML-KEM-512 (FIPS 203, security category 1)
  • ML-KEM-768 (FIPS 203, security category 3)
  • ML-KEM-1024 (FIPS 203, security category 5)

Properties

AlgorithmName

Gets the algorithm name.

string AlgorithmName { get; }

Property Value

string

CiphertextSizeBytes

Gets the ciphertext size in bytes.

int CiphertextSizeBytes { get; }

Property Value

int

DecapsulationKeySizeBytes

Gets the decapsulation key size in bytes.

int DecapsulationKeySizeBytes { get; }

Property Value

int

EncapsulationKeySizeBytes

Gets the encapsulation key size in bytes.

int EncapsulationKeySizeBytes { get; }

Property Value

int

SharedSecretSizeBytes

Gets the shared secret size in bytes.

int SharedSecretSizeBytes { get; }

Property Value

int

Methods

Decapsulate(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>)

Decapsulates the shared secret from the ciphertext using the decapsulation key.

void Decapsulate(ReadOnlySpan<byte> decapsulationKey, ReadOnlySpan<byte> ciphertext, Span<byte> sharedSecret)

Parameters

decapsulationKey ReadOnlySpan<byte>

The decapsulation (private) key.

ciphertext ReadOnlySpan<byte>

The ciphertext produced by encapsulation.

sharedSecret Span<byte>

The buffer to receive the shared secret.

Remarks

ML-KEM uses implicit rejection: if decapsulation fails, a pseudorandom value derived from the ciphertext and a secret value is returned instead of an error.

Exceptions

ArgumentException

decapsulationKey, ciphertext, or sharedSecret has an invalid size.

Encapsulate(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, Span<byte>)

Encapsulates a shared secret using the encapsulation key with a deterministic seed.

void Encapsulate(ReadOnlySpan<byte> encapsulationKey, ReadOnlySpan<byte> seed, Span<byte> ciphertext, Span<byte> sharedSecret)

Parameters

encapsulationKey ReadOnlySpan<byte>

The encapsulation (public) key.

seed ReadOnlySpan<byte>

The 32-byte random seed (m) for deterministic encapsulation.

ciphertext Span<byte>

The buffer to receive the ciphertext.

sharedSecret Span<byte>

The buffer to receive the shared secret.

Exceptions

ArgumentException

Any parameter has an invalid size.

Encapsulate(ReadOnlySpan<byte>, Span<byte>, Span<byte>)

Encapsulates a shared secret using the encapsulation key.

void Encapsulate(ReadOnlySpan<byte> encapsulationKey, Span<byte> ciphertext, Span<byte> sharedSecret)

Parameters

encapsulationKey ReadOnlySpan<byte>

The encapsulation (public) key.

ciphertext Span<byte>

The buffer to receive the ciphertext.

sharedSecret Span<byte>

The buffer to receive the shared secret.

Exceptions

ArgumentException

encapsulationKey has an invalid size, or ciphertext or sharedSecret is too small.

GenerateKeyPair(ReadOnlySpan<byte>, Span<byte>, Span<byte>)

Generates an encapsulation key and a decapsulation key using the provided seed.

void GenerateKeyPair(ReadOnlySpan<byte> seed, Span<byte> encapsulationKey, Span<byte> decapsulationKey)

Parameters

seed ReadOnlySpan<byte>

The deterministic seed (d ‖ z) for key generation.

encapsulationKey Span<byte>

The buffer to receive the encapsulation (public) key.

decapsulationKey Span<byte>

The buffer to receive the decapsulation (private) key.

Exceptions

ArgumentException

seed, encapsulationKey, or decapsulationKey has an invalid size.

GenerateKeyPair(ReadOnlySpan<byte>, Span<byte>, Span<byte>, bool)

Generates a key pair from a seed, optionally skipping the pairwise consistency test.

void GenerateKeyPair(ReadOnlySpan<byte> seed, Span<byte> encapsulationKey, Span<byte> decapsulationKey, bool pairwiseConsistencyTest)

Parameters

seed ReadOnlySpan<byte>

The deterministic seed (d ‖ z) for key generation.

encapsulationKey Span<byte>

The buffer to receive the encapsulation (public) key.

decapsulationKey Span<byte>

The buffer to receive the decapsulation (private) key.

pairwiseConsistencyTest bool

true to verify the generated key pair; false to skip it.

Exceptions

ArgumentException

A parameter has an invalid size.

GenerateKeyPair(Span<byte>, Span<byte>)

Generates an encapsulation key and a decapsulation key.

void GenerateKeyPair(Span<byte> encapsulationKey, Span<byte> decapsulationKey)

Parameters

encapsulationKey Span<byte>

The buffer to receive the encapsulation (public) key.

decapsulationKey Span<byte>

The buffer to receive the decapsulation (private) key.

Exceptions

ArgumentException

encapsulationKey or decapsulationKey is too small.

GenerateKeyPair(Span<byte>, Span<byte>, bool)

Generates a key pair, optionally skipping the pairwise consistency test.

void GenerateKeyPair(Span<byte> encapsulationKey, Span<byte> decapsulationKey, bool pairwiseConsistencyTest)

Parameters

encapsulationKey Span<byte>

The buffer to receive the encapsulation (public) key.

decapsulationKey Span<byte>

The buffer to receive the decapsulation (private) key.

pairwiseConsistencyTest bool

true to verify the generated key pair with an encapsulate/decapsulate round trip; false to skip it. See the remarks on the KEM type.

Exceptions

ArgumentException

A buffer is too small.

Edit this page