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

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.

CipherText Property (MLKEM Class)

The cipher text.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetCipherText(char* &lpCipherText, int &lenCipherText);
int SetCipherText(const char* lpCipherText, int lenCipherText);

Unicode (Windows)
INT GetCipherText(LPSTR &lpCipherText, INT &lenCipherText);
INT SetCipherText(LPCSTR lpCipherText, INT lenCipherText);

int ipworksencrypt_mlkem_getciphertext(void* lpObj, char** lpCipherText, int* lenCipherText);
int ipworksencrypt_mlkem_setciphertext(void* lpObj, const char* lpCipherText, int lenCipherText);

QByteArray getCipherText();
int setCipherText(QByteArray qbaCipherText);

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

Key Property (MLKEM Class)

The ML-KEM key.

Syntax

• C++
• C
• Qt

IPWorksEncryptMLKEMKey* GetKey();
int SetKey(IPWorksEncryptMLKEMKey* val);

int ipworksencrypt_mlkem_getkeyprivatekey(void* lpObj, char** lpKeyPrivateKey, int* lenKeyPrivateKey);
int ipworksencrypt_mlkem_setkeyprivatekey(void* lpObj, const char* lpKeyPrivateKey, int lenKeyPrivateKey);

int ipworksencrypt_mlkem_getkeypublickey(void* lpObj, char** lpKeyPublicKey, int* lenKeyPublicKey);
int ipworksencrypt_mlkem_setkeypublickey(void* lpObj, const char* lpKeyPublicKey, int lenKeyPublicKey);

QByteArray getKeyPrivateKey();
int setKeyPrivateKey(QByteArray qbaKeyPrivateKey);

QByteArray getKeyPublicKey();
int setKeyPublicKey(QByteArray qbaKeyPublicKey);

Remarks

This property specifies the ML-KEM public or private key.

The public key is required before calling Encapsulate, and the private key is required before calling Decapsulate.

ML-KEM keys are made up of raw private key and public key fields.

PublicKey holds the public key.

PrivateKey holds the private key.

Data Type

IPWorksEncryptMLKEMKey

SharedSecret Property (MLKEM Class)

The computed shared secret.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSharedSecret(char* &lpSharedSecret, int &lenSharedSecret);

Unicode (Windows)
INT GetSharedSecret(LPSTR &lpSharedSecret, INT &lenSharedSecret);

int ipworksencrypt_mlkem_getsharedsecret(void* lpObj, char** lpSharedSecret, int* lenSharedSecret);

QByteArray getSharedSecret();

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 (MLKEM Class)

Whether binary values are hex encoded.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseHex();
int SetUseHex(int bUseHex);

Unicode (Windows)
BOOL GetUseHex();
INT SetUseHex(BOOL bUseHex);

int ipworksencrypt_mlkem_getusehex(void* lpObj);
int ipworksencrypt_mlkem_setusehex(void* lpObj, int bUseHex);

bool getUseHex();
int setUseHex(bool bUseHex);

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 (MLKEM Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksencrypt_mlkem_config(void* lpObj, const char* lpszConfigurationString);

QString config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateKey Method (MLKEM Class)

Creates a new key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateKey();

Unicode (Windows)
INT CreateKey();

int ipworksencrypt_mlkem_createkey(void* lpObj);

int createKey();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Decapsulate Method (MLKEM Class)

Decapsulates a shared secret.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Decapsulate();

Unicode (Windows)
INT Decapsulate();

int ipworksencrypt_mlkem_decapsulate(void* lpObj);

int decapsulate();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Encapsulate Method (MLKEM Class)

Encapsulates a shared secret.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Encapsulate();

Unicode (Windows)
INT Encapsulate();

int ipworksencrypt_mlkem_encapsulate(void* lpObj);

int encapsulate();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (MLKEM Class)

Resets the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksencrypt_mlkem_reset(void* lpObj);

int reset();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Error Event (MLKEM Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(MLKEMErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} MLKEMErrorEventParams;


Unicode (Windows)
virtual INT FireError(MLKEMErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} MLKEMErrorEventParams;

#define EID_MLKEM_ERROR 1

virtual INT IPWORKSENCRYPT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class MLKEMErrorEventParams {
public:
  int errorCode();

  const QString &description();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass MLKEM and override this emitter function.
virtual int fireError(MLKEMErrorEventParams *e) {...}
// Or, connect one or more slots to this signal.
void error(MLKEMErrorEventParams *e);

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.

MLKEMKey Type

Contains a raw ML-KEM key.

Syntax

IPWorksEncryptMLKEMKey (declared in ipworksencrypt.h)

Remarks

This type contains the raw public and private key values used by the MLKEM component.

• PrivateKey
• PublicKey

Fields

Constructors

MLKEMKey()

MLKEMKey(const char* lpPublicKey, int lenPublicKey)

MLKEMKey(const char* lpPublicKey, int lenPublicKey, const char* lpPrivateKey, int lenPrivateKey)

Config Settings (MLKEM Class)

MLKEM Config Settings

Base Config Settings

Trappable Errors (MLKEM Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

MLKEM Errors