Funzione CryptUnprotectData (dpapi.h)

Articolo
02/26/2024

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
CRYPTPROTECT_UI_FORBIDDEN	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.
CRYPTPROTECT_VERIFY_PROTECTION	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'hash mac (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