NCryptDecapsulate-Funktion

2025-06-06

Hinweis

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.

Die NCryptDecapsulate-Funktion führt den Entkapselungsvorgang eines Schlüsselkapselungsmechanismus (KEM) aus. 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

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
);

Die Parameter

hKey[in]

Das Handle des Schlüssels, der für den Entkapselungsvorgang verwendet werden soll.

pbCipherText[in]

Ein Zeiger auf einen Puffer, der den KEM-Chiffretext enthält. Die Funktion "NCryptEncapsulate " kann zum Erstellen eines KEM-Chiffretexts verwendet werden.

cbCipherText[in]

Die Größe des PbCipherText-Puffers in Bytes.

pbSecretKey[out]

Ein Zeiger auf einen Puffer, der den freigegebenen geheimen Schlüssel empfängt. Weitere Informationen finden Sie in den Hinweisen .

cbSecretKey[in]

Die Größe des PbSecretKey-Puffers in Bytes.

pcbSecretKey[out]

Ein Zeiger auf eine ULONG-Variable , die die Anzahl der Bytes empfängt, die in pbSecretKey-Puffer geschrieben wurden.

Wenn pbSecretKey lautet NULL, erhält dies die Größe in Bytes, die für den freigegebenen geheimen Schlüssel erforderlich ist. Weitere Informationen finden Sie in den Hinweisen .

dwFlags[in]

Reserviert, muss Null sein.

Rückgabewert

Gibt einen Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes umfassen, aber nicht beschränkt auf Folgendes.

Rückgabecode	BESCHREIBUNG
`ERROR_SUCCESS`	Die Funktion war erfolgreich.
`NTE_BAD_FLAGS`	Der dwFlags-Parameter enthält einen ungültigen Wert.
`NTE_INVALID_PARAMETER`	Mindestens ein erforderlicher Parameter (hKey, pcbSecretKey, pcbCipherText) ist NULL, oder einer der Parameter weist einen ungültigen Wert auf.
`NTE_BUFFER_TOO_SMALL`	Eine Ausgabepuffergröße (cbSecretKey) ist zu klein für den Ergebnistrennvorgang für die KEM-Parameter, die dem Entkapselungsschlüssel zugeordnet sind. pcbSecretKey empfängt die Anzahl der bytes, die für pbSecretKey erforderlich sind.

Bemerkungen

Rufen Sie NCryptDecapsulate mit einem NULLpbSecretKey-Schlüssel auf, um die erforderliche Größe des pbSecretKey-Puffers abzufragen, der für den gemeinsam genutzten Schlüssel keM erforderlich ist. Die erforderliche Größe wird in pcbSecretKey zurückgegeben. Diese Abfrage ist effizient und gibt die Größe zurück, ohne die Entkapselung auszuführen. Verwenden Sie NCryptGetProperty , um die NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY Eigenschaft des Algorithmus oder des Tastenhandle abzufragen. 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.

Weitere Hinweise

Angesichts eines ungültigen, aber korrekten Chiffretexts lehnt der ML-KEM Entkapselungsvorgang implizit den Chiffretext ab, indem er den Erfolg in gleicher Zeit an einen gültigen Entkapselungsvorgang zurückgibt, wobei pseudo-zufällig vereinbarte geheime Ausgabe vorhanden ist. Dadurch werden Protokolle auf höherer Ebene später fehlschlagen, wenn symmetrische Schlüssel von Peers nicht übereinstimmen. Wenn also Programmierfehler auftreten (z. B. falsche Größe, Verwendung nicht initialisierter hKey) oder etwas grundsätzlich mit der Umgebung schief geht (d. h. interne Speicherzuweisung schlägt fehl, oder Selbsttest erkennt Hardwarefehler).

Anforderungen

Anforderung	Wert
Mindestens unterstützter Client	Windows Insiders Preview [nur Desktop-Apps]
Mindestanforderungen für unterstützte Server	Windows Insiders Preview [nur Desktop-Apps]
Bibliothek	`Ncrypt.lib`
DLL	`Ncrypt.dll`

Siehe auch