CryptUnprotectData-Funktion (dpapi.h)

Artikel
08/23/2023

Die CryptUnprotectData-Funktion entschlüsselt und führt eine Integritätsprüfung der Daten in einer DATA_BLOB-Struktur durch. In der Regel ist der einzige Benutzer, der die Daten entschlüsseln kann, ein Benutzer mit den gleichen Anmeldeinformationen wie der Benutzer, der die Daten verschlüsselt hat. Darüber hinaus muss die Ver- und Entschlüsselung auf demselben Computer erfolgen. Informationen zu Ausnahmen finden Sie im Abschnitt Hinweise von CryptProtectData.

Syntax

DPAPI_IMP BOOL CryptUnprotectData(
  [in]            DATA_BLOB                 *pDataIn,
  [out, optional] LPWSTR                    *ppszDataDescr,
  [in, optional]  DATA_BLOB                 *pOptionalEntropy,
                  PVOID                     pvReserved,
  [in, optional]  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  [in]            DWORD                     dwFlags,
  [out]           DATA_BLOB                 *pDataOut
);

Parameter

[in] pDataIn

Ein Zeiger auf eine DATA_BLOB Struktur, die die verschlüsselten Daten enthält. Das cbData-Element der DATA_BLOB-Struktur enthält die Länge der Bytezeichenfolge des pbData-Elements, die den zu verschlüsselnden Text enthält.

[out, optional] ppszDataDescr

Ein Zeiger auf eine Zeichenfolgenlesbare Beschreibung der verschlüsselten Daten, die in den verschlüsselten Daten enthalten sind. Dieser Parameter kann auf NULL festgelegt werden. Wenn Sie die Verwendung von ppszDataDescr abgeschlossen haben, geben Sie es frei, indem Sie die Funktion LocalFree aufrufen.

[in, optional] pOptionalEntropy

Ein Zeiger auf eine DATA_BLOB-Struktur , die ein Kennwort oder eine andere zusätzliche Entropie enthält, die beim Verschlüsseln der Daten verwendet wurde. Dieser Parameter kann auf NULL festgelegt werden. Wenn jedoch in der Verschlüsselungsphase eine optionale Entropie-DATA_BLOB-Struktur verwendet wurde, muss dieselbe DATA_BLOB-Struktur für die Entschlüsselungsphase verwendet werden. Informationen zum Schützen von Kennwörtern finden Sie unter Behandeln von Kennwörtern.

pvReserved

Dieser Parameter ist für die zukünftige Verwendung reserviert und muss auf NULL festgelegt werden.

[in, optional] pPromptStruct

Ein Zeiger auf eine CRYPTPROTECT_PROMPTSTRUCT-Struktur , die Informationen darüber bereitstellt, wo und wann Eingabeaufforderungen angezeigt werden sollen und wie der Inhalt dieser Eingabeaufforderungen sein sollte. Dieser Parameter kann auf NULL festgelegt werden.

[in] dwFlags

Ein DWORD-Wert , der Optionen für diese Funktion angibt. Dieser Parameter kann null sein. In diesem Fall ist keine Option festgelegt, oder das folgende Flag.

Wert	Bedeutung
CRYPTPROTECT_UI_FORBIDDEN	Dieses Flag wird für Remotesituationen verwendet, in denen die Benutzeroberfläche (UI) keine Option ist. Wenn dieses Flag festgelegt ist und die Benutzeroberfläche entweder für den Schutzvorgang oder den Vorgang zum Aufheben des Schützens angegeben ist, schlägt der Vorgang fehl, und GetLastError gibt den ERROR_PASSWORD_RESTRICTION Code zurück.
CRYPTPROTECT_VERIFY_PROTECTION	Dieses Flag überprüft den Schutz eines geschützten BLOB. Wenn die vom Host konfigurierte Standardschutzebene höher als die aktuelle Schutzebene für das BLOB ist, gibt die Funktion CRYPT_I_NEW_PROTECTION_REQUIRED zurück, um den Aufrufer zu empfehlen, den im BLOB enthaltenen Klartext erneut zu schützen.

[out] pDataOut

Ein Zeiger auf eine DATA_BLOB-Struktur , in der die Funktion die entschlüsselten Daten speichert. Wenn Sie die Verwendung der DATA_BLOB-Struktur abgeschlossen haben, geben Sie dessen pbData-Member frei, indem Sie die LocalFree-Funktion aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion TRUE zurück.

Wenn die Funktion fehlschlägt, wird FALSE zurückgegeben.

Hinweise

Die CryptProtectData-Funktion erstellt einen Sitzungsschlüssel, wenn die Daten verschlüsselt werden. Dieser Schlüssel wird erneut abgeleitet und zum Entschlüsseln des Datenblobs verwendet.

Der den verschlüsselten Daten hinzugefügte Mac-Hash (Message Authentication Code) kann verwendet werden, um zu bestimmen, ob die verschlüsselten Daten in irgendeiner Weise geändert wurden. Jede Manipulation führt zur Rückgabe des ERROR_INVALID_DATA Codes.

Wenn Sie die Verwendung der DATA_BLOB-Struktur abgeschlossen haben, geben Sie dessen pbData-Member frei, indem Sie die LocalFree-Funktion aufrufen. Alle ppszDataDescr , die nicht NULL ist, müssen auch mithilfe von LocalFree freigegeben werden.

Wenn Sie die Verwendung vertraulicher Informationen abgeschlossen haben, löschen Sie sie aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen.

Beispiele

Das folgende Beispiel zeigt die Entschlüsselung verschlüsselter Daten in einer DATA_BLOB-Struktur . Diese Funktion führt die Entschlüsselung mithilfe eines Sitzungsschlüssels durch, den die Funktion mithilfe der Anmeldeinformationen des Benutzers erstellt. Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Verwenden von CryptProtectData.

// Decrypt data from DATA_BLOB DataOut to DATA_BLOB DataVerify.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataOut;
DATA_BLOB DataVerify;
LPWSTR pDescrOut =  NULL;
//--------------------------------------------------------------------
// The buffer DataOut would be created using the CryptProtectData
// function. If may have been read in from a file.

//--------------------------------------------------------------------
//   Begin unprotect phase.

if (CryptUnprotectData(
        &DataOut,
        &pDescrOut,
        NULL,                 // Optional entropy
        NULL,                 // Reserved
        NULL,                 // Here, the optional 
                              // prompt structure is not
                              // used.
        0,
        &DataVerify))
{
     printf("The decrypted data is: %s\n", DataVerify.pbData);
     printf("The description of the data was: %s\n",pDescrOut);
     LocalFree(DataVerify.pbData);
     LocalFree(pDescrOut);
}
else
{
    printf("Decryption error!");
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	dpapi.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll