Fungsi CryptCreateHash (wincrypt.h)

Artikel
08/27/2023

Penting API ini tidak digunakan lagi. Perangkat lunak baru dan yang sudah ada harus mulai menggunakan Cryptography Next Generation API. Microsoft dapat menghapus API ini dalam rilis mendatang.

Fungsi CryptCreateHash memulai hashing aliran data. Ini membuat dan kembali ke aplikasi panggilan handel ke objek hash penyedia layanan kriptografi (CSP). Handel ini digunakan dalam panggilan berikutnya ke CryptHashData dan CryptHashSessionKey untuk hash kunci sesi dan aliran data lainnya.

Sintaks

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parameter

[in] hProv

Handel ke CSP yang dibuat oleh panggilan ke CryptAcquireContext.

[in] Algid

Nilai ALG_ID yang mengidentifikasi algoritma hash untuk digunakan.

Nilai yang valid untuk parameter ini bervariasi, tergantung pada CSP yang digunakan. Untuk daftar algoritma default, lihat Keterangan.

[in] hKey

Jika jenis algoritma hash adalah hash kunci, seperti algoritma Kode Autentikasi Pesan Berbasis Hash (HMAC) atau Kode Autentikasi Pesan (MAC), kunci untuk hash diteruskan dalam parameter ini. Untuk algoritma yang tidak di-kunci, parameter ini harus diatur ke nol.

Untuk algoritma kunci, kuncinya harus ke kunci cipher blok , seperti RC2, yang memiliki mode sandi Cipher Block Chaining (CBC).

[in] dwFlags

Nilai bendera berikut ditentukan.

Nilai	Makna
CRYPT_SECRETDIGEST 0x00000001	Bendera ini tidak digunakan.

[out] phHash

Alamat tempat fungsi menyalin handel ke objek hash baru. Setelah Anda selesai menggunakan objek hash, lepaskan handel dengan memanggil fungsi CryptDestroyHash .

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan TRUE.

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

Kode kesalahan yang diawali oleh NTE dihasilkan oleh CSP tertentu yang Anda gunakan. Tabel berikut ini memperlihatkan beberapa kemungkinan kode kesalahan.

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Salah satu parameter menentukan handel yang tidak valid.
ERROR_INVALID_PARAMETER	Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid.
ERROR_NOT_ENOUGH_MEMORY	Sistem operasi kehabisan memori selama operasi.
NTE_BAD_ALGID	Parameter Algid menentukan algoritma yang tidak didukung CSP ini.
NTE_BAD_FLAGS	Parameter dwFlags bukan nol.
NTE_BAD_KEY	Algoritma hash berkunci, seperti CALG_MAC, ditentukan oleh Algid, dan parameter hKey adalah nol atau menentukan handel kunci yang tidak valid. Kode kesalahan ini juga dikembalikan jika kuncinya adalah ke cipher aliran atau jika mode cipher adalah apa pun selain CBC.
NTE_NO_MEMORY	CSP kehabisan memori selama operasi.

Keterangan

Untuk daftar penyedia layanan Microsoft dan algoritma yang mereka terapkan, lihat Penyedia Layanan Kriptografi Microsoft.

Komputasi hash aktual dilakukan dengan fungsi CryptHashData dan CryptHashSessionKey . Ini memerlukan handel ke objek hash. Setelah semua data ditambahkan ke objek hash, salah satu operasi berikut dapat dilakukan:

Nilai hash dapat diambil dengan menggunakan CryptGetHashParam.
Kunci sesi dapat diturunkan dengan menggunakan CryptDeriveKey.
Hash dapat ditandatangani dengan menggunakan CryptSignHash.
Tanda tangan dapat diverifikasi dengan menggunakan CryptVerifySignature.

Setelah salah satu fungsi dari daftar ini dipanggil, CryptHashData dan CryptHashSessionKey tidak dapat dipanggil.

Contoh

Contoh berikut menunjukkan memulai hashing aliran data. Ini membuat dan kembali ke aplikasi panggilan handel ke objek hash. Handel ini digunakan dalam panggilan berikutnya ke CryptHashData dan CryptHashSessionKey untuk hash aliran data apa pun. Untuk contoh yang menyertakan konteks lengkap untuk contoh ini, lihat Contoh Program C: Membuat dan Hashing Kunci Sesi. Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Menandatangani Hash dan Memverifikasi Tanda Tangan Hash.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincrypt.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll