MLKEM Class

Properties   Methods   Events   Config Settings   Errors  

The MLKEM class can be used to establish a shared secret key through Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) cryptography.

Syntax

class ipworksencrypt.MLKEM

Remarks

The MLKEM component can be used to establish a shared secret key through Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) cryptography. Includes support for ML-KEM-512, ML-KEM-768, and ML-KEM-1024 parameter sets.

Note that by default the component uses ML-KEM-512. You may specify the parameter set by setting ParamSet.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

cipher_text property

The cipher text.

Syntax

def get_cipher_text() -> bytes: ...
def set_cipher_text(value: bytes) -> None: ...

cipher_text = property(get_cipher_text, set_cipher_text)

Default Value

""

Remarks

This property holds the ML-KEM ciphertext.

It is populated by encapsulate and must be set before calling decapsulate.

key_private_key property

The raw ML-KEM private key.

Syntax

def get_key_private_key() -> bytes: ...
def set_key_private_key(value: bytes) -> None: ...

key_private_key = property(get_key_private_key, set_key_private_key)

Default Value

""

Remarks

The raw ML-KEM private key.

key_public_key property

The raw ML-KEM public key.

Syntax

def get_key_public_key() -> bytes: ...
def set_key_public_key(value: bytes) -> None: ...

key_public_key = property(get_key_public_key, set_key_public_key)

Default Value

""

Remarks

The raw ML-KEM public key.

shared_secret property

The computed shared secret.

Syntax

def get_shared_secret() -> bytes: ...

shared_secret = property(get_shared_secret, None)

Default Value

""

Remarks

This property holds the shared secret computed by encapsulate or decapsulate.

This property is read-only.

use_hex property

Whether binary values are hex encoded.

Syntax

def get_use_hex() -> bool: ...
def set_use_hex(value: bool) -> None: ...

use_hex = property(get_use_hex, set_use_hex)

Default Value

FALSE

Remarks

This property specifies whether cipher_text and shared_secret are hex encoded when encapsulate is called.

If set to False (default), values are provided as-is with no encoding.

When decapsulate is called and this property is set to True, cipher_text is treated as hex encoded and shared_secret is hex encoded when populated.

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

create_key method

Creates a new key.

Syntax

def create_key() -> None: ...

Remarks

create_key creates a new ML-KEM public and private key pair.

When this method is called, key is populated with the generated raw public and private key values. The parameter set is controlled by the ParamSet configuration setting.

decapsulate method

Decapsulates a shared secret.

Syntax

def decapsulate() -> None: ...

Remarks

This method uses the private key in key and the ciphertext in cipher_text to recover the shared secret.

The shared secret is available from shared_secret.

encapsulate method

Encapsulates a shared secret.

Syntax

def encapsulate() -> None: ...

Remarks

This method uses the public key in key to generate a shared secret and ciphertext.

The generated shared secret is available from shared_secret, and the ciphertext is available from cipher_text.

reset method

Resets the class.

Syntax

def reset() -> None: ...

Remarks

When called, the class will reset all of its properties to their default values.

on_error event

Fired when information is available about errors during data delivery.

Syntax

class MLKEMErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class MLKEM:
@property
def on_error() -> Callable[[MLKEMErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[MLKEMErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

MLKEM Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

MLKEM Config Settings

Base Config Settings

MLKEM Errors

MLKEM Errors