通过

BCryptEncapsulate 函数

注释

某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。 本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。

BCryptEncapsulate 函数执行密钥封装机制（KEM）的封装作。 它生成共享密钥，并使用提供的公钥对其进行加密，以生成 KEM 密码文本，同时返回共享密钥和 KEM 密码文本。

语法

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
);

参数

hKey[in]

用于封装作的密钥的句柄。 此密钥必须包含公共（封装）密钥，并且通常通过使用 BCryptImportKeyPair 和 KEM 算法的 公钥 BLOB 来获取句柄。 还可以将私钥句柄用于封装作，因为 KEM 私钥句柄表示密钥对。

pbSecretKey[out]

指向接收共享密钥的缓冲区的指针。 有关详细信息 ，请参阅备注 。

cbSecretKey[in]

pbSecretKey 缓冲区的大小（以字节为单位）。

apiSecretKey[out]

指向 ULONG 变量的指针，该变量接收写入 pbSecretKey 缓冲区的字节数。

如果 pbSecretKey 是 NULL，则会接收共享密钥所需的大小（以字节为单位）。 有关详细信息 ，请参阅备注 。

pbCipherText[out]

指向接收 KEM 密码文本的缓冲区的指针。 有关详细信息 ，请参阅备注 。

cbCipherText[in]

pbCipherText 缓冲区的大小（以字节为单位）。

sslCipherText[out]

指向 ULONG 变量的指针，该变量接收写入 pbCipherText 缓冲区的字节数。

如果 pbCipherText 为 NULL，则会接收 KEM 密码文本所需的大小（以字节为单位）。 有关详细信息 ，请参阅备注 。

dwFlags[in]

保留，必须为零。

返回值

返回一个状态代码，指示函数的成功或失败。

可能的返回代码包括但不限于以下代码。

返回代码 DESCRIPTION
STATUS_SUCCESS 函数成功。
STATUS_INVALID_PARAMETER 一个或多个必需的参数（hKey、 hpSecretKey、 hpCipherText）或 NULL其中一个参数具有无效值。
STATUS_INVALID_BUFFER_SIZE 缓冲区大小（cbSecretKey，cbCipherText）与与封装密钥关联的 KEM 参数的预期大小不匹配。 * pbSecretKey 接收 pbSecretKey 所需的字节数， pbCipherText 接收 pbCipherText 所需的字节数。
STATUS_BUFFER_TOO_SMALL 输出缓冲区大小（cbSecretKey，cbCipherText）对于与封装密钥关联的 KEM 参数的结果封装作来说太小。 pbSecretKey 接收 pbSecretKey 所需的字节数， pbCipherText 接收 pbCipherText 所需的字节数。

注解

若要查询 pbSecretKey 和 pbCipherText 缓冲区的所需大小，调用方可以使用 pbSecretKey 和 pbCipherText 调用 BCryptEncapsulateNULL。 所需的大小将分别以 secretKey 和 毫秒密码文本返回。 此查询效率高，无需执行封装即可返回大小。 同样，使用 BCryptGetProperty 查询算法或密钥句柄的 BCRYPT_KEM_SHARED_SECRET_LENGTH 属性，以及密钥句柄的 BCRYPT_KEM_CIPHERTEXT_LENGTH 属性。 对于当前支持的 KEM 算法（ML-KEM），共享机密长度是给定算法的常量大小，KEM 密码文本长度是给定参数集的常量大小。

要求

要求 价值
最低支持的客户端 Windows 预览体验成员预览版 [仅限桌面应用]
支持的最低服务器 Windows 预览体验成员预览版 [仅限桌面应用]
图书馆 Bcrypt.lib
DLL Bcrypt.dll

另请参阅

BCryptDecapsulate

BCryptGetProperty