BCryptDecapsulate function

Note

Beberapa informasi berkaitan dengan produk prarilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini. Fitur yang dijelaskan dalam topik ini tersedia dalam versi pra-rilis Windows Insider Preview.

The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Dibutuhkan ciphertext KEM dan mendekripsi dengan kunci privat yang disediakan, mengembalikan kunci rahasia bersama.

Jika ciphertext diformat dengan benar tetapi tidak cocok dengan kunci dekapsulasi, API ini akan berhasil tetapi kunci rahasia bersama acak akan dihasilkan.

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]

Handel kunci yang digunakan untuk memisahkan ciphertext KEM. Ini harus berupa kunci privat (dekapsulasi) yang sesuai dengan kunci publik (enkapsulasi) yang digunakan untuk menghasilkan ciphertext KEM. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.

pbCipherText[in]

Penunjuk ke buffer yang berisi ciphertext KEM. The BCryptEncapsulate function may be used to create a KEM ciphertext.

cbCipherText[in]

The size, in bytes, of the pbCipherText buffer.

pbSecretKey[out]

Penunjuk ke buffer yang menerima kunci rahasia bersama. 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]

Dicadangkan, harus nol.

Return value

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini.

Return Code	Description
STATUS_SUCCESS	Fungsi berhasil.
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. Kueri ini efisien dan mengembalikan ukuran tanpa melakukan dekapsulasi. Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle. Untuk algoritma KEM yang saat ini didukung (ML-KEM), panjang rahasia bersama adalah ukuran konstan untuk algoritma tertentu.

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. Ini memaksa protokol tingkat yang lebih tinggi untuk gagal nanti ketika kunci konten serekan tidak cocok. 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
Klien minimum yang didukung	Windows Insider (build 27843): Dukungan untuk ML-KEM dimulai. [hanya aplikasi desktop]
Server minimum yang didukung	Windows Insider (build 27843): Dukungan untuk ML-KEM dimulai. [hanya aplikasi desktop]
Library	Bcrypt.lib
DLL	Bcrypt.dll

See also

BCryptEncapsulate

BCryptGetProperty