Note
某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。 本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). 它采用 KEM 密码文本，并使用提供的私钥进行解密，并返回共享密钥。
如果密码文本格式正确，但与解封密钥不匹配，则此 API 将成功，但将生成随机共享密钥。
Syntax
NTSTATUS BCryptDecapsulate(
_In_ BCRYPT_KEY_HANDLE hKey,
_In_reads_bytes_(cbCipherText)
PUCHAR pbCipherText,
_In_ ULONG cbCipherText,
_Out_writes_bytes_to_opt_(cbSecretKey, *pcbSecretKey)
PUCHAR pbSecretKey,
_In_ ULONG cbSecretKey,
_Out_ ULONG *pcbSecretKey,
_In_ ULONG dwFlags
);
Parameters
hKey[in]
用于解封 KEM 密码文本的密钥的句柄。 这必须是对应于用于生成 KEM 密码文本的公共（封装）密钥的私有（解封）密钥。 The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
指向包含 KEM 密码文本的缓冲区的指针。 The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
指向接收共享密钥的缓冲区的指针。 See remarks for more information.
cbSecretKey[in]
The size, in bytes, of the pbSecretKey buffer.
pcbSecretKey[out]
A pointer to a ULONG variable that the receives the number of bytes written to pbSecretKey buffer.
If pbSecretKey is NULL, this receives the size, in bytes, required for the shared secret key.
See remarks for more information.
dwFlags[in]
保留，必须为零。
Return value
返回一个状态代码，指示函数的成功或失败。
可能的返回代码包括但不限于以下代码。
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
函数成功。 |
STATUS_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pbCipherText) is NULL, or one of the parameters has an invalid value. |
STATUS_INVALID_BUFFER_SIZE |
A buffer size (cbSecretKey, cbCipherText) does not match the expected size for the KEM parameters associated with the decapsulation key. |
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. |
Remarks
To query the required size of the pbSecretKey buffer needed for the KEM shared secret key, call BCryptDecapsulate with a NULLpbSecretKey. The required size will be returned in pcbSecretKey. 此查询效率高，无需执行解封即可返回大小。
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
对于当前支持的 KEM 算法（ML-KEM），共享机密长度是给定算法的常量大小。
Additional remarks
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. 当对等方的对称密钥不匹配时，这会强制更高级别的协议在以后失败。 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).
Requirements
| Requirement | Value |
|---|---|
| 最低支持的客户端 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| 支持的最低服务器 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |