MLKEM Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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

Method List

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

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.

Config Settings

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

CipherText Property (MLKEM Component)

The cipher text.

Syntax

• C#
• VB.NET

public string CipherText { get; set; }
public byte[] CipherTextB { get; set; }

Public Property CipherText As String
Public Property CipherTextB As Byte()

Default Value

""

Remarks

This property holds the ML-KEM ciphertext.

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

Key Property (MLKEM Component)

The ML-KEM key.

Syntax

• C#
• VB.NET

public MLKEMKey Key { get; set; }

Public Property Key As MLKEMKey

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.

SharedSecret Property (MLKEM Component)

The computed shared secret.

Syntax

• C#
• VB.NET

public string SharedSecret { get; }
public byte[] SharedSecretB { get; }

Public ReadOnly Property SharedSecret As String
Public ReadOnly Property SharedSecretB As Byte()

Default Value

""

Remarks

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

This property is read-only.

UseHex Property (MLKEM Component)

Whether binary values are hex encoded.

Syntax

• C#
• VB.NET

public bool UseHex { get; set; }

Public Property UseHex As Boolean

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.

Config Method (MLKEM Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 (MLKEM Component)

Creates a new key.

Syntax

• C#
• VB.NET

public void CreateKey();

Async Version
public async Task CreateKey();
public async Task CreateKey(CancellationToken cancellationToken);

Public Sub CreateKey()

Async Version
Public Sub CreateKey() As Task
Public Sub CreateKey(cancellationToken As CancellationToken) As Task

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 Component)

Decapsulates a shared secret.

Syntax

• C#
• VB.NET

public void Decapsulate();

Async Version
public async Task Decapsulate();
public async Task Decapsulate(CancellationToken cancellationToken);

Public Sub Decapsulate()

Async Version
Public Sub Decapsulate() As Task
Public Sub Decapsulate(cancellationToken As CancellationToken) As Task

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

Encapsulates a shared secret.

Syntax

• C#
• VB.NET

public void Encapsulate();

Async Version
public async Task Encapsulate();
public async Task Encapsulate(CancellationToken cancellationToken);

Public Sub Encapsulate()

Async Version
Public Sub Encapsulate() As Task
Public Sub Encapsulate(cancellationToken As CancellationToken) As Task

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

Resets the component.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

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

Error Event (MLKEM Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, MLKEMErrorEventArgs e);

public class MLKEMErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As MLKEMErrorEventArgs)

Public Class MLKEMErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

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.

Remarks

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

• PrivateKey
• PublicKey

Fields

Constructors

• C#
• VB.NET

public MLKEMKey();

Public MLKEMKey()

• C#
• VB.NET

public MLKEMKey(byte[] publicKey);

Public MLKEMKey(ByVal PublicKey As Byte())

• C#
• VB.NET

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

Public MLKEMKey(ByVal PublicKey As Byte(), ByVal PrivateKey As Byte())

Config Settings (MLKEM Component)

MLKEM Config Settings

Base Config Settings

Trappable Errors (MLKEM Component)

MLKEM Errors