Fungsi CryptSignHashA (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 CryptSignHash menandatangani data. Karena semua algoritma tanda tangan asimetris dan dengan demikian lambat, CryptoAPI tidak memungkinkan data untuk ditandatangani secara langsung. Sebaliknya, data pertama kali di-hash, dan CryptSignHash digunakan untuk menandatangani hash.

Sintaks

BOOL CryptSignHashA(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCSTR     szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

Parameter

[in] hHash

Menangani objek hash yang akan ditandatangani.

[in] dwKeySpec

Mengidentifikasi kunci privat yang akan digunakan dari kontainer penyedia. Ini bisa AT_KEYEXCHANGE atau AT_SIGNATURE.

Algoritma tanda tangan yang digunakan ditentukan ketika pasangan kunci awalnya dibuat.

Satu-satunya algoritma tanda tangan yang didukung Penyedia Kriptografi Dasar Microsoft adalah algoritma Kunci Umum RSA.

[in] szDescription

Parameter ini tidak lagi digunakan dan harus diatur ke NULL untuk mencegah kerentanan keamanan. Namun, ini masih didukung untuk kompatibilitas mundur di Penyedia Kriptografi Dasar Microsoft.

[in] dwFlags

Nilai bendera berikut ditentukan.

Nilai	Makna
CRYPT_NOHASHOID 0x00000001	Digunakan dengan penyedia RSA. Pengidentifikasi objek hash (OID) tidak ditempatkan di enkripsi kunci publik RSA. Jika bendera ini tidak diatur, hash OID dalam tanda tangan default adalah seperti yang ditentukan dalam definisi DigestInfo di PKCS #1.
CRYPT_TYPE2_FORMAT 0x00000002	Bendera ini tidak digunakan.
CRYPT_X931_FORMAT 0x00000004	Gunakan metode padding tanda tangan RSA yang ditentukan dalam standar ANSI X9.31.

[out] pbSignature

Penunjuk ke buffer yang menerima data tanda tangan.

Parameter ini dapat berupa NULL untuk mengatur ukuran buffer untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.

[in, out] pdwSigLen

Penunjuk ke nilai DWORD yang menentukan ukuran, dalam byte, dari buffer pbSignature . Saat fungsi kembali, nilai DWORD berisi jumlah byte yang disimpan dalam buffer.

Catatan Saat memproses data yang dikembalikan dalam buffer, aplikasi harus menggunakan ukuran aktual data yang dikembalikan. Ukuran aktual bisa sedikit lebih kecil dari ukuran buffer yang ditentukan pada input. (Pada input, ukuran buffer biasanya ditentukan cukup besar untuk memastikan bahwa data output terbesar yang mungkin cocok di buffer.) Pada output, variabel yang diacu oleh parameter ini diperbarui untuk mencerminkan ukuran aktual data yang disalin ke buffer.

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. Beberapa kemungkinan kode kesalahan mengikuti.

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_MORE_DATA	Buffer yang ditentukan oleh parameter pbSignature tidak cukup besar untuk menyimpan data yang dikembalikan. Ukuran buffer yang diperlukan, dalam byte, berada dalam nilai DWORDpdwSigLen.
NTE_BAD_ALGID	Handel hHash menentukan algoritma yang tidak didukung CSP ini, atau parameter dwKeySpec memiliki nilai yang salah.
NTE_BAD_FLAGS	Parameter dwFlags bukan nol.
NTE_BAD_HASH	Objek hash yang ditentukan oleh parameter hHash tidak valid.
NTE_BAD_UID	Konteks CSP yang ditentukan ketika objek hash dibuat tidak dapat ditemukan.
NTE_NO_KEY	Kunci privat yang ditentukan oleh dwKeySpec tidak ada.
NTE_NO_MEMORY	CSP kehabisan memori selama operasi.

Keterangan

Sebelum memanggil fungsi ini, fungsi CryptCreateHash harus dipanggil untuk mendapatkan handel ke objek hash. Fungsi CryptHashData atau CryptHashSessionKey kemudian digunakan untuk menambahkan kunci data atau sesi ke objek hash. Fungsi CryptSignHash menyelesaikan hash.

Sementara DSS CSP mendukung hash dengan algoritma hash MD5 dan SHA, DSS CSP hanya mendukung hash SHA penandatanganan.

Setelah fungsi ini dipanggil, tidak ada lagi data yang dapat ditambahkan ke hash. Panggilan tambahan ke CryptHashData atau CryptHashSessionKey gagal.

Setelah aplikasi selesai menggunakan hash, hancurkan objek hash dengan memanggil fungsi CryptDestroyHash .

Secara default, penyedia Microsoft RSA menggunakan metode padding PKCS #1 untuk tanda tangan. OID hash dalam elemen DigestInfo dari tanda tangan secara otomatis diatur ke OID algoritma yang terkait dengan objek hash. Menggunakan bendera CRYPT_NOHASHOID akan menyebabkan OID ini dihilangkan dari tanda tangan.

Terkadang, nilai hash yang telah dihasilkan di tempat lain harus ditandatangani. Ini dapat dilakukan dengan menggunakan urutan operasi berikut:

Buat objek hash dengan menggunakan CryptCreateHash.
Atur nilai hash dalam objek hash dengan menggunakan nilai HP_HASHVAL parameter dwParam di CryptSetHashParam.
Tanda tangani nilai hash dengan menggunakan CryptSignHash dan dapatkan blok tanda tangan digital.
Hancurkan objek hash dengan menggunakan CryptDestroyHash.

Contoh

Contoh berikut menunjukkan penandatanganan data dengan terlebih dahulu hashing data yang akan ditandatangani lalu menandatangani hash dengan menggunakan fungsi CryptSignHash .

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

Untuk contoh lengkap termasuk konteks untuk kode ini, lihat Contoh Program C: Menandatangani Hash dan Memverifikasi Tanda Tangan Hash.

Catatan

Header wincrypt.h mendefinisikan CryptSignHash sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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