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.

Class Name

IPWorksEncrypt_MLKEM

Procedural Interface

 ipworksencrypt_mlkem_open();
 ipworksencrypt_mlkem_close($res);
 ipworksencrypt_mlkem_register_callback($res, $id, $function);
 ipworksencrypt_mlkem_get_last_error($res);
 ipworksencrypt_mlkem_get_last_error_code($res);
 ipworksencrypt_mlkem_set($res, $id, $index, $value);
 ipworksencrypt_mlkem_get($res, $id, $index);
 ipworksencrypt_mlkem_do_config($res, $configurationstring);
 ipworksencrypt_mlkem_do_createkey($res);
 ipworksencrypt_mlkem_do_decapsulate($res);
 ipworksencrypt_mlkem_do_encapsulate($res);
 ipworksencrypt_mlkem_do_reset($res);

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.

CipherText Property (IPWorksEncrypt_MLKEM Class)

The cipher text.

Object Oriented Interface

public function getCipherText();
public function setCipherText($value);

Procedural Interface

ipworksencrypt_mlkem_get($res, 1 );
ipworksencrypt_mlkem_set($res, 1, $value );

Default Value

''

Remarks

This property holds the ML-KEM ciphertext.

It is populated by Encapsulate and must be set before calling Decapsulate.

Data Type

Binary String

KeyPrivateKey Property (IPWorksEncrypt_MLKEM Class)

The raw ML-KEM private key.

Object Oriented Interface

public function getKeyPrivateKey();
public function setKeyPrivateKey($value);

Procedural Interface

ipworksencrypt_mlkem_get($res, 2 );
ipworksencrypt_mlkem_set($res, 2, $value );

Default Value

''

Remarks

The raw ML-KEM private key.

Data Type

Binary String

KeyPublicKey Property (IPWorksEncrypt_MLKEM Class)

The raw ML-KEM public key.

Object Oriented Interface

public function getKeyPublicKey();
public function setKeyPublicKey($value);

Procedural Interface

ipworksencrypt_mlkem_get($res, 3 );
ipworksencrypt_mlkem_set($res, 3, $value );

Default Value

''

Remarks

The raw ML-KEM public key.

Data Type

Binary String

SharedSecret Property (IPWorksEncrypt_MLKEM Class)

The computed shared secret.

Object Oriented Interface

public function getSharedSecret();

Procedural Interface

ipworksencrypt_mlkem_get($res, 4 );

Default Value

''

Remarks

This property holds the shared secret computed by Encapsulate or Decapsulate.

This property is read-only.

Data Type

Binary String

UseHex Property (IPWorksEncrypt_MLKEM Class)

Whether binary values are hex encoded.

Object Oriented Interface

public function getUseHex();
public function setUseHex($value);

Procedural Interface

ipworksencrypt_mlkem_get($res, 5 );
ipworksencrypt_mlkem_set($res, 5, $value );

Default Value

false

Remarks

This property specifies whether CipherText and SharedSecret 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, CipherText is treated as hex encoded and SharedSecret is hex encoded when populated.

Data Type

Boolean

Config Method (IPWorksEncrypt_MLKEM Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

ipworksencrypt_mlkem_do_config($res, $configurationstring);

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.

CreateKey Method (IPWorksEncrypt_MLKEM Class)

Creates a new key.

Object Oriented Interface

public function doCreateKey();

Procedural Interface

ipworksencrypt_mlkem_do_createkey($res);

Remarks

CreateKey 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 (IPWorksEncrypt_MLKEM Class)

Decapsulates a shared secret.

Object Oriented Interface

public function doDecapsulate();

Procedural Interface

ipworksencrypt_mlkem_do_decapsulate($res);

Remarks

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

The shared secret is available from SharedSecret.

Encapsulate Method (IPWorksEncrypt_MLKEM Class)

Encapsulates a shared secret.

Object Oriented Interface

public function doEncapsulate();

Procedural Interface

ipworksencrypt_mlkem_do_encapsulate($res);

Remarks

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

The generated shared secret is available from SharedSecret, and the ciphertext is available from CipherText.

Reset Method (IPWorksEncrypt_MLKEM Class)

Resets the class.

Object Oriented Interface

public function doReset();

Procedural Interface

ipworksencrypt_mlkem_do_reset($res);

Remarks

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

Error Event (IPWorksEncrypt_MLKEM Class)

Fired when information is available about errors during data delivery.

Object Oriented Interface

public function fireError($param);

Procedural Interface

ipworksencrypt_mlkem_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

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

The ErrorCode 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.

Config Settings (MLKEM Class)

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

Trappable Errors (MLKEM Class)

MLKEM Errors