BCRYPT_MLKEM_KEY_BLOB structure

The BCRYPT_MLKEM_KEY_BLOB structure is used as a header for an ML-KEM public key (byte-encoded encapsulation key) or private key BLOB in memory.

Syntax

typedef struct _BCRYPT_MLKEM_KEY_BLOB {
  ULONG dwMagic;
  ULONG cbParameterSet;             // Byte size of parameterSet[]
  ULONG cbKey;                      // Byte size of key[]
  // WCHAR parameterSet[cbParameterSet / sizeof(WCHAR)];  // Including \0-terminated
  // BYTE key[cbKey];                                     // Key material
} BCRYPT_MLKEM_KEY_BLOB, *PBCRYPT_MLKEM_KEY_BLOB;

typedef struct _BCRYPT_COMPOSITE_MLKEM_KEY_BLOB {
  ULONG dwMagic;
  ULONG cbParameterSet;             // Byte size of parameterSet[]
  ULONG cbKey;                      // Byte size of key[]
  // WCHAR parameterSet[cbParameterSet / sizeof(WCHAR)];  // Including \0-terminated
  // BYTE key[cbKey];                                     // Key material
} BCRYPT_COMPOSITE_MLKEM_KEY_BLOB, *PBCRYPT_COMPOSITE_MLKEM_KEY_BLOB;

Fields

dwMagic

The dwMagic field is a 4-byte value that indicates the format of the key being used. The following values are defined:

cbParameterSet

The length, in bytes, of the buffer parameterSet directly following the struct. This buffer contains a null-terminated Unicode string that identifies the parameter set of the key. The following values are currently supported:

cbKey

The length, in bytes, of the buffer key directly following parameterSet. This size is static and depends on the key format and parameter set in use.

Remarks

BCRYPT_MLKEM_PRIVATE_BLOB (also aliased as BCRYPT_MLKEM_DECAPSULATION_BLOB) supports import and export of standard byte-encoded ML-KEM decapsulation keys per FIPS 203. The blob has dwMagic value BCRYPT_MLKEM_PRIVATE_MAGIC and the key field contains the byte-encoded key.

BCRYPT_MLKEM_PUBLIC_BLOB (also aliased as BCRYPT_MLKEM_ENCAPSULATION_BLOB) supports import and export of standard byte-encoded ML-KEM encapsulation keys per FIPS 203. The blob has dwMagic value BCRYPT_MLKEM_PUBLIC_MAGIC and the key field contains the byte-encoded key.

BCRYPT_MLKEM_PRIVATE_SEED_BLOB supports import and export of ML-KEM seeds. The blob has dwMagic value BCRYPT_MLKEM_PRIVATE_SEED_MAGIC and the key field contains the KEM seed (defined as the 64-byte concatenation of d || z per FIPS 203), so cbKey is currently always 64.

The byte sizes of the byte-encoded keys can be found in FIPS 203 Section 8 Table 3. Many callers can instead dynamically query the required blob sizes using BCryptExportKey with NULL pbOutput.

BCRYPT_COMPOSITE_MLKEM_PRIVATE_BLOB supports import and export of standard byte-encoded Composite-ML-KEM private keys per PQ Composite ML-KEM. The blob has dwMagic value BCRYPT_COMPOSITE_MLKEM_PRIVATE_MAGIC and the key field contains the byte-encoded key.

BCRYPT_COMPOSITE_MLKEM_PUBLIC_BLOB supports import and export of standard byte-encoded Composite-ML-KEM public keys per PQ Composite ML-KEM. The blob has dwMagic value BCRYPT_COMPOSITE_MLKEM_PUBLIC_MAGIC and the key field contains the byte-encoded key.

BCRYPT_COMPOSITE_MLKEM_PRIVATE_IRTF_SEED_BLOB supports import and export of Composite-ML-KEM seeds. The blob has dwMagic value BCRYPT_COMPOSITE_MLKEM_PRIVATE_IRTF_SEED_MAGIC and the key field contains the 32-byte IRTF Composite-ML-KEM seed per CFRG Concrete Hybrid KEMs, so cbKey is currently always 32.

Requirements

See also

BCryptGenerateKeyPair

BCryptImportKeyPair

BCryptFinalizeKeyPair

BCryptExportKey

BCryptGetProperty

BCryptSetProperty

BCryptEncapsulate

BCryptDecapsulate