Fungsi CryptUnprotectData (dpapi.h)

Artikel
08/23/2023

Fungsi CryptUnprotectData mendekripsi dan melakukan pemeriksaan integritas data dalam struktur DATA_BLOB . Biasanya, satu-satunya pengguna yang dapat mendekripsi data adalah pengguna dengan kredensial masuk yang sama dengan pengguna yang mengenkripsi data. Selain itu, enkripsi dan dekripsi harus dilakukan pada komputer yang sama. Untuk informasi tentang pengecualian, lihat bagian Keterangan dari CryptProtectData.

Sintaks

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

Penunjuk ke struktur DATA_BLOB yang menyimpan data terenkripsi. Anggota cbData struktur DATA_BLOB memegang panjang string byte anggota pbData yang berisi teks yang akan dienkripsi.

[out, optional] ppszDataDescr

Penunjuk ke deskripsi data terenkripsi yang dapat dibaca string yang disertakan dengan data terenkripsi. Parameter ini dapat diatur ke NULL. Setelah Anda selesai menggunakan ppszDataDescr, bebaskan dengan memanggil fungsi LocalFree .

[in, optional] pOptionalEntropy

Penunjuk ke struktur DATA_BLOB yang berisi kata sandi atau entropi tambahan lainnya yang digunakan saat data dienkripsi. Parameter ini dapat diatur ke NULL; namun, jika entropi opsional DATA_BLOB struktur digunakan dalam fase enkripsi, struktur DATA_BLOB yang sama harus digunakan untuk fase dekripsi. Untuk informasi tentang melindungi kata sandi, lihat Menangani Kata Sandi.

pvReserved

Parameter ini dicadangkan untuk digunakan di masa mendatang dan harus diatur ke NULL.

[in, optional] pPromptStruct

Penunjuk ke struktur CRYPTPROTECT_PROMPTSTRUCT yang menyediakan informasi tentang di mana dan kapan perintah akan ditampilkan dan apa konten perintah tersebut. Parameter ini dapat diatur ke NULL.

[in] dwFlags

Nilai DWORD yang menentukan opsi untuk fungsi ini. Parameter ini bisa nol, dalam hal ini tidak ada opsi yang diatur, atau bendera berikut.

Nilai	Makna
CRYPTPROTECT_UI_FORBIDDEN	Bendera ini digunakan untuk situasi jarak jauh di mana antarmuka pengguna (UI) bukan pilihan. Ketika bendera ini diatur dan UI ditentukan untuk operasi lindungi atau buka proteksi, operasi gagal dan GetLastError mengembalikan kode ERROR_PASSWORD_RESTRICTION.
CRYPTPROTECT_VERIFY_PROTECTION	Bendera ini memverifikasi perlindungan BLOB yang dilindungi. Jika tingkat perlindungan default yang dikonfigurasi host lebih tinggi dari tingkat perlindungan saat ini untuk BLOB, fungsi mengembalikan CRYPT_I_NEW_PROTECTION_REQUIRED untuk menyarankan pemanggil untuk kembali melindungi teks biasa yang terkandung dalam BLOB.

[out] pDataOut

Penunjuk ke struktur DATA_BLOB tempat fungsi menyimpan data yang didekripsi. Setelah Anda selesai menggunakan struktur DATA_BLOB , bebaskan anggota pbData-nya dengan memanggil fungsi LocalFree .

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan TRUE.

Jika fungsi gagal, fungsi akan mengembalikan FALSE.

Keterangan

Fungsi CryptProtectData membuat kunci sesi saat data dienkripsi. Kunci itu diturunkan lagi dan digunakan untuk mendekripsi BLOB data.

Hash Kode Autentikasi Pesan (MAC) yang ditambahkan ke data terenkripsi dapat digunakan untuk menentukan apakah data terenkripsi diubah dengan cara apa pun. Setiap perubahan menghasilkan pengembalian kode ERROR_INVALID_DATA.

Setelah Anda selesai menggunakan struktur DATA_BLOB , bebaskan anggota pbData-nya dengan memanggil fungsi LocalFree . Setiap ppszDataDescr yang bukan NULL juga harus dibebaskan dengan menggunakan LocalFree.

Setelah Anda selesai menggunakan informasi sensitif, bersihkan dari memori dengan memanggil fungsi SecureZeroMemory .

Contoh

Contoh berikut menunjukkan dekripsi data terenkripsi dalam struktur DATA_BLOB . Fungsi ini melakukan dekripsi dengan menggunakan kunci sesi yang dibuat fungsi dengan menggunakan kredensial masuk pengguna. Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Menggunakan 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!");
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	dpapi.h
Pustaka	Crypt32.lib
DLL	Crypt32.dll