CryptProtectData-Funktion (dpapi.h)

Die CryptProtectData-Funktion führt Verschlüsselung für die 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 in den Hinweisen.

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

Die 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 für keine zusätzliche Entropie auf NULL festgelegt werden. Informationen zum Schützen 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 welche Inhalte diese Eingabeaufforderungen enthalten sollen. Dieser Parameter kann in den Verschlüsselungs- und Entschlüsselungsphasen auf NULL festgelegt werden.

[in] dwFlags

Dieser Parameter kann eine der folgenden Flags sein. Wenn keine Flags erforderlich sind, kann dieser Parameter auf 0.

[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 durch Aufrufen der LocalFree-Funktion frei.

Rückgabewert

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

Wenn die Funktion fehlschlägt, wird FALSE zurückgegeben. Rufen Sie getLastError für erweiterte Fehlerinformationen auf.

Bemerkungen

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 wird, wenn die Daten verschlüsselt sind, 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 auszuführen. Der Sitzungsschlüssel wird erneut abgeleitet, wenn die Daten entschlüsselt werden sollen.

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

Rufen Sie die CryptProtectMemory-Funktion auf, um den Speicher für die temporäre Verwendung im selben Prozess oder über Prozesse hinweg zu verschlüsseln.

Examples

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

Siehe auch

• CryptProtectMemory
• CryptUnprotectData
• Datenverschlüsselungs- und Entschlüsselungsfunktionen
• LocalFree