BCryptDecapsulate function

The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Pobiera on szyfr KEM i odszyfrowuje go przy użyciu podanego klucza prywatnego, zwracając wspólny klucz tajny.

Jeśli tekst szyfrowania jest poprawnie sformatowany, ale nie jest zgodny z kluczem decapsulacji, ten interfejs API powiedzie się, ale zostanie wygenerowany losowy wspólny klucz tajny.

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]

Uchwyt klucza, który ma być używany do decapsulatego szyfrowania KEM. Musi to być klucz prywatny (decapsulation), który odpowiada kluczowi publicznemu (hermetyzacji) używanemu do tworzenia szyfrowania KEM. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.

pbCipherText[in]

Wskaźnik do buforu zawierającego szyfr KEM. The BCryptEncapsulate function may be used to create a KEM ciphertext.

cbCipherText[in]

The size, in bytes, of the pbCipherText buffer.

pbSecretKey[out]

Wskaźnik do buforu, który odbiera wspólny klucz tajny. 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]

Zarezerwowane, musi mieć wartość zero.

Return value

Zwraca kod stanu wskazujący powodzenie lub niepowodzenie funkcji.

Możliwe kody powrotne obejmują, ale nie są ograniczone do następujących.

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. To zapytanie jest wydajne i zwraca rozmiar bez przeprowadzania decapsulacji. Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle. W przypadku obecnie obsługiwanych algorytmów KEM (ML-KEM) współdzielona długość wpisu tajnego jest stałym rozmiarem danego algorytmu.

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. Wymusza to niepowodzenie protokołów wyższego poziomu później, gdy klucze symetryczne elementów równorzędnych nie są zgodne. 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

See also

BCryptEncapsulate

BCryptGetProperty