CryptProtectData-Funktion (dpapi.h)

Die CryptProtectData-Funktion führt die Verschlüsselung der Daten in einer DATA_BLOB-Struktur durch. In der Regel kann nur ein Benutzer mit den gleichen Anmeldeinformationen wie der Benutzer, der die Daten verschlüsselt hat, die Daten entschlüsseln. Darüber hinaus muss die Verschlüsselung und Entschlüsselung in der Regel auf demselben Computer erfolgen. Informationen zu Ausnahmen finden Sie unter Hinweise.

Syntax

DPAPI_IMP BOOL CryptProtectData(
  [in]           DATA_BLOB                 *pDataIn,
  [in, optional] LPCWSTR                   szDataDescr,
  [in, optional] DATA_BLOB                 *pOptionalEntropy,
  [in]           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 den zu verschlüsselnden Klartext enthält.

[in, optional] szDataDescr

Eine Zeichenfolge mit einer lesbaren Beschreibung der zu verschlüsselnden Daten. Diese Beschreibungszeichenfolge ist in den verschlüsselten Daten enthalten. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in, optional] pOptionalEntropy

Ein Zeiger auf eine DATA_BLOB Struktur, die ein Kennwort oder eine andere zusätzliche Entropie enthält, die zum Verschlüsseln der Daten verwendet wird. Die in der Verschlüsselungsphase verwendete DATA_BLOB-Struktur muss auch in der Entschlüsselungsphase verwendet werden. Dieser Parameter kann ohne zusätzliche Entropie auf NULL festgelegt werden. Informationen zum Schutz von Kennwörtern finden Sie unter Behandeln von Kennwörtern.

[in] pvReserved

Reserviert für die zukünftige Verwendung 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 was der Inhalt dieser Eingabeaufforderungen sein soll. Dieser Parameter kann sowohl in der Verschlüsselungs- als auch in der Entschlüsselungsphase auf NULL festgelegt werden.

[in] dwFlags

Dieser Parameter kann eines der folgenden Flags sein.

[out] pDataOut

Ein Zeiger auf eine DATA_BLOB Struktur, die die verschlüsselten Daten empfängt. 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, gibt sie FALSE zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweise

In der Regel kann nur ein Benutzer mit Anmeldeinformationen , die mit denen des Benutzers übereinstimmen, der die Daten verschlüsselt hat, die Daten entschlüsseln. Darüber hinaus kann die Entschlüsselung in der Regel nur auf dem Computer erfolgen, auf dem die Daten verschlüsselt wurden. Ein Benutzer mit einem Roamingprofil kann die Daten jedoch von einem anderen Computer im Netzwerk entschlüsseln.

Wenn das CRYPTPROTECT_LOCAL_MACHINE-Flag festgelegt ist, wenn die Daten verschlüsselt werden, kann jeder Benutzer auf dem Computer, auf dem die Verschlüsselung durchgeführt wurde, die Daten entschlüsseln.

Die Funktion erstellt einen Sitzungsschlüssel, um die Verschlüsselung durchzuführen. Der Sitzungsschlüssel wird erneut abgeleitet, wenn die Daten entschlüsselt werden sollen.

Die Funktion fügt auch einen Nachrichtenauthentifizierungscode (MAC) (Keyed Integrity Check) zu den verschlüsselten Daten hinzu, um vor Datenmanipulationen zu schützen.

Rufen Sie die Funktion CryptProtectMemory auf, um Arbeitsspeicher für die temporäre Verwendung im selben Prozess oder prozessübergreifend zu verschlüsseln.

Beispiele

Das folgende Beispiel zeigt die Verschlüsselung der Daten in einer DATA_BLOB-Struktur . Die CryptProtectData-Funktion führt die Verschlü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.

// Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.

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

DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;

//--------------------------------------------------------------------
// Initialize the DataIn structure.

DataIn.pbData = pbDataInput;    
DataIn.cbData = cbDataInput;

//--------------------------------------------------------------------
//  Begin protect phase. Note that the encryption key is created
//  by the function and is not passed.

if(CryptProtectData(
     &DataIn,
     L"This is the description string.", // A description string
                                         // to be included with the
                                         // encrypted data. 
     NULL,                               // Optional entropy not used.
     NULL,                               // Reserved.
     NULL,                               // Pass NULL for the 
                                         // prompt structure.
     0,
     &DataOut))
{
     printf("The encryption phase worked.\n");
     LocalFree(DataOut.pbData);
}
else
{
    printf("Encryption error using CryptProtectData.\n");
    exit(1); 
}

Anforderungen

Weitere Informationen

CryptProtectMemory

CryptUnprotectData

Datenverschlüsselungs- und Entschlüsselungsfunktionen

LocalFree