Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Note
Einige Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Veröffentlichung erheblich geändert werden kann. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen. Das in diesem Thema beschriebene Feature ist in Vorabversionen der Windows Insider Previewverfügbar.
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Es akzeptiert einen KEM-Chiffretext und entschlüsselt ihn mit dem bereitgestellten privaten Schlüssel und gibt den freigegebenen geheimen Schlüssel zurück.
Wenn der Chiffretext korrekt formatiert ist, aber nicht mit dem Entkapselungsschlüssel übereinstimmt, wird diese API erfolgreich ausgeführt, aber ein zufällig freigegebener geheimer Schlüssel wird generiert.
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]
Der Ziehpunkt des Schlüssels, der zum Entkapseln des KEM-Chiffretexts verwendet werden soll. Dies muss der private Schlüssel (Entkapselung) sein, der dem öffentlichen Schlüssel (Kapselung) entspricht, der zum Erzeugen des KEM-Chiffretexts verwendet wird. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
Ein Zeiger auf einen Puffer, der den KEM-Chiffretext enthält. The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
Ein Zeiger auf einen Puffer, der den freigegebenen geheimen Schlüssel empfängt. 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]
Reserviert, muss Null sein.
Return value
Gibt einen Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.
Mögliche Rückgabecodes umfassen, aber nicht beschränkt auf Folgendes.
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
Die Funktion war erfolgreich. |
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. Diese Abfrage ist effizient und gibt die Größe zurück, ohne die Entkapselung auszuführen.
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
Bei derzeit unterstützten KEM-Algorithmen (ML-KEM) ist die Länge des freigegebenen geheimen Schlüssels eine konstante Größe für einen bestimmten Algorithmus.
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. Dadurch werden Protokolle auf höherer Ebene später fehlschlagen, wenn symmetrische Schlüssel von Peers nicht übereinstimmen. 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 |
|---|---|
| Mindestens unterstützter Client | Windows-Insider (Build 27843): Die Unterstützung für ML-KEM beginnt. [Nur Desktop-Apps] |
| Mindestanforderungen für unterstützte Server | Windows-Insider (Build 27843): Die Unterstützung für ML-KEM beginnt. [Nur Desktop-Apps] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |