Fungsi CryptProtectData (dpapi.h)

  • Artikel

Fungsi CryptProtectData melakukan enkripsi pada data dalam struktur DATA_BLOB . Biasanya, hanya pengguna dengan kredensial masuk yang sama dengan pengguna yang mengenkripsi data yang dapat mendekripsi data. Selain itu, enkripsi dan dekripsi biasanya harus dilakukan pada komputer yang sama. Untuk informasi tentang pengecualian, lihat Keterangan.

Sintaks

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

Penunjuk ke struktur DATA_BLOB yang berisi teks biasa yang akan dienkripsi.

[in, optional] szDataDescr

String dengan deskripsi data yang dapat dibaca untuk dienkripsi. String deskripsi ini disertakan dengan data terenkripsi. Parameter ini bersifat opsional dan dapat diatur ke NULL.

[in, optional] pOptionalEntropy

Penunjuk ke struktur DATA_BLOB yang berisi kata sandi atau entropi tambahan lainnya yang digunakan untuk mengenkripsi data. Struktur DATA_BLOB yang digunakan dalam fase enkripsi juga harus digunakan dalam fase dekripsi. Parameter ini dapat diatur ke NULL tanpa entropi tambahan. Untuk informasi tentang melindungi kata sandi, lihat Menangani Kata Sandi.

[in] pvReserved

Dicadangkan untuk penggunaan 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 dalam fase enkripsi dan dekripsi.

[in] dwFlags

Parameter ini bisa menjadi salah satu bendera berikut.

Nilai Makna
CRYPTPROTECT_LOCAL_MACHINE
 Ketika bendera ini diatur, bendera ini mengaitkan data yang dienkripsi dengan komputer saat ini alih-alih dengan pengguna individual. Setiap pengguna di komputer tempat CryptProtectData dipanggil dapat menggunakan CryptUnprotectData untuk mendekripsi data.
CRYPTPROTECT_UI_FORBIDDEN
 Bendera ini digunakan untuk situasi jarak jauh di mana menyajikan antarmuka pengguna (UI) bukanlah pilihan. Ketika bendera ini diatur dan UI ditentukan untuk operasi lindungi atau tidak terlindungi, operasi gagal dan GetLastError mengembalikan kode ERROR_PASSWORD_RESTRICTION.
CRYPTPROTECT_AUDIT
 Bendera ini menghasilkan audit tentang operasi perlindungan dan pembatalan perlindungan. Entri log audit dicatat hanya jika szDataDescr bukan NULL dan tidak kosong.

[out] pDataOut

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

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan TRUE.

Jika fungsi gagal, fungsi akan mengembalikan FALSE. Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Biasanya, hanya pengguna dengan kredensial masuk yang cocok dengan pengguna yang mengenkripsi data yang dapat mendekripsi data. Selain itu, dekripsi biasanya hanya dapat dilakukan di komputer tempat data dienkripsi. Namun, pengguna dengan profil roaming dapat mendekripsi data dari komputer lain di jaringan.

Jika bendera CRYPTPROTECT_LOCAL_MACHINE diatur saat data dienkripsi, setiap pengguna di komputer tempat enkripsi dilakukan dapat mendekripsi data.

Fungsi ini membuat kunci sesi untuk melakukan enkripsi. Kunci sesi diturunkan lagi ketika data akan didekripsi.

Fungsi ini juga menambahkan Kode Autentikasi Pesan (MAC) (pemeriksaan integritas kunci) ke data terenkripsi untuk melindungi dari perubahan data.

Untuk mengenkripsi memori untuk penggunaan sementara dalam proses yang sama atau di seluruh proses, panggil fungsi CryptProtectMemory .

Contoh

Contoh berikut menunjukkan enkripsi data dalam struktur DATA_BLOB . Fungsi CryptProtectData melakukan enkripsi 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.

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

Persyaratan

   
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

Lihat juga

CryptProtectMemory

CryptUnprotectData

Fungsi Enkripsi dan Dekripsi Data

LocalFree