Note
某些資訊與一款尚未正式發行的產品有關，該產品在正式推出之前可能會進行大幅修改。 Microsoft 對於此處提供的資訊，不做任何明確或隱含的保證。 本主題所述的功能可在 Windows Insider Preview發行前版本取得。
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). 它會採用 KEM 加密文字，並使用提供的私鑰進行解密，並傳回共用的秘密金鑰。
如果加密文字的格式正確，但不符合解構密鑰，則此 API 將會成功，但會產生隨機共用的秘密密鑰。
Syntax
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
);
Parameters
hKey[in]
用來解譯 KEM 加密文字之金鑰的句柄。 這必須是對應至用來產生 KEM 加密文字之公用 （封裝） 金鑰的私人 （解構） 金鑰。 The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
緩衝區的指標，其中包含 KEM 加密文字。 The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
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.
dwFlags[in]
保留的 必須是零。
Return value
傳回狀態代碼，指出函式的成功或失敗。
可能的傳回碼包括，但不限於下列專案。
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
函式成功。 |
STATUS_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pbCipherText) 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 decapsulation key. |
STATUS_BUFFER_TOO_SMALL |
An output buffer size (cbSecretKey) is too small for the result decapsulation operation for the KEM parameters associated with the decapsulation key. pcbSecretKey receives the number of bytes required for pbSecretKey. |
Remarks
To query the required size of the pbSecretKey buffer needed for the KEM shared secret key, call BCryptDecapsulate with a NULLpbSecretKey. The required size will be returned in pcbSecretKey. 此查詢有效率，而且會傳回大小，而不需要執行解構。
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
對於目前支援的 KEM 演算法（ML-KEM），共用的秘密長度是指定演算法的常數大小。
Additional remarks
Given an invalid, but correctly-sized, ciphertext, the ML-KEM decapsulation operation will implicitly reject the ciphertext by returning success in equal time to a valid decapsulation operation, with pseudo-random shared secret key output. 當對等的對稱密鑰不相符時，這會強制較高層級的通訊協定稍後失敗。 So, decapsulate will only ever fail if there are programming errors (i.e. incorrect size, use of uninitialized hKey), or something fundamentally goes wrong with the environment (i.e. internal memory allocation fails, or and internal consistency test detects hardware error).
Requirements
| Requirement | Value |
|---|---|
| 最低支援的用戶端 | Windows 測試人員 （組建 27843）： 開始支援 ML-KEM。 [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows 測試人員 （組建 27843）： 開始支援 ML-KEM。 [僅限傳統型應用程式] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |