# MLKEM Component

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

## Syntax

```text
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 component with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [CipherText](#ciphertext-property-mlkem-component) | The cipher text. |
| [KeyPrivateKey](#keyprivatekey-property-mlkem-component) | The raw ML-KEM private key. |
| [KeyPublicKey](#keypublickey-property-mlkem-component) | The raw ML-KEM public key. |
| [SharedSecret](#sharedsecret-property-mlkem-component) | The computed shared secret. |
| [UseHex](#usehex-property-mlkem-component) | Whether binary values are hex encoded. |

## Method List

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

|  |  |
| --- | --- |
| [Config](#config-method-mlkem-component) | Sets or retrieves a configuration setting. |
| [CreateKey](#createkey-method-mlkem-component) | Creates a new key. |
| [Decapsulate](#decapsulate-method-mlkem-component) | Decapsulates a shared secret. |
| [Encapsulate](#encapsulate-method-mlkem-component) | Encapsulates a shared secret. |
| [Reset](#reset-method-mlkem-component) | Resets the class. |

## Event List

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

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

## Config Settings

*The following is a list of config settings for the component 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. |

# CipherText Property ([MLKEM](#mlkem-component) Component)

The cipher text.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) CipherText() ([]byte, error)func (obj *MLKEM) SetCipherText(value []byte) error
```

## Default Value

""

## Remarks

This property holds the ML-KEM ciphertext.

It is populated by [Encapsulate](#encapsulate-method-mlkem-component) and must be set before calling [Decapsulate](#decapsulate-method-mlkem-component).

## Data Type

**[]byte**

# KeyPrivateKey Property ([MLKEM](#mlkem-component) Component)

The raw ML-KEM private key.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) KeyPrivateKey() ([]byte, error)func (obj *MLKEM) SetKeyPrivateKey(value []byte) error
```

## Default Value

""

## Remarks

The raw ML-KEM private key.

## Data Type

**[]byte**

# KeyPublicKey Property ([MLKEM](#mlkem-component) Component)

The raw ML-KEM public key.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) KeyPublicKey() ([]byte, error)func (obj *MLKEM) SetKeyPublicKey(value []byte) error
```

## Default Value

""

## Remarks

The raw ML-KEM public key.

## Data Type

**[]byte**

# SharedSecret Property ([MLKEM](#mlkem-component) Component)

The computed shared secret.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) SharedSecret() ([]byte, error)
```

## Default Value

""

## Remarks

This property holds the shared secret computed by [Encapsulate](#encapsulate-method-mlkem-component) or [Decapsulate](#decapsulate-method-mlkem-component).

This property is read-only.

## Data Type

**[]byte**

# UseHex Property ([MLKEM](#mlkem-component) Component)

Whether binary values are hex encoded.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) UseHex() (bool, error)func (obj *MLKEM) SetUseHex(value bool) error
```

## Default Value

false

## Remarks

This property specifies whether [CipherText](#ciphertext-property-mlkem-component) and [SharedSecret](#sharedsecret-property-mlkem-component) are hex encoded when [Encapsulate](#encapsulate-method-mlkem-component) is called.

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

When [Decapsulate](#decapsulate-method-mlkem-component) is called and this property is set to *True*, [CipherText](#ciphertext-property-mlkem-component) is treated as hex encoded and [SharedSecret](#sharedsecret-property-mlkem-component) is hex encoded when populated.

## Data Type

**bool**

# Config Method ([MLKEM](#mlkem-component) Component)

Sets or retrieves a configuration setting.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) Config(ConfigurationString string) (string, error)
```

## Remarks

Config is a generic method available in every struct. It is used to set and retrieve [configuration settings](#config-settings-mlkem-component) for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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-mlkem-component), you must call *Config("PROPERTY")*. The value will be returned as a string.

# CreateKey Method ([MLKEM](#mlkem-component) Component)

Creates a new key.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) CreateKey() error
```

## 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 ([MLKEM](#mlkem-component) Component)

Decapsulates a shared secret.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) Decapsulate() error
```

## Remarks

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

The shared secret is available from [SharedSecret](#sharedsecret-property-mlkem-component).

# Encapsulate Method ([MLKEM](#mlkem-component) Component)

Encapsulates a shared secret.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) Encapsulate() error
```

## Remarks

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

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

# Reset Method ([MLKEM](#mlkem-component) Component)

Resets the class.

## Syntax

*Go Syntax*

```text
func (obj *MLKEM) Reset() error
```

## Remarks

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

# Error Event ([MLKEM](#mlkem-component) Component)

Fired when information is available about errors during data delivery.

## Syntax

*Go Syntax*

```text
// MLKEMErrorEventArgs carries the MLKEM Error event's parameters.
type MLKEMErrorEventArgs struct {...}

func (args *MLKEMErrorEventArgs) ErrorCode() int32
func (args *MLKEMErrorEventArgs) Description() string
// MLKEMErrorEvent defines the signature of the MLKEM Error event's handler function.
type MLKEMErrorEvent func(sender *MLKEM, args *MLKEMErrorEventArgs)

func (obj *MLKEM) GetOnErrorHandler() MLKEMErrorEvent
func (obj *MLKEM) SetOnErrorHandler(handlerFunc MLKEMErrorEvent)
```

## Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the struct 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](#trappable-errors-mlkem-component) section.

# Config Settings ([MLKEM](#mlkem-component) Component)

 The struct 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 struct, access to these *internal properties* is provided through the [Config](#config-method-mlkem-component) 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 struct 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 struct will use the system security libraries by default to perform cryptographic functions where applicable.

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

 On Windows, this setting is set to *false* by default. On Linux/macOS, this setting is set to *true* by default.

 To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the [OpenSSL Notes](platforms.md) section.

# Trappable Errors ([MLKEM](#mlkem-component) Component)

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