Funzione CryptUnprotectData (dpapi.h)
La funzione CryptUnprotectData decrittografa ed esegue un controllo di integrità dei dati in una struttura DATA_BLOB . In genere, l'unico utente che può decrittografare i dati è un utente con le stesse credenziali di accesso dell'utente che ha crittografato i dati. Inoltre, la crittografia e la decrittografia devono essere eseguite nello stesso computer. Per informazioni sulle eccezioni, vedere la sezione Osservazioni di CryptProtectData.
Sintassi
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
);
Parametri
[in] pDataIn
Puntatore a una struttura DATA_BLOB che contiene i dati crittografati. Il membro cbData della struttura DATA_BLOB contiene la lunghezza della stringa di byte del membro pbData contenente il testo da crittografare.
[out, optional] ppszDataDescr
Puntatore a una descrizione leggibile in formato stringa dei dati crittografati inclusi nei dati crittografati. Questo parametro può essere impostato su NULL. Al termine dell'uso di ppszDataDescr, liberarlo chiamando la funzione LocalFree .
[in, optional] pOptionalEntropy
Puntatore a una struttura DATA_BLOB che contiene una password o un'altra entropia aggiuntiva utilizzata quando i dati sono stati crittografati. Questo parametro può essere impostato su NULL; Tuttavia, se è stata usata una struttura di entropia facoltativa DATA_BLOB nella fase di crittografia, è necessario usare la stessa struttura DATA_BLOB per la fase di decrittografia. Per informazioni sulla protezione delle password, vedere Gestione delle password.
pvReserved
Questo parametro è riservato per uso futuro e deve essere impostato su NULL.
[in, optional] pPromptStruct
Puntatore a una struttura di CRYPTPROTECT_PROMPTSTRUCT che fornisce informazioni su dove e quando devono essere visualizzati i prompt e sul contenuto di tali richieste. Questo parametro può essere impostato su NULL.
[in] dwFlags
Valore DWORD che specifica le opzioni per questa funzione. Questo parametro può essere zero, nel qual caso non è impostata alcuna opzione o il flag seguente.
| Valore | Significato |
|---|---|
|
Questo flag viene usato per situazioni remote in cui l'interfaccia utente non è un'opzione. Quando questo flag viene impostato e l'interfaccia utente viene specificata per l'operazione di protezione o di rimozione della protezione, l'operazione ha esito negativo e GetLastError restituisce il codice ERROR_PASSWORD_RESTRICTION. |
|
Questo flag verifica la protezione di un BLOB protetto. Se il livello di protezione predefinito configurato dell'host è superiore al livello di protezione corrente per il BLOB, la funzione restituisce CRYPT_I_NEW_PROTECTION_REQUIRED per consigliare al chiamante di proteggere nuovamente il testo non crittografato contenuto nel BLOB. |
[out] pDataOut
Puntatore a una struttura DATA_BLOB in cui la funzione archivia i dati decrittografati. Al termine dell'uso della struttura DATA_BLOB , liberare il relativo membro pbData chiamando la funzione LocalFree .
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce TRUE.
Se la funzione ha esito negativo, restituisce FALSE.
Commenti
La funzione CryptProtectData crea una chiave di sessione quando i dati vengono crittografati. Tale chiave viene derivata di nuovo e usata per decrittografare il BLOB di dati.
L'hashmac (Message Authentication Code) aggiunto ai dati crittografati può essere usato per determinare se i dati crittografati sono stati modificati in qualsiasi modo. Qualsiasi manomissione restituisce la restituzione del codice ERROR_INVALID_DATA.
Al termine dell'uso della struttura DATA_BLOB , liberare il relativo membro pbData chiamando la funzione LocalFree . Qualsiasi ppszDataDescr che non è NULL deve essere liberato anche tramite LocalFree.
Al termine dell'uso delle informazioni riservate, cancellarlo dalla memoria chiamando la funzione SecureZeroMemory .
Esempio
Nell'esempio seguente viene illustrata la decrittografia dei dati crittografati in una struttura di DATA_BLOB . Questa funzione esegue la decrittografia usando una chiave di sessione creata dalla funzione usando le credenziali di accesso dell'utente. Per un altro esempio che usa questa funzione, vedere Esempio di programma C: Uso di 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!");
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | dpapi.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |