Note
某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。 本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。
The NCryptEncapsulate function performs the Encapsulation operation of a Key Encapsulation Mechanism (KEM). 它生成共享密钥，并使用提供的公钥对其进行加密，以生成 KEM 密码文本，同时返回共享密钥和 KEM 密码文本。
Syntax
NTSTATUS NCryptEncapsulate (
[in] NCRYPT_KEY_HANDLE hKey
[out] PBYTE pbSecretKey,
[in] ULONG cbSecretKey,
[out] ULONG *pcbSecretKey,
[out] PBYTE pbCipherText,
[in] ULONG cbCipherText,
[out] ULONG *pcbCipherText,
[in] ULONG dwFlags
);
Parameters
hKey[in]
用于封装作的密钥的句柄。
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 |
|---|---|
ERROR_SUCCESS |
函数成功。 |
NTE_BAD_FLAGS |
The dwFlags parameter contains a value that is not valid. |
NTE_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pcbCipherText) is NULL, or one of the parameters has an invalid value. |
NTE_BUFFER_TOO_SMALL |
An output buffer size (cbSecretKey, cbCipherText) is too small for the result of the encapsulation 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 NCryptEncapsulate with NULL values in pbSecretKey and pbCipherText. The required size will be returned in pcbSecretKey and pcbCipherText, respectively. 此查询效率高，无需执行封装即可返回大小。
Equivalently, use NCryptGetProperty to query the NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY property of the algorithm or key handle, and the NCRYPT_KEM_CIPHERTEXT_LENGTH_PROPERTY property of the key handle.
对于当前支持的 KEM 算法（ML-KEM），共享机密长度是给定算法的常量大小，KEM 密码文本长度是给定参数集的常量大小。
Requirements
| Requirement | Value |
|---|---|
| 最低支持的客户端 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| 支持的最低服务器 | Windows 预览体验成员（内部版本 27843）： 开始对 ML-KEM 的支持。 [仅限桌面应用] |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |