Fungsi CryptDeriveKey (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 CryptDeriveKey menghasilkan kunci sesi kriptografi yang berasal dari nilai data dasar. Fungsi ini menjamin bahwa ketika penyedia layanan kriptografi (CSP) dan algoritma yang sama digunakan, kunci yang dihasilkan dari data dasar yang sama identik. Data dasar dapat berupa kata sandi atau data pengguna lainnya.

Fungsi ini sama dengan CryptGenKey, kecuali bahwa kunci sesi yang dihasilkan berasal dari data dasar alih-alih acak. CryptDeriveKey hanya dapat digunakan untuk menghasilkan kunci sesi. Ini tidak dapat menghasilkan pasangan kunci publik/privat.

Handel ke kunci sesi dikembalikan dalam parameter phKey . Handel ini dapat digunakan dengan fungsi CryptoAPI apa pun yang memerlukan handel kunci.

Sintaks

BOOL CryptDeriveKey(
  [in]      HCRYPTPROV hProv,
  [in]      ALG_ID     Algid,
  [in]      HCRYPTHASH hBaseData,
  [in]      DWORD      dwFlags,
  [in, out] HCRYPTKEY  *phKey
);

Parameter

[in] hProv

Handel HCRYPTPROV dari CSP yang dibuat oleh panggilan ke CryptAcquireContext.

[in] Algid

Struktur ALG_ID yang mengidentifikasi algoritma enkripsi simetris yang kuncinya akan dihasilkan. Algoritma yang tersedia kemungkinan besar akan berbeda untuk setiap CSP. Untuk informasi selengkapnya tentang pengidentifikasi algoritma mana yang digunakan oleh penyedia yang berbeda untuk spesifikasi utama AT_KEYEXCHANGE dan AT_SIGNATURE, lihat ALG_ID.

Untuk informasi selengkapnya tentang nilai ALG_ID untuk digunakan dengan Penyedia Kriptografi Dasar Microsoft, lihat Algoritma Penyedia Dasar. Untuk informasi selengkapnya tentang nilai ALG_ID untuk digunakan dengan Penyedia Kriptografi Microsoft Strong atau Penyedia Kriptografi yang Ditingkatkan Microsoft, lihat Algoritma Penyedia yang Ditingkatkan.

[in] hBaseData

Handel ke objek hash yang telah diberi makan data dasar yang tepat.

Untuk mendapatkan handel ini, aplikasi harus terlebih dahulu membuat objek hash dengan CryptCreateHash dan kemudian menambahkan data dasar ke objek hash dengan CryptHashData. Proses ini dijelaskan secara rinci dalam Hash dan Tanda Tangan Digital.

[in] dwFlags

Menentukan jenis kunci yang dihasilkan.

Ukuran kunci sesi dapat diatur saat kunci dibuat. Ukuran kunci, yang mewakili panjang modulus kunci dalam bit, diatur dengan 16 bit atas parameter ini. Dengan demikian, jika kunci sesi RC4 128-bit akan dihasilkan, nilai 0x00800000 dikombinasikan dengan nilai dwFlags lain yang telah ditentukan sebelumnya dengan operasi bitwise-OR. Karena perubahan pembatasan kontrol ekspor, CSP default dan panjang kunci default dapat berubah di antara rilis sistem operasi. Penting bahwa enkripsi dan dekripsi menggunakan CSP yang sama dan bahwa panjang kunci secara eksplisit diatur menggunakan parameter dwFlags untuk memastikan interoperabilitas pada platform sistem operasi yang berbeda.

16 bit yang lebih rendah dari parameter ini bisa nol atau Anda dapat menentukan satu atau beberapa bendera berikut dengan menggunakan operator bitwise-OR untuk menggabungkannya.

Nilai	Makna
CRYPT_CREATE_SALT	Biasanya, ketika kunci sesi dibuat dari nilai hash , ada sejumlah bit sisa. Misalnya, jika nilai hash adalah 128 bit dan kunci sesi adalah 40 bit, akan ada 88 bit yang tersisa. Jika bendera ini diatur, maka kunci diberi nilai salt berdasarkan bit nilai hash yang tidak digunakan. Anda dapat mengambil nilai salt ini dengan menggunakan fungsi CryptGetKeyParam dengan parameter dwParam diatur ke KP_SALT. Jika bendera ini tidak diatur, maka kunci diberi nilai salt nol. Ketika kunci dengan nilai garam bukan nol diekspor (dengan menggunakan CryptExportKey), nilai garam juga harus diperoleh dan disimpan dengan BLOB kunci.
CRYPT_EXPORTABLE	Jika bendera ini diatur, kunci sesi dapat ditransfer keluar dari CSP ke blob kunci melalui fungsi CryptExportKey . Karena kunci umumnya harus dapat diekspor, bendera ini biasanya harus diatur. Jika bendera ini tidak diatur, maka kunci sesi tidak dapat diekspor. Ini berarti kunci hanya tersedia dalam sesi saat ini dan hanya aplikasi yang membuatnya yang dapat menggunakannya. Bendera ini tidak berlaku untuk pasangan kunci publik/privat.
CRYPT_NO_SALT	Bendera ini menentukan bahwa nilai tanpa garam dialokasikan untuk kunci simetris 40-bit. Untuk informasi selengkapnya, lihat Fungsionalitas Nilai Garam.
CRYPT_UPDATE_KEY	Beberapa CSP menggunakan kunci sesi yang berasal dari beberapa nilai hash. Jika demikian, CryptDeriveKey harus dipanggil beberapa kali. Jika bendera ini diatur, kunci sesi baru tidak dihasilkan. Sebaliknya, kunci yang ditentukan oleh phKey dimodifikasi. Perilaku tepat dari bendera ini tergantung pada jenis kunci yang dihasilkan dan pada CSP tertentu yang digunakan. Penyedia layanan kriptografi Microsoft mengabaikan bendera ini.
CRYPT_SERVER 1024 (0x400)	Bendera ini hanya digunakan dengan penyedia Schannel . Jika bendera ini diatur, kunci yang akan dihasilkan adalah kunci penulisan server; jika tidak, ini adalah kunci penulisan klien.

[in, out] phKey

Penunjuk ke variabel HCRYPTKEY untuk menerima alamat handel kunci yang baru dibuat. Setelah Anda selesai menggunakan kunci, lepaskan handel dengan memanggil fungsi CryptDestroyKey .

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).

Jika fungsi gagal, fungsi mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Kode kesalahan yang diawali oleh "NTE" dihasilkan oleh CSP tertentu yang digunakan. Beberapa kemungkinan kode kesalahan tercantum dalam tabel berikut.

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.
NTE_BAD_ALGID	Parameter Algid menentukan algoritma yang tidak didukung CSP ini.
NTE_BAD_FLAGS	Parameter dwFlags berisi nilai yang tidak valid.
NTE_BAD_HASH	Parameter hBaseData tidak berisi handel yang valid ke objek hash.
NTE_BAD_HASH_STATE	Upaya dilakukan untuk menambahkan data ke objek hash yang sudah ditandai "selesai."
NTE_BAD_UID	Parameter hProv tidak berisi handel konteks yang valid.
NTE_FAIL	Fungsi gagal dengan cara yang tidak terduga.
NTE_SILENT_CONTEXT	Penyedia tidak dapat melakukan tindakan karena konteks diperoleh sebagai senyap.

Keterangan

Ketika kunci dihasilkan untuk cipher blok simetris, kunci secara default diatur dalam mode rantai blok sandi (CBC) dengan vektor inisialisasi nol. Mode sandi ini menyediakan metode default yang baik untuk mengenkripsi data secara massal. Untuk mengubah parameter ini, gunakan fungsi CryptSetKeyParam .

Fungsi CryptDeriveKey menyelesaikan hash. Setelah CryptDeriveKey dipanggil, tidak ada lagi data yang dapat ditambahkan ke hash. Panggilan tambahan ke CryptHashData atau CryptHashSessionKey gagal. Setelah aplikasi selesai dengan hash, CryptDestroyHash harus dipanggil untuk menghancurkan objek hash.

Untuk memilih panjang kunci yang sesuai, metode berikut disarankan.

Untuk menghitung algoritma yang didukung CSP dan untuk mendapatkan panjang kunci maksimum dan minimum untuk setiap algoritma, panggil CryptGetProvParam dengan PP_ENUMALGS_EX.
Gunakan panjang minimum dan maksimum untuk memilih panjang kunci yang sesuai. Tidak selalu disarankan untuk memilih panjang maksimum karena ini dapat menyebabkan masalah performa.
Setelah panjang kunci yang diinginkan dipilih, gunakan 16 bit atas parameter dwFlags untuk menentukan panjang kunci.

Biarkan n menjadi panjang kunci turunan yang diperlukan, dalam byte. Kunci turunan adalah n byte pertama dari nilai hash setelah komputasi hash diselesaikan oleh CryptDeriveKey. Jika hash bukan anggota keluarga SHA-2 dan kunci yang diperlukan adalah untuk 3DES atau AES, kuncinya diturunkan sebagai berikut:

Bentuk buffer 64 byte dengan mengulangi konstanta 0x36 64 kali. Biarkan k menjadi panjang nilai hash yang diwakili oleh parameter input hBaseData. Atur byte k pertama buffer ke hasil operasi XOR dari byte k pertama buffer dengan nilai hash yang diwakili oleh parameter input hBaseData.
Bentuk buffer 64 byte dengan mengulangi konstanta 0x5C 64 kali. Atur byte k pertama buffer ke hasil operasi XOR dari byte k pertama buffer dengan nilai hash yang diwakili oleh parameter input hBaseData.
Hash hasil langkah 1 dengan menggunakan algoritma hash yang sama seperti yang digunakan untuk menghitung nilai hash yang diwakili oleh parameter hBaseData .
Hash hasil langkah 2 dengan menggunakan algoritma hash yang sama seperti yang digunakan untuk menghitung nilai hash yang diwakili oleh parameter hBaseData .
Menggabungkan hasil langkah 3 dengan hasil langkah 4.
Gunakan n byte pertama dari hasil langkah 5 sebagai kunci turunan.

Penyedia Layanan Kriptografi Penuh RSA default adalah Penyedia Kriptografi Kuat Microsoft RSA. Penyedia Layanan Kriptografi Diffie-Hellman Tanda Tangan DSS default adalah Penyedia Kriptografi Diffie-Hellman Microsoft Enhanced DSS. Masing-masing CSP ini memiliki panjang kunci simetris default 128-bit untuk RC2 dan RC4.

Tabel berikut mencantumkan panjang kunci minimum, default, dan maksimum untuk kunci sesi menurut algoritma dan penyedia.

Penyedia	Algoritma	Panjang kunci minimum	Panjang kunci default	Panjang kunci maksimum
Basis MS	RC4 dan RC2	40	40	56
Basis MS	DES	56	56	56
MS Ditingkatkan	RC4 dan RC2	40	128	128
MS Ditingkatkan	DES	56	56	56
MS Ditingkatkan	3DES 112	112	112	112
MS Ditingkatkan	3DES	168	168	168
MS Strong	RC4 dan RC2	40	128	128
MS Strong	DES	56	56	56
MS Strong	3DES 112	112	112	112
MS Strong	3DES	168	168	168
Basis DSS/DH	RC4 dan RC2	40	40	56
Basis DSS/DH	Cylink MEK	40	40	40
Basis DSS/DH	DES	56	56	56
DSS/DH Enh	RC4 dan RC2	40	128	128
DSS/DH Enh	Cylink MEK	40	40	40
DSS/DH Enh	DES	56	56	56
DSS/DH Enh	3DES 112	112	112	112
DSS/DH Enh	3DES	168	168	168

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Mendapatkan Kunci Sesi dari Kata Sandi.

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