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 |