# MLKEM Class

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

## Syntax

**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](#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.*

|  |  |
| --- | --- |
| [CipherText](#mlkemciphertext-property) | The cipher text. |
| [Key](#mlkemkey-property) | The ML-KEM key. |
| [SharedSecret](#mlkemsharedsecret-property) | The computed shared secret. |
| [UseHex](#mlkemusehex-property) | Whether binary values are hex encoded. |

## Method List

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

|  |  |
| --- | --- |
| [Config](#mlkemconfig-method) | Sets or retrieves a configuration setting. |
| [CreateKey](#mlkemcreatekey-method) | Creates a new key. |
| [Decapsulate](#mlkemdecapsulate-method) | Decapsulates a shared secret. |
| [Encapsulate](#mlkemencapsulate-method) | Encapsulates a shared secret. |
| [Reset](#mlkemreset-method) | Resets the class. |

## 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.*

|  |  |
| --- | --- |
| [Error](#mlkemerror-event) | Fired when information is available about errors during data delivery. |

## Config Settings

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

|  |  |
| --- | --- |
| [ParamSet](#ParamSet) | The ML-KEM parameter set. |
| [BuildInfo](#BuildInfo) | Information about the product's build. |
| [CodePage](#CodePage) | The system code page used for Unicode to Multibyte translations. |
| [LicenseInfo](#LicenseInfo) | Information about the current license. |
| [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. |
| [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. |

# [MLKEM](#mlkem-class).CipherText Property

The cipher text.

## Syntax

```text
getCipherText(): Uint8Array;
setCipherText(cipherText: Uint8Array): void;
```

## Default Value

""

## Remarks

This property holds the ML-KEM ciphertext.

It is populated by [Encapsulate](#mlkemencapsulate-method) and must be set before calling [Decapsulate](#mlkemdecapsulate-method).

# [MLKEM](#mlkem-class).Key Property

The ML-KEM key.

## Syntax

```text
getKey(): MLKEMKey;
setKey(key: MLKEMKey): void;
```

## Default Value

## Remarks

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

The public key is required before calling [Encapsulate](#mlkemencapsulate-method), and the private key is required before calling [Decapsulate](#mlkemdecapsulate-method).

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

KeyPublicKey holds the public key.

KeyPrivateKey holds the private key.

 Please refer to the [MLKEMKey](#mlkemkey-type) type for a complete list of fields.

# [MLKEM](#mlkem-class).SharedSecret Property

The computed shared secret.

## Syntax

```text
getSharedSecret(): Uint8Array;
```

## Default Value

""

## Remarks

This property holds the shared secret computed by [Encapsulate](#mlkemencapsulate-method) or [Decapsulate](#mlkemdecapsulate-method).

This property is read-only.

# [MLKEM](#mlkem-class).UseHex Property

Whether binary values are hex encoded.

## Syntax

```text
isUseHex(): boolean;
setUseHex(useHex: boolean): void;
```

## Default Value

FALSE

## Remarks

This property specifies whether [CipherText](#mlkemciphertext-property) and [SharedSecret](#mlkemsharedsecret-property) are hex encoded when [Encapsulate](#mlkemencapsulate-method) is called.

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

When [Decapsulate](#mlkemdecapsulate-method) is called and this property is set to *True*, [CipherText](#mlkemciphertext-property) is treated as hex encoded and [SharedSecret](#mlkemsharedsecret-property) is hex encoded when populated.

# [MLKEM](#mlkem-class).config Method

Sets or retrieves a configuration setting.

## Syntax

```text
async mlkem.config(configurationString : string): Promise< string>
```

## Remarks

Config is a generic method available in every class. It is used to set and retrieve [configuration settings](#config-settings-class-ipworksencryptmlkem) 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](#config-settings-class-ipworksencryptmlkem), you must call *Config("PROPERTY")*. The value will be returned as a string.

# [MLKEM](#mlkem-class).createKey Method

Creates a new key.

## Syntax

```text
async mlkem.createKey(): Promise< void>
```

## Remarks

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

When this method is called, [Key](#mlkemkey-property) is populated with the generated raw public and private key values. The parameter set is controlled by the *ParamSet* configuration setting.

# [MLKEM](#mlkem-class).decapsulate Method

Decapsulates a shared secret.

## Syntax

```text
async mlkem.decapsulate(): Promise< void>
```

## Remarks

This method uses the private key in [Key](#mlkemkey-property) and the ciphertext in [CipherText](#mlkemciphertext-property) to recover the shared secret.

The shared secret is available from [SharedSecret](#mlkemsharedsecret-property).

# [MLKEM](#mlkem-class).encapsulate Method

Encapsulates a shared secret.

## Syntax

```text
async mlkem.encapsulate(): Promise< void>
```

## Remarks

This method uses the public key in [Key](#mlkemkey-property) to generate a shared secret and ciphertext.

The generated shared secret is available from [SharedSecret](#mlkemsharedsecret-property), and the ciphertext is available from [CipherText](#mlkemciphertext-property).

# [MLKEM](#mlkem-class).reset Method

Resets the class.

## Syntax

```text
async mlkem.reset(): Promise< void>
```

## Remarks

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

# [MLKEM](#mlkem-class).Error Event

Fired when information is available about errors during data delivery.

## Syntax

```text
mlkem.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )
```

## Remarks

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

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](#trappable-errors-class-ipworksencryptmlkem) section.

# MLKEMKey Type

Contains a raw ML-KEM key.

## Remarks

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

The following fields are available:

- [PrivateKey](#MLKEMKey_f_PrivateKey)

- [PublicKey](#MLKEMKey_f_PublicKey)

## Fields

 **PrivateKey** *string*
*Default Value: ""*

The raw ML-KEM private key.

 **PrivateKeyB** *Uint8Array*
*Default Value: ""*

The raw ML-KEM private key.

 **PublicKey** *string*
*Default Value: ""*

The raw ML-KEM public key.

 **PublicKeyB** *Uint8Array*
*Default Value: ""*

The raw ML-KEM public key.

## Constructors

```text
public MLKEMKey();
```

 The default constructor creates a new MLKEMKey instance but does not assign a public or private key.

```text
public MLKEMKey(byte[] publicKey);
```

 The public key constructor assigns an existing public key.

```text
public MLKEMKey(byte[] publicKey, byte[] privateKey);
```

 The private key constructor assigns an existing private key.

# Config Settings (*class *ipworksencrypt.[mlkem](#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](#mlkemconfig-method) method.

### MLKEM Config Settings

**ParamSet**: The ML-KEM parameter set.This setting specifies the ML-KEM parameter set to use when creating keys, encapsulating, and decapsulating. Possible values are:

- 512 (default)
- 768
- 1024

### Base Config Settings

**BuildInfo**: Information about the product's build.When queried, this setting will return a string containing information about the product's build.

**CodePage**: The system code page used for Unicode to Multibyte translations.The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:

|  |  |
| --- | --- |
| Identifier | Name |
| 037 | IBM EBCDIC - U.S./Canada |
| 437 | OEM - United States |
| 500 | IBM EBCDIC - International |
| 708 | Arabic - ASMO 708 |
| 709 | Arabic - ASMO 449+, BCON V4 |
| 710 | Arabic - Transparent Arabic |
| 720 | Arabic - Transparent ASMO |
| 737 | OEM - Greek (formerly 437G) |
| 775 | OEM - Baltic |
| 850 | OEM - Multilingual Latin I |
| 852 | OEM - Latin II |
| 855 | OEM - Cyrillic (primarily Russian) |
| 857 | OEM - Turkish |
| 858 | OEM - Multilingual Latin I + Euro symbol |
| 860 | OEM - Portuguese |
| 861 | OEM - Icelandic |
| 862 | OEM - Hebrew |
| 863 | OEM - Canadian-French |
| 864 | OEM - Arabic |
| 865 | OEM - Nordic |
| 866 | OEM - Russian |
| 869 | OEM - Modern Greek |
| 870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) |
| 874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) |
| 875 | IBM EBCDIC - Modern Greek |
| 932 | ANSI/OEM - Japanese, Shift-JIS |
| 936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) |
| 949 | ANSI/OEM - Korean (Unified Hangul Code) |
| 950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) |
| 1026 | IBM EBCDIC - Turkish (Latin-5) |
| 1047 | IBM EBCDIC - Latin 1/Open System |
| 1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) |
| 1141 | IBM EBCDIC - Germany (20273 + Euro symbol) |
| 1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) |
| 1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) |
| 1144 | IBM EBCDIC - Italy (20280 + Euro symbol) |
| 1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) |
| 1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) |
| 1147 | IBM EBCDIC - France (20297 + Euro symbol) |
| 1148 | IBM EBCDIC - International (500 + Euro symbol) |
| 1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) |
| 1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) |
| 1201 | Unicode UCS-2 Big-Endian |
| 1250 | ANSI - Central European |
| 1251 | ANSI - Cyrillic |
| 1252 | ANSI - Latin I |
| 1253 | ANSI - Greek |
| 1254 | ANSI - Turkish |
| 1255 | ANSI - Hebrew |
| 1256 | ANSI - Arabic |
| 1257 | ANSI - Baltic |
| 1258 | ANSI/OEM - Vietnamese |
| 1361 | Korean (Johab) |
| 10000 | MAC - Roman |
| 10001 | MAC - Japanese |
| 10002 | MAC - Traditional Chinese (Big5) |
| 10003 | MAC - Korean |
| 10004 | MAC - Arabic |
| 10005 | MAC - Hebrew |
| 10006 | MAC - Greek I |
| 10007 | MAC - Cyrillic |
| 10008 | MAC - Simplified Chinese (GB 2312) |
| 10010 | MAC - Romania |
| 10017 | MAC - Ukraine |
| 10021 | MAC - Thai |
| 10029 | MAC - Latin II |
| 10079 | MAC - Icelandic |
| 10081 | MAC - Turkish |
| 10082 | MAC - Croatia |
| 12000 | Unicode UCS-4 Little-Endian |
| 12001 | Unicode UCS-4 Big-Endian |
| 20000 | CNS - Taiwan |
| 20001 | TCA - Taiwan |
| 20002 | Eten - Taiwan |
| 20003 | IBM5550 - Taiwan |
| 20004 | TeleText - Taiwan |
| 20005 | Wang - Taiwan |
| 20105 | IA5 IRV International Alphabet No. 5 (7-bit) |
| 20106 | IA5 German (7-bit) |
| 20107 | IA5 Swedish (7-bit) |
| 20108 | IA5 Norwegian (7-bit) |
| 20127 | US-ASCII (7-bit) |
| 20261 | T.61 |
| 20269 | ISO 6937 Non-Spacing Accent |
| 20273 | IBM EBCDIC - Germany |
| 20277 | IBM EBCDIC - Denmark/Norway |
| 20278 | IBM EBCDIC - Finland/Sweden |
| 20280 | IBM EBCDIC - Italy |
| 20284 | IBM EBCDIC - Latin America/Spain |
| 20285 | IBM EBCDIC - United Kingdom |
| 20290 | IBM EBCDIC - Japanese Katakana Extended |
| 20297 | IBM EBCDIC - France |
| 20420 | IBM EBCDIC - Arabic |
| 20423 | IBM EBCDIC - Greek |
| 20424 | IBM EBCDIC - Hebrew |
| 20833 | IBM EBCDIC - Korean Extended |
| 20838 | IBM EBCDIC - Thai |
| 20866 | Russian - KOI8-R |
| 20871 | IBM EBCDIC - Icelandic |
| 20880 | IBM EBCDIC - Cyrillic (Russian) |
| 20905 | IBM EBCDIC - Turkish |
| 20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) |
| 20932 | JIS X 0208-1990 & 0121-1990 |
| 20936 | Simplified Chinese (GB2312) |
| 21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) |
| 21027 | Extended Alpha Lowercase |
| 21866 | Ukrainian (KOI8-U) |
| 28591 | ISO 8859-1 Latin I |
| 28592 | ISO 8859-2 Central Europe |
| 28593 | ISO 8859-3 Latin 3 |
| 28594 | ISO 8859-4 Baltic |
| 28595 | ISO 8859-5 Cyrillic |
| 28596 | ISO 8859-6 Arabic |
| 28597 | ISO 8859-7 Greek |
| 28598 | ISO 8859-8 Hebrew |
| 28599 | ISO 8859-9 Latin 5 |
| 28605 | ISO 8859-15 Latin 9 |
| 29001 | Europa 3 |
| 38598 | ISO 8859-8 Hebrew |
| 50220 | ISO 2022 Japanese with no halfwidth Katakana |
| 50221 | ISO 2022 Japanese with halfwidth Katakana |
| 50222 | ISO 2022 Japanese JIS X 0201-1989 |
| 50225 | ISO 2022 Korean |
| 50227 | ISO 2022 Simplified Chinese |
| 50229 | ISO 2022 Traditional Chinese |
| 50930 | Japanese (Katakana) Extended |
| 50931 | US/Canada and Japanese |
| 50933 | Korean Extended and Korean |
| 50935 | Simplified Chinese Extended and Simplified Chinese |
| 50936 | Simplified Chinese |
| 50937 | US/Canada and Traditional Chinese |
| 50939 | Japanese (Latin) Extended and Japanese |
| 51932 | EUC - Japanese |
| 51936 | EUC - Simplified Chinese |
| 51949 | EUC - Korean |
| 51950 | EUC - Traditional Chinese |
| 52936 | HZ-GB2312 Simplified Chinese |
| 54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) |
| 57002 | ISCII Devanagari |
| 57003 | ISCII Bengali |
| 57004 | ISCII Tamil |
| 57005 | ISCII Telugu |
| 57006 | ISCII Assamese |
| 57007 | ISCII Oriya |
| 57008 | ISCII Kannada |
| 57009 | ISCII Malayalam |
| 57010 | ISCII Gujarati |
| 57011 | ISCII Punjabi |
| 65000 | Unicode UTF-7 |
| 65001 | Unicode UTF-8 |

 The following is a list of valid code page identifiers for Mac OS only:

|  |  |
| --- | --- |
| Identifier | Name |
| 1 | ASCII |
| 2 | NEXTSTEP |
| 3 | JapaneseEUC |
| 4 | UTF8 |
| 5 | ISOLatin1 |
| 6 | Symbol |
| 7 | NonLossyASCII |
| 8 | ShiftJIS |
| 9 | ISOLatin2 |
| 10 | Unicode |
| 11 | WindowsCP1251 |
| 12 | WindowsCP1252 |
| 13 | WindowsCP1253 |
| 14 | WindowsCP1254 |
| 15 | WindowsCP1250 |
| 21 | ISO2022JP |
| 30 | MacOSRoman |
| 10 | UTF16String |
| 0x90000100 | UTF16BigEndian |
| 0x94000100 | UTF16LittleEndian |
| 0x8c000100 | UTF32String |
| 0x98000100 | UTF32BigEndian |
| 0x9c000100 | UTF32LittleEndian |
| 65536 | Proprietary |

**LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.

**MaskSensitiveData**: Whether sensitive data is masked in log messages.In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to *true* to mask sensitive data. The default is *true*.

**UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to *true* tells the class to use the internal implementation instead of using the system security libraries.

 This setting is set to *false* by default on all platforms.

# Trappable Errors (*class *ipworksencrypt.[mlkem](#mlkem-class))

### MLKEM Errors

|  |  |
| --- | --- |
| 102 | No Key specified. |
| 120 | Invalid parameter set. |
| 1401 | Specified ML-KEM key is invalid. |
| 1402 | Invalid parameter set. |
| 1403 | Public key must be specified. |
| 1404 | Private key must be specified. |
| 1405 | CipherText must be specified. |
| 1406 | Decapsulation failed. |