注释
某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。 本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。
BCryptDecapsulate 函数执行密钥封装机制（KEM）的解封作。 它采用 KEM 密码文本，并使用提供的私钥进行解密，并返回共享密钥。
如果密码文本格式正确，但与解封密钥不匹配，则此 API 将成功，但将生成随机共享密钥。
语法
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
);
参数
hKey[in]
用于解封 KEM 密码文本的密钥的句柄。 这必须是对应于用于生成 KEM 密码文本的公共（封装）密钥的私有（解封）密钥。 密钥句柄是从密钥对创建函数之一（如 BCryptGenerateKeyPair 或 BCryptImportKeyPair）获取的。
pbCipherText[in]
指向包含 KEM 密码文本的缓冲区的指针。 BCryptEncapsulate 函数可用于创建 KEM 密码文本。
cbCipherText[in]
pbCipherText 缓冲区的大小（以字节为单位）。
pbSecretKey[out]
指向接收共享密钥的缓冲区的指针。 有关详细信息 ，请参阅备注 。
cbSecretKey[in]
pbSecretKey 缓冲区的大小（以字节为单位）。
apiSecretKey[out]
指向 ULONG 变量的指针，该变量接收写入 pbSecretKey 缓冲区的字节数。
如果 pbSecretKey 是 NULL，则会接收共享密钥所需的大小（以字节为单位）。
有关详细信息 ，请参阅备注 。
dwFlags[in]
保留，必须为零。
返回值
返回一个状态代码，指示函数的成功或失败。
可能的返回代码包括但不限于以下代码。
| 返回代码 | DESCRIPTION |
|---|---|
STATUS_SUCCESS |
函数成功。 |
STATUS_INVALID_PARAMETER |
一个或多个必需的参数（hKey、 hpSecretKey、 pbCipherText）或 NULL其中一个参数具有无效值。 |
STATUS_INVALID_BUFFER_SIZE |
缓冲区大小（cbSecretKey，cbCipherText）与与解封密钥关联的 KEM 参数的预期大小不匹配。 |
STATUS_BUFFER_TOO_SMALL |
输出缓冲区大小（cbSecretKey）对于与解封键关联的 KEM 参数的结果解封作来说太小。 pbSecretKey 接收 pbSecretKey 所需的字节数。 |
注解
若要查询 KEM 共享密钥所需的 pbSecretKey 缓冲区所需的大小，请使用 NULLpbSecretKey 调用 BCryptDecapsulate。 所需的大小将在 secretKey 中返回。 此查询效率高，无需执行解封即可返回大小。
同样，使用 BCryptGetProperty 查询算法或密钥句柄的 BCRYPT_KEM_SHARED_SECRET_LENGTH 属性。
对于当前支持的 KEM 算法（ML-KEM），共享机密长度是给定算法的常量大小。
其他备注
给定无效但大小正确的密码文本，ML-KEM 解封作将通过将成功返回与有效的解封作相等的时间（带有伪随机共享密钥输出） 隐式拒绝 密码文本。 当对等方的对称密钥不匹配时，这会强制更高级别的协议在以后失败。 因此，如果出现编程错误（即大小不正确、使用未初始化 的 hKey），或者环境发生根本问题（即内部内存分配失败或内部一致性测试检测到硬件错误），则解封只会失败。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows 预览体验成员预览版 [仅限桌面应用] |
| 支持的最低服务器 | Windows 预览体验成员预览版 [仅限桌面应用] |
| 图书馆 | Bcrypt.lib |
| DLL | Bcrypt.dll |