Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Note
Viss information gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här. Funktionen som beskrivs i det här avsnittet är tillgänglig i förhandsversioner av Windows Insider Preview.
The NCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Det tar en KEM-chiffertext och dekrypterar med den tillhandahållna privata nyckeln och returnerar den delade hemliga nyckeln.
Om chiffertexten är korrekt formaterad men inte matchar inkapslingsnyckeln lyckas det här API:et, men en slumpmässig delad hemlighetsnyckel genereras.
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]
Handtaget för nyckeln som ska användas för inkapslingsåtgärden.
pbCipherText[in]
En pekare till en buffert som innehåller KEM-chiffertexten. The NCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
En pekare till en buffert som tar emot den delade hemlighetsnyckeln. 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]
Reserverad, måste vara noll.
Return value
Returnerar en statuskod som anger att funktionen lyckades eller misslyckades.
Möjliga returkoder inkluderar, men är inte begränsade till, följande.
| Return Code | Description |
|---|---|
ERROR_SUCCESS |
Funktionen lyckades. |
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. Den här frågan är effektiv och returnerar storleken utan att utföra inkapslingen.
Equivalently, use NCryptGetProperty to query the NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY property of the algorithm or key handle.
För kem-algoritmer som stöds (ML-KEM) är den delade hemlighetens längd en konstant storlek för en viss algoritm.
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. Detta tvingar protokoll på högre nivå att misslyckas senare när symmetriska nycklar för peer-datorer inte matchar. 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 |
|---|---|
| Lägsta klient som stöds | Windows Insiders (version 27843): Stödet för ML-KEM börjar. [endast skrivbordsappar] |
| Lägsta server som stöds | Windows Insiders (version 27843): Stödet för ML-KEM börjar. [endast skrivbordsappar] |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |