Note
某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。 本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。
The BCryptEncapsulate function performs the Encapsulation operation of a Key Encapsulation Mechanism (KEM). 它生成共享密钥，并使用提供的公钥对其进行加密，以生成 KEM 密码文本，同时返回共享密钥和 KEM 密码文本。
Syntax
NTSTATUS BCryptEncapsulate(
_In_ BCRYPT_KEY_HANDLE hKey,
_Out_writes_bytes_to_opt_(cbSecretKey ,*pcbSecretKey)
PUCHAR pbSecretKey,
_In_ ULONG cbSecretKey,
_Out_ ULONG *pcbSecretKey,
_Out_writes_bytes_to_opt_(cbCipherText ,*pcbCipherText)
PUCHAR pbCipherText,
_In_ ULONG cbCipherText,
_Out_ ULONG *pcbCipherText,
_In_ ULONG dwFlags
);
Parameters
hKey[in]
用于封装作的密钥的句柄。 This key must contain a public (encapsulation) key, and the handle would typically be obtained by using BCryptImportKeyPair with a public key BLOB for the KEM algorithm. 还可以将私钥句柄用于封装作，因为 KEM 私钥句柄表示密钥对。
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.
pbCipherText[out]
指向接收 KEM 密码文本的缓冲区的指针。 See remarks for more information.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pcbCipherText[out]
A pointer to a ULONG variable that the receives the number of bytes written to pbCipherText buffer.
If pbCipherText is NULL, this receives the size, in bytes, required for the KEM ciphertext.
See remarks for more information.
dwFlags[in]
保留，必须为零。
Return value
返回一个状态代码，指示函数的成功或失败。
可能的返回代码包括但不限于以下代码。
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
函数成功。 |
STATUS_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pcbCipherText) 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 encapsulation key. *pcbSecretKey receives the number of bytes required for pbSecretKey, pcbCipherText receives the number of bytes required for pbCipherText. |
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. |
Remarks
To query the required sizes of the pbSecretKey and pbCipherText buffers, callers may call BCryptEncapsulate with NULLpbSecretKey and pbCipherText. The required sizes will be returned in pcbSecretKey and pcbCipherText, respectively. 此查询效率高，无需执行封装即可返回大小。
Equivalently, use 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.
对于当前支持的 KEM 算法（ML-KEM），共享机密长度是给定算法的常量大小，KEM 密码文本长度是给定参数集的常量大小。
Requirements
| Requirement | Value |
|---|---|
| 最低支持的客户端 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| 支持的最低服务器 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |