Fungsi CryptSetKeyParam (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 CryptSetKeyParam menyesuaikan berbagai aspek operasi kunci sesi. Nilai yang ditetapkan oleh fungsi ini tidak bertahan ke memori dan hanya dapat digunakan dalam satu sesi.

Penyedia Kriptografi Dasar Microsoft tidak mengizinkan pengaturan nilai untuk pertukaran kunci atau kunci tanda tangan; namun, penyedia kustom dapat menentukan nilai yang dapat diatur untuk kuncinya.

Sintaks

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parameter

[in] hKey

Handel ke kunci yang nilainya akan diatur.

[in] dwParam

Tabel berikut berisi nilai yang telah ditentukan sebelumnya yang bisa digunakan.

Untuk semua jenis kunci, parameter ini dapat berisi salah satu nilai berikut.

Nilai	Makna
KP_ALGID	pbData menunjuk ke ALG_ID yang sesuai. Ini digunakan saat bertukar kunci sesi dengan Microsoft Base Digital Signature Standard (DSS), Diffie-Hellman Penyedia Kriptografi, atau CSP yang kompatibel. Setelah kunci disepakati dengan fungsi CryptImportKey , kunci sesi diaktifkan untuk digunakan dengan mengatur jenis algoritmanya.
KP_CERTIFICATE	pbData adalah alamat buffer yang berisi sertifikat X.509 yang telah dikodekan dengan menggunakan Distinguished Encoding Rules (DER). Kunci publik dalam sertifikat harus cocok dengan tanda tangan atau kunci pertukaran yang sesuai.
KP_PERMISSIONS	pbData menunjuk ke nilai DWORD yang menentukan nol atau beberapa bendera izin. Untuk deskripsi bendera ini, lihat CryptGetKeyParam.
KP_SALT	pbData menunjuk ke array BYTE yang menentukan nilai salt baru untuk dijadikan bagian dari kunci sesi. Ukuran nilai garam bervariasi tergantung pada CSP yang digunakan. Sebelum mengatur nilai ini, tentukan ukuran nilai salt dengan memanggil fungsi CryptGetKeyParam . Nilai salt digunakan untuk membuat kunci sesi lebih unik, yang membuat serangan kamus lebih sulit. Nilai garam adalah nol secara default untuk Penyedia Kriptografi Dasar Microsoft.
KP_SALT_EX	pbData menunjuk ke struktur CRYPT_INTEGER_BLOB yang berisi garam. Untuk informasi selengkapnya, lihat Menentukan Nilai Salt.

Jika kunci Digital Signature Standard (DSS) ditentukan oleh parameter hKey , nilai dwParam juga dapat diatur ke salah satu nilai berikut.

Nilai	Makna
KP_G	pbData menunjuk ke generator G dari BLOB kunci DSS. Data dalam bentuk struktur CRYPT_INTEGER_BLOB , di mana anggota pbData adalah nilai, dan anggota cbData adalah panjang nilai. Nilai diharapkan tanpa informasi header dan dalam bentuk little-endian .
KP_P	pbData menunjuk ke modulus utama P dari BLOB kunci DSS. Data dalam bentuk struktur CRYPT_INTEGER_BLOB . Anggota pbData adalah nilai, dan anggota cbData adalah panjang nilai. Nilai diharapkan tanpa informasi header dan dalam bentuk little-endian .
KP_Q	pbData menunjuk ke Q utama dari BLOB kunci DSS. Data dalam bentuk struktur CRYPT_INTEGER_BLOB di mana anggota pbData adalah nilai, dan anggota cbData adalah panjang nilai. Nilai diharapkan tanpa informasi header dan dalam bentuk little-endian .
KP_X	Setelah nilai P, Q, dan G ditetapkan, panggilan yang menentukan nilai KP_X untuk dwParam dan NULL untuk parameter pbData dapat dilakukan ke fungsi CryptSetKeyParam . Hal ini menyebabkan nilai X dan Y dihasilkan.

Jika algoritma Diffie-Hellman atau kunci Digital Signature Algorithm (DSA) ditentukan oleh hKey, nilai dwParam juga dapat diatur ke salah satu nilai berikut.

Nilai	Makna
KP_CMS_DH_KEY_INFO	Mengatur informasi untuk kunci Diffie-Hellman yang diimpor. Parameter pbData adalah alamat struktur CMS_DH_KEY_INFO yang berisi informasi utama yang akan diatur.
KP_PUB_PARAMS	Mengatur parameter publik (P, Q, G, dan sebagainya) dari kunci DSS atau Diffie-Hellman. Handel kunci untuk kunci ini harus dalam status PREGEN, yang dihasilkan dengan bendera CRYPT_PREGEN. Parameter pbData harus menjadi penunjuk ke struktur DATA_BLOB di mana data dalam struktur ini adalah BLOB DHPUBKEY_VER3 atau DSSPUBKEY_VER3. Fungsi menyalin parameter publik dari struktur CRYPT_INTEGER_BLOB ini ke handel kunci. Setelah panggilan ini dilakukan, nilai parameter KP_X harus digunakan dengan CryptSetKeyParam untuk membuat kunci privat yang sebenarnya. Parameter KP_PUB_PARAMS digunakan sebagai satu panggilan daripada beberapa panggilan dengan nilai parameter KP_P, KP_Q, dan KP_G.

Nilai

Makna

KP_CMS_DH_KEY_INFO

Mengatur informasi untuk kunci Diffie-Hellman yang diimpor. Parameter pbData adalah alamat struktur CMS_DH_KEY_INFO yang berisi informasi utama yang akan diatur.

KP_PUB_PARAMS

Mengatur parameter publik (P, Q, G, dan sebagainya) dari kunci DSS atau Diffie-Hellman. Handel kunci untuk kunci ini harus dalam status PREGEN, yang dihasilkan dengan bendera CRYPT_PREGEN. Parameter pbData harus menjadi penunjuk ke struktur DATA_BLOB di mana data dalam struktur ini adalah BLOB DHPUBKEY_VER3 atau DSSPUBKEY_VER3. Fungsi menyalin parameter publik dari struktur CRYPT_INTEGER_BLOB ini ke handel kunci. Setelah panggilan ini dilakukan, nilai parameter KP_X harus digunakan dengan CryptSetKeyParam untuk membuat kunci privat yang sebenarnya. Parameter KP_PUB_PARAMS digunakan sebagai satu panggilan daripada beberapa panggilan dengan nilai parameter KP_P, KP_Q, dan KP_G.

Jika kunci sesi cipher blok ditentukan oleh parameter hKey, nilai dwParam juga dapat diatur ke salah satu nilai berikut.

Nilai	Makna
KP_EFFECTIVE_KEYLEN	Jenis nilai ini hanya dapat digunakan dengan kunci RC2 dan telah ditambahkan karena implementasi fungsi CryptSetKeyParam di Microsoft Enhanced Cryptographic Provider sebelum Windows 2000. Dalam implementasi sebelumnya, kunci RC2 di Enhanced Provider memiliki kekuatan 128 bit, tetapi panjang kunci efektif yang digunakan untuk memperluas kunci ke dalam tabel kunci hanya 40 bit. Ini mengurangi kekuatan algoritma menjadi 40 bit. Untuk menjaga kompatibilitas mundur, implementasi sebelumnya akan tetap apa adanya. Namun, panjang kunci yang efektif dapat diatur menjadi lebih besar dari 40 bit dengan menggunakan KP_EFFECTIVE_KEYLEN dalam panggilan CryptSetKeyParam . Panjang kunci yang efektif diteruskan dalam parameter pbData sebagai penunjuk ke nilai DWORD dengan nilai panjang kunci yang efektif. Panjang kunci efektif minimum pada Penyedia Kriptografi Dasar Microsoft adalah satu, dan maksimumnya adalah 40. Di Penyedia Kriptografi yang Ditingkatkan Microsoft, minimumnya adalah satu dan maksimumnya adalah 1.024. Panjang kunci harus diatur sebelum mengenkripsi atau mendekripsi dengan kunci.
KP_HIGHEST_VERSION	Mengatur versi Keamanan Lapisan Transportasi (TLS) tertinggi yang diizinkan. Properti ini hanya berlaku untuk kunci SSL dan TLS. Parameter pbData adalah alamat variabel DWORD yang berisi nomor versi TLS tertinggi yang didukung.
KP_IV	pbData menunjuk ke array BYTE yang menentukan vektor inisialisasi. Array ini harus berisi elemen BlockLength/8. Misalnya, jika panjang blok adalah 64 bit, vektor inisialisasi terdiri dari 8 byte. Vektor inisialisasi diatur ke nol secara default untuk Penyedia Kriptografi Dasar Microsoft.
KP_KEYVAL	Atur nilai kunci untuk kunci Standar Enkripsi Data (DES). Parameter pbData adalah alamat buffer yang berisi kunci. Buffer ini harus memiliki panjang yang sama dengan kunci. Properti ini hanya berlaku untuk kunci DES.
KP_PADDING	Atur mode padding. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima pengidentifikasi numerik yang mengidentifikasi metode padding yang digunakan oleh cipher. Ini bisa menjadi salah satu nilai berikut. PKCS5_PADDING Menentukan metode padding PKCS 5 (detik 6,2). RANDOM_PADDING Padding menggunakan angka acak. Metode padding ini tidak didukung oleh CSP yang disediakan Microsoft. ZERO_PADDING Padding menggunakan nol. Metode padding ini tidak didukung oleh CSP yang disediakan Microsoft.
KP_MODE	pbData menunjuk ke nilai DWORD yang menentukan mode sandi yang akan digunakan. Untuk daftar mode cipher yang ditentukan, lihat CryptGetKeyParam. Mode sandi diatur ke CRYPT_MODE_CBC secara default untuk Penyedia Kriptografi Dasar Microsoft.
KP_MODE_BITS	pbData menunjuk ke nilai DWORD yang menunjukkan jumlah bit yang diproses per siklus ketika mode sandi Umpan Balik Output (OFB) atau Cipher Feedback (CFB) digunakan. Jumlah bit yang diproses per siklus diatur ke 8 secara default untuk Penyedia Kriptografi Dasar Microsoft.

Jika kunci RSA ditentukan dalam parameter hKey , nilai parameter dwParam dapat menjadi nilai berikut.

Nilai	Makna
KP_OAEP_PARAMS	Atur parameter Optimal Asymmetric Encryption Padding (OAEP) (PKCS #1 versi 2) untuk kunci tersebut. Parameter pbData adalah alamat struktur CRYPT_DATA_BLOB yang berisi label OAEP. Properti ini hanya berlaku untuk kunci RSA.

Perhatikan bahwa nilai berikut ini tidak digunakan:

KP_ADMIN_PIN
KP_CMS_KEY_INFO
KP_INFO
KP_KEYEXCHANGE_PIN
KP_PRECOMP_MD5
KP_PRECOMP_SHA
KP_PREHASH
KP_PUB_EX_LEN
KP_PUB_EX_VAL
KP_RA
KP_RB
KP_ROUNDS
KP_RP
KP_SIGNATURE_PIN
KP_Y

[in] pbData

Penunjuk ke buffer yang diinisialisasi dengan nilai yang akan diatur sebelum memanggil CryptSetKeyParam. Bentuk data ini bervariasi tergantung pada nilai dwParam.

[in] dwFlags

Hanya digunakan saat dwParam KP_ALGID. Parameter dwFlags digunakan untuk meneruskan nilai bendera untuk kunci yang diaktifkan. Parameter dwFlags dapat menyimpan nilai seperti ukuran kunci dan nilai bendera lainnya yang diizinkan saat menghasilkan jenis kunci yang sama dengan CryptGenKey. Untuk informasi tentang nilai bendera yang diizinkan, lihat CryptGenKey.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah 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 mengikuti.

Menampilkan kode	Deskripsi
ERROR_BUSY	Konteks CSP saat ini sedang digunakan oleh proses lain.
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_FLAGS	Parameter dwFlags bukan nol, atau buffer pbData berisi nilai yang tidak valid.
NTE_BAD_TYPE	Parameter dwParam menentukan parameter yang tidak diketahui.
NTE_BAD_UID	Konteks CSP yang ditentukan ketika kunci hKey dibuat tidak dapat ditemukan.
NTE_FAIL	Fungsi gagal dengan cara yang tidak terduga.
NTE_FIXEDPARAMETER	Beberapa CSP memiliki nilai P, Q, dan G yang dikodekan secara permanen. Jika demikian, maka menggunakan KP_P, KP_Q, dan KP_G untuk nilai dwParam menyebabkan kesalahan ini.

Keterangan

Jika parameter KP_Q, KP_P, atau KP_X diatur pada kunci PREGEN Diffie-Hellman atau DSS, panjang kunci harus kompatibel dengan panjang kunci yang diatur menggunakan 16 bit atas parameter dwFlags saat kunci dibuat menggunakan CryptGenKey. Jika tidak ada panjang kunci yang diatur dalam CryptGenKey, panjang kunci default digunakan. Ini akan membuat kesalahan jika panjang kunci nondefault digunakan untuk mengatur P, Q, atau X.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Menduplikasi Kunci Sesi. Untuk kode lainnya yang menggunakan fungsi ini, lihat Contoh Program C: Mengatur dan Mendapatkan Parameter Kunci Sesi .

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