Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Note
Cierta información se relaciona con un producto de versión preliminar que puede modificarse sustancialmente antes de su publicación comercial. Microsoft no ofrece ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí. La característica descrita en este tema está disponible en versiones preliminares de Windows Insider Preview.
The NCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Toma un texto cifrado KEM y se descifra con la clave privada proporcionada y devuelve la clave secreta compartida.
Si el texto cifrado tiene el formato correcto, pero no coincide con la clave de descapsulación, esta API se realizará correctamente, pero se generará una clave secreta compartida aleatoria.
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]
Identificador de la clave que se va a usar para la operación de descapsulación.
pbCipherText[in]
Puntero a un búfer que contiene el texto cifrado KEM. The NCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
Puntero a un búfer que recibe la clave secreta compartida. 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]
Reservado, debe ser cero.
Return value
Devuelve un código de estado que indica el éxito o error de la función.
Entre los códigos de retorno posibles se incluyen, entre otros, los siguientes.
| Return Code | Description |
|---|---|
ERROR_SUCCESS |
La función se realizó correctamente. |
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. Esta consulta es eficaz y devuelve el tamaño sin realizar la descapsulación.
Equivalently, use NCryptGetProperty to query the NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY property of the algorithm or key handle.
Para los algoritmos KEM admitidos actualmente (ML-KEM), la longitud del secreto compartido es un tamaño constante para un algoritmo determinado.
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. Esto obliga a que los protocolos de nivel superior produzcan errores más adelante cuando las claves simétricas de los elementos del mismo nivel no coinciden. 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 |
|---|---|
| Cliente mínimo compatible | Windows Insiders (compilación 27843): Comienza la compatibilidad con ML-KEM. [solo aplicaciones de escritorio] |
| Servidor mínimo admitido | Windows Insiders (compilación 27843): Comienza la compatibilidad con ML-KEM. [solo aplicaciones de escritorio] |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |