Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Note
Некоторые сведения относятся к предварительному продукту, который может быть существенно изменен до его коммерческого выпуска. Корпорация Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых в отношении информации, предоставленной здесь. Функция, описанная в этом разделе, доступна в предварительной версии Предварительной версии Windows Preview.
The NCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Он принимает зашифрованный текст KEM и расшифровывает предоставленный закрытый ключ, возвращая общий секретный ключ.
Если зашифрованный текст правильно отформатирован, но не соответствует ключу декапсуляции, этот API будет успешно выполнен, но будет создан случайный общий секретный ключ.
Syntax
SECURITY_STATUS NCryptDecapsulate (
[in] NCRYPT_KEY_HANDLE hKey,
[in] PCBYTE pbCipherText,
[in] ULONG cbCipherText,
[out] PBYTE pbSecretKey,
[in] ULONG cbSecretKey,
[out] ULONG *pcbSecretKey,
[in] ULONG dwFlags
);
Parameters
hKey[in]
Дескриптор ключа, используемый для операции декапсуляции.
pbCipherText[in]
Указатель на буфер, содержащий зашифрованный текст KEM. The NCryptEncapsulate 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 |
|---|---|
ERROR_SUCCESS |
Функция была успешной. |
NTE_BAD_FLAGS |
The dwFlags parameter contains a value that is not valid. |
NTE_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pcbCipherText) is NULL, or one of the parameters has an invalid value. |
NTE_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 NCryptDecapsulate with a NULLpbSecretKey. The required size will be returned in pcbSecretKey. Этот запрос эффективен и возвращает размер без декапсуляции.
Equivalently, use NCryptGetProperty to query the NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY 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 agreed secret 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 self-test detect hardware error).
Requirements
| Requirement | Value |
|---|---|
| Минимальный поддерживаемый клиент | Программы предварительной оценки Windows (сборка 27843): Начинается поддержка ML-KEM. [только классические приложения] |
| минимальный поддерживаемый сервер | Программы предварительной оценки Windows (сборка 27843): Начинается поддержка ML-KEM. [только классические приложения] |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |