BCryptDecapsulate function

Note

Некоторые сведения относятся к предварительному продукту, который может быть существенно изменен до его коммерческого выпуска. Корпорация Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых в отношении информации, предоставленной здесь. Функция, описанная в этом разделе, доступна в предварительной версии Предварительной версии Windows 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

See also

BCryptEncapsulate

BCryptGetProperty