Class HandShakeHelper

Namespace

SecureExchangesSDK.Helpers

Assembly

SecureExchangesSDK.NetCore.dll

Establishes the post-quantum handshake between a client and the Secure Exchanges server.

The handshake uses ML-KEM-1024 (FIPS 203) for the key exchange and ML-DSA-87 (FIPS 204) to authenticate the server's ephemeral public key (certificate pinning). The derived AES-256 key protects the metadata channel (API arguments and responses) with AES-256-GCM. It mirrors the reference JavaScript client (MLKemHelper.js) and the server (SecureExchangesCore HandShakeHelper).

The metadata channel is distinct from the file/body content key (FilesAndBodyKey / FilesAndBodyIV) which is generated locally and never shared with the server.

public static class HandShakeHelper

Inheritance

object

HandShakeHelper

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

DecryptBinaryFromBytes(HandShake, byte[])

Decrypts metadata ciphertext bytes to bytes.

public static byte[] DecryptBinaryFromBytes(HandShake hand, byte[] cipher)

Parameters

hand HandShake

cipher byte[]

Returns

byte[]

DecryptStringFromBase64(HandShake, string)

Decrypts base64 metadata ciphertext to a string.

public static string DecryptStringFromBase64(HandShake hand, string b64)

Parameters

hand HandShake

b64 string

Returns

string

DecryptStringFromBytes(HandShake, byte[])

Decrypts metadata ciphertext bytes to a string.

public static string DecryptStringFromBytes(HandShake hand, byte[] cipher)

Parameters

hand HandShake

cipher byte[]

Returns

string

EncryptBinary(HandShake, byte[])

Encrypts binary metadata. Returns the AES-256-GCM bytes (nonce-prefixed).

public static byte[] EncryptBinary(HandShake hand, byte[] binary)

Parameters

hand HandShake

binary byte[]

Returns

byte[]

EncryptBinaryToB64(HandShake, byte[])

Encrypts binary metadata and returns it base64 encoded.

public static string EncryptBinaryToB64(HandShake hand, byte[] binary)

Parameters

hand HandShake

binary byte[]

Returns

string

EncryptStringToB64(HandShake, string)

Encrypts a metadata string and returns it base64 encoded (format: [nonce 12][ciphertext + tag]).

public static string EncryptStringToB64(HandShake hand, string plainText)

Parameters

hand HandShake

plainText string

Returns

string

EncryptStringToBytes(HandShake, string)

Encrypts a metadata string and returns the AES-256-GCM bytes (nonce-prefixed).

public static byte[] EncryptStringToBytes(HandShake hand, string plainText)

Parameters

hand HandShake

plainText string

Returns

byte[]

GenerateHandShakeKey(IEndPointConfiguration)

Create a HandShake (post-quantum ML-KEM-1024 + ML-DSA-87). Synchronous wrapper.

[Obsolete("Use GenerateHandShakeKeyAsync instead. Synchronous calls can cause deadlocks.")]
public static HandShake GenerateHandShakeKey(IEndPointConfiguration endPointConfig)

Parameters

endPointConfig IEndPointConfiguration

Returns

HandShake

GenerateHandShakeKeyAsync(IEndPointConfiguration)

Generate a post-quantum handshake asynchronously using ML-KEM-1024 + ML-DSA-87.

public static Task<HandShake> GenerateHandShakeKeyAsync(IEndPointConfiguration endPointConfig)

Parameters

endPointConfig IEndPointConfiguration

The endpoint configuration (used to resolve the server domain)

Returns

Task<HandShake>

A secure HandShake whose Key is the derived AES-256 key