Skip to content

Commit 8fe437c

Browse files
jess-krynitskyjess-krynitsky
authored
Update SDK API docs with changes for ML-DSA and ML-KEM in Bcrypt (#2216)
* Add BCryptEncapsulate function documentation BCryptEncapsulate function was added October 2025 along with post-quantum cryptography algorithm ML-KEM. This was documented in win32 apps - https://learn.microsoft.com/en-us/windows/win32/seccng/bcrypt/nf-bcrypt-bcryptencapsulate - but was missing from the SDK documentation. * Create nf-bcrypt-bcryptdecapsulate.md adding decapsulate function for ML-KEM based on Win32 apps docs * add API documentation for PQ DSA and MLKEM key blobs copied over from win32 apps documentation. Needs ms asset IDs and style review. * add PQDSA padding info structure Missing SDK doc copied from win32 content for PQ DSA padding info. * Fixed links changed links to point to sdk-api docs rather than win32 * Update nf-bcrypt-bcryptdecapsulate.md fixed min version support * formatting fixes and composite updates Added composite key blob values removed original_content_git_url Fixed headings referencing Win32 APIs added final newline to the end of pages Fixed some small formatting issues Fixed note syntax * remove prerelease note removing prerelease note from encapsulate and decapsulate functions as these are fully released.
1 parent c3dcfa6 commit 8fe437c

5 files changed

Lines changed: 621 additions & 0 deletions

‎sdk-api-src/content/bcrypt/nf-bcrypt-bcryptdecapsulate.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
UID: NF:bcrypt.BCryptDecapsulate
3+
title: BCryptDecapsulate function (bcrypt.h)
4+
description: Performs the Decapsulation operation of a KEM algorithm, decrypting a ciphertext and returning the shared secret key.
5+
helpviewer_keywords: ["BCryptDecapsulate","BCryptDecapsulate function [Security]","bcrypt/BCryptDecapsulate","security.bcryptdecapsulate", "BCrypt KEM"]
6+
old-location: security\bcryptdecapsulate.htm
7+
tech.root: security
8+
ms.assetid:
9+
ms.date: 5/22/2025
10+
ms.keywords: BCryptDecapsulate, BCryptDecapsulate function [Security], bcrypt/BCryptDecapsulate, security.bcryptdecapsulate, BCrypt KEM
11+
req.header: bcrypt.h
12+
req.include-header:
13+
req.target-type: Windows
14+
req.target-min-winverclnt: Windows 11 24H2
15+
req.target-min-winversvr: Windows Server 2025
16+
req.kmdf-ver:
17+
req.umdf-ver:
18+
req.ddi-compliance:
19+
req.unicode-ansi:
20+
req.idl:
21+
req.max-support:
22+
req.namespace:
23+
req.assembly:
24+
req.type-library:
25+
req.lib: Bcrypt.lib
26+
req.dll: Bcrypt.dll
27+
req.irql:
28+
targetos: Windows
29+
req.typenames:
30+
req.redist:
31+
ms.custom: 24H2
32+
f1_keywords:
33+
- BCryptDecapsulate
34+
- bcrypt/BCryptDecapsulate
35+
dev_langs:
36+
- c++
37+
topic_type:
38+
- APIRef
39+
- kbSyntax
40+
api_type:
41+
- DllExport
42+
api_location:
43+
- Bcrypt.dll
44+
api_name:
45+
- BCryptDecapsulate
46+
---
47+
48+
# BCryptDecapsulate function
49+
50+
The **BCryptDecapsulate** function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM).
51+
It takes a KEM ciphertext and it decrypts with the provided private key, returning the shared secret key.
52+
53+
If the ciphertext is correctly formatted but does not match the decapsulation key, this API will succeed but a random shared secret key will be generated.
54+
55+
## Syntax
56+
57+
```cpp
58+
NTSTATUS BCryptDecapsulate(
59+
_In_ BCRYPT_KEY_HANDLE hKey,
60+
_In_reads_bytes_(cbCipherText)
61+
PUCHAR pbCipherText,
62+
_In_ ULONG cbCipherText,
63+
_Out_writes_bytes_to_opt_(cbSecretKey, *pcbSecretKey)
64+
PUCHAR pbSecretKey,
65+
_In_ ULONG cbSecretKey,
66+
_Out_ ULONG *pcbSecretKey,
67+
_In_ ULONG dwFlags
68+
);
69+
```
70+
71+
## Parameters
72+
73+
*hKey* `[in]`
74+
75+
The handle of the key to use to decapsulate the KEM ciphertext. This must be the private (decapsulation) key which corresponds to the public (encapsulation) key used to produce the KEM ciphertext. The key handle is obtained from one of the keypair creation functions, such as [BCryptGenerateKeyPair](/windows/desktop/api/Bcrypt/nf-bcrypt-bcryptgeneratekeypair) or [BCryptImportKeyPair](/windows/desktop/api/Bcrypt/nf-bcrypt-bcryptimportkeypair).
76+
77+
*pbCipherText* `[in]`
78+
79+
A pointer to a buffer that contains the KEM ciphertext. The [BCryptEncapsulate](nf-bcrypt-bcryptencapsulate.md) function may be used to create a KEM ciphertext.
80+
81+
*cbCipherText* `[in]`
82+
83+
The size, in bytes, of the *pbCipherText* buffer.
84+
85+
*pbSecretKey* `[out]`
86+
87+
A pointer to a buffer that receives the shared secret key. See [remarks](#remarks) for more information.
88+
89+
*cbSecretKey* `[in]`
90+
91+
The size, in bytes, of the *pbSecretKey* buffer.
92+
93+
*pcbSecretKey* `[out]`
94+
95+
A pointer to a **ULONG** variable that the receives the number of bytes written to *pbSecretKey* buffer.
96+
97+
If *pbSecretKey* is `NULL`, this receives the size, in bytes, required for the shared secret key.
98+
See [remarks](#remarks) for more information.
99+
100+
*dwFlags* `[in]`
101+
102+
Reserved, must be zero.
103+
104+
## Return value
105+
106+
Returns a status code that indicates the success or failure of the function.
107+
108+
Possible return codes include, but are not limited to, the following.
109+
110+
| Return Code | Description |
111+
|--|--|
112+
| `STATUS_SUCCESS` | The function was successful. |
113+
| `STATUS_INVALID_PARAMETER` | One or more required parameters (*hKey*, *pcbSecretKey*, *pbCipherText*) is `NULL`, or one of the parameters has an invalid value. |
114+
| `STATUS_INVALID_BUFFER_SIZE` | A buffer size (*cbSecretKey*, *cbCipherText*) does not match the expected size for the KEM parameters associated with the decapsulation key. |
115+
| `STATUS_BUFFER_TOO_SMALL` | An output buffer size (*cbSecretKey*) is too small for the result decapsulation operation for the KEM parameters associated with the decapsulation key. *pcbSecretKey* receives the number of bytes required for *pbSecretKey*. |
116+
117+
## Remarks
118+
119+
To query the required size of the *pbSecretKey* buffer needed for the KEM shared secret key, call **BCryptDecapsulate** with a `NULL` *pbSecretKey*. The required size will be returned in *pcbSecretKey*. This query is efficient and returns the size without performing the decapsulation.
120+
Equivalently, use [BCryptGetProperty](/windows/desktop/api/Bcrypt/nf-bcrypt-bcryptgetproperty) to query the **BCRYPT_KEM_SHARED_SECRET_LENGTH** property of the algorithm or key handle.
121+
For currently supported KEM algorithms (ML-KEM), the shared secret length is a constant size for a given algorithm.
122+
123+
### Additional remarks
124+
125+
Given an invalid, but correctly-sized, ciphertext, the ML-KEM decapsulation operation will *implicitly reject* the ciphertext by returning success in equal time to a valid decapsulation operation, with pseudo-random shared secret key output. This forces higher-level protocols to fail later when symmetric keys of peers don't match. So, decapsulate will only ever fail if there are programming errors (i.e. incorrect size, use of uninitialized *hKey*), or something fundamentally goes wrong with the environment (i.e. internal memory allocation fails, or and internal consistency test detects hardware error).
126+
127+
## Requirements
128+
129+
| Requirement | Value |
130+
| ---- | ---- |
131+
| **Minimum supported client** | **Windows 11 24H2:** Support for ML-KEM begins. [desktop apps only] |
132+
| **Minimum supported server** | **Windows Server 2025:** Support for ML-KEM begins. [desktop apps only] |
133+
| **Library** | `Bcrypt.lib` |
134+
| **DLL** | `Bcrypt.dll` |

‎sdk-api-src/content/bcrypt/nf-bcrypt-bcryptencapsulate.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
UID: NF:bcrypt.BCryptEncapsulate
3+
title: BCryptEncapsulate function (bcrypt.h)
4+
description: Uses a key encapsulation mechanism (KEM) to generate a shared secret key and encrypt it to produce a KEM ciphertext.
5+
helpviewer_keywords: ["BCryptEncapsulate","BCryptEncapsulate function [Security]","bcrypt/BCryptEncapsulate","security.bcryptencapsulate", "BCrypt KEM"]
6+
old-location: security\bcryptencapsulate.htm
7+
tech.root: security
8+
ms.assetid:
9+
ms.date: 5/22/2025
10+
ms.keywords: BCryptEncapsulate, BCryptEncapsulate function [Security], bcrypt/BCryptEncapsulate, security.bcryptencapsulate, BCrypt KEM
11+
req.header: bcrypt.h
12+
req.include-header:
13+
req.target-type: Windows
14+
req.target-min-winverclnt: Windows 11 24H2
15+
req.target-min-winversvr: Windows Server 2025
16+
req.kmdf-ver:
17+
req.umdf-ver:
18+
req.ddi-compliance:
19+
req.unicode-ansi:
20+
req.idl:
21+
req.max-support:
22+
req.namespace:
23+
req.assembly:
24+
req.type-library:
25+
req.lib: Bcrypt.lib
26+
req.dll: Bcrypt.dll
27+
req.irql:
28+
targetos: Windows
29+
req.typenames:
30+
req.redist:
31+
ms.custom: 24H2
32+
f1_keywords:
33+
- BCryptEncapsulate
34+
- bcrypt/BCryptEncapsulate
35+
dev_langs:
36+
- c++
37+
topic_type:
38+
- APIRef
39+
- kbSyntax
40+
api_type:
41+
- DllExport
42+
api_location:
43+
- Bcrypt.dll
44+
api_name:
45+
- BCryptEncapsulate
46+
---
47+
48+
# BCryptEncapsulate function
49+
50+
The **BCryptEncapsulate** function performs the Encapsulation operation of a Key Encapsulation Mechanism (KEM). It generates a shared secret key and encrypts it with the provided public key to produce a KEM ciphertext, returning both the shared secret key and the KEM ciphertext.
51+
52+
## Syntax
53+
54+
```cpp
55+
NTSTATUS BCryptEncapsulate(
56+
_In_ BCRYPT_KEY_HANDLE hKey,
57+
_Out_writes_bytes_to_opt_(cbSecretKey ,*pcbSecretKey)
58+
PUCHAR pbSecretKey,
59+
_In_ ULONG cbSecretKey,
60+
_Out_ ULONG *pcbSecretKey,
61+
_Out_writes_bytes_to_opt_(cbCipherText ,*pcbCipherText)
62+
PUCHAR pbCipherText,
63+
_In_ ULONG cbCipherText,
64+
_Out_ ULONG *pcbCipherText,
65+
_In_ ULONG dwFlags
66+
);
67+
```
68+
69+
## Parameters
70+
71+
*hKey*`[in]`
72+
73+
The handle of the key to use for the encapsulation operation. This key must contain a public (encapsulation) key, and the handle would typically be obtained by using [BCryptImportKeyPair](/en-us/windows/desktop/api/Bcrypt/nf-bcrypt-bcryptimportkeypair) with a [public key](/en-us/windows/desktop/SecGloss/p-gly) BLOB for the KEM algorithm. It is also possible to use a private key handle for the encapsulation operation, as KEM private key handles represent a key pair.
74+
75+
*pbSecretKey*`[out]`
76+
77+
A pointer to a buffer that receives the shared secret key. See remarks for more information.
78+
79+
*cbSecretKey*`[in]`
80+
81+
The size, in bytes, of the *pbSecretKey* buffer.
82+
83+
*pcbSecretKey*`[out]`
84+
85+
A pointer to a **ULONG** variable that the receives the number of bytes written to *pbSecretKey* buffer.
86+
87+
If *pbSecretKey* is `NULL`, this receives the size, in bytes, required for the shared secret key. See remarks for more information.
88+
89+
*pbCipherText*`[out]`
90+
91+
A pointer to a buffer that receives the KEM ciphertext. See remarks for more information.
92+
93+
*cbCipherText*`[in]`
94+
95+
The size, in bytes, of the *pbCipherText* buffer.
96+
97+
*pcbCipherText*`[out]`
98+
99+
A pointer to a **ULONG** variable that the receives the number of bytes written to *pbCipherText* buffer.
100+
101+
If *pbCipherText* is `NULL`, this receives the size, in bytes, required for the KEM ciphertext. See remarks for more information.
102+
103+
*dwFlags*`[in]`
104+
105+
Reserved, must be zero.
106+
107+
## Return value
108+
109+
Returns a status code that indicates the success or failure of the function.
110+
111+
Possible return codes include, but are not limited to, the following.
112+
113+
| Return Code | Description |
114+
| --- | --- |
115+
| `STATUS_SUCCESS` | The function was successful. |
116+
| `STATUS_INVALID_PARAMETER` | One or more required parameters (*hKey*, *pcbSecretKey*, *pcbCipherText*) is `NULL`, or one of the parameters has an invalid value. |
117+
| `STATUS_INVALID_BUFFER_SIZE` | A buffer size (*cbSecretKey*, *cbCipherText*) does not match the expected size for the KEM parameters associated with the encapsulation key. *pcbSecretKey* receives the number of bytes required for *pbSecretKey*, *pcbCipherText* receives the number of bytes required for *pbCipherText*. |
118+
| `STATUS_BUFFER_TOO_SMALL` | An output buffer size (*cbSecretKey*, *cbCipherText*) is too small for the result encapsulation operation for the KEM parameters associated with the encapsulation key. *pcbSecretKey* receives the number of bytes required for *pbSecretKey*, *pcbCipherText* receives the number of bytes required for *pbCipherText*. |
119+
120+
## Remarks
121+
122+
To query the required sizes of the *pbSecretKey* and *pbCipherText* buffers, callers may call **BCryptEncapsulate** with `NULL`*pbSecretKey* and *pbCipherText*. The required sizes will be returned in *pcbSecretKey* and *pcbCipherText*, respectively. This query is efficient and returns the size without performing the encapsulation. Equivalently, use [BCryptGetProperty](/en-us/windows/desktop/api/Bcrypt/nf-bcrypt-bcryptgetproperty) to query the **BCRYPT_KEM_SHARED_SECRET_LENGTH** property of the algorithm or key handle, and the **BCRYPT_KEM_CIPHERTEXT_LENGTH** property of the key handle. For currently supported KEM algorithms (ML-KEM), the shared secret length is a constant size for a given algorithm and the KEM ciphertext length is a constant size for a given parameter set.
123+
124+
## Requirements
125+
126+
| Requirement | Value |
127+
| --- | --- |
128+
| **Minimum supported client** | **Windows 11 24H2:** Support for ML-KEM begins. [desktop apps only] |
129+
| **Minimum supported server** | **Windows Server 2025:** Support for ML-KEM begins. [desktop apps only] |
130+
| **Library** | `Bcrypt.lib` |
131+
| **DLL** | `Bcrypt.dll` |

0 commit comments

Comments
 (0)