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 Microsoft Base tidak mengizinkan pengaturan nilai untuk pertukaran kunci atau kunci tanda tangan; namun, penyedia kustom dapat menentukan nilai yang dapat diatur untuk kuncinya.
Sintaksis
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 dapat digunakan.
Untuk semua jenis kunci, parameter ini dapat berisi salah satu nilai berikut.
| Nilai |
Arti |
-
KP_ALGID
|
pbData menunjuk ke ALG_IDyang 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 lebih bendera izin. Untuk deskripsi bendera ini, lihat CryptGetKeyParam.
|
-
KP_SALT
|
pbData menunjuk ke array BYTE yang menentukan nilai garam baru untuk dijadikan bagian dari kunci sesi. Ukuran nilai garam bervariasi tergantung pada CSP yang digunakan. Sebelum mengatur nilai ini, tentukan ukuran nilai garam dengan memanggil fungsi CryptGetKeyParam. Nilai garam 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 Garam.
|
Jika kunci Standar Tanda Tangan Digital (DSS) ditentukan oleh parameter hKey, nilai dwParam juga dapat diatur ke salah satu nilai berikut.
| Nilai |
Arti |
-
KP_G
|
pbData menunjuk ke generator G dariBLOB kunci DSS . Data dalam bentuk struktur CRYPT_INTEGER_BLOB, di mana anggota pbData adalah nilainya, 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 nilainya, dan anggota cbData adalah panjang nilai. Nilai diharapkan tanpa informasi header dan dalam bentuk little-endian .
|
-
KP_Q
|
pbData menunjuk ke Q utama BLOB kunci DSS. Data dalam bentuk struktur CRYPT_INTEGER_BLOB di mana anggota pbData adalah nilainya, 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. Ini menyebabkan nilai X dan Y dihasilkan.
|
Jika kunci algoritma Diffie-Hellman atau Digital Signature Algorithm (DSA) ditentukan oleh hKey, nilai dwParam juga dapat diatur ke salah satu nilai berikut.
| Nilai |
Arti |
-
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 sesisandi blok ditentukan oleh parameter hKey, nilai dwParam juga dapat diatur ke salah satu nilai berikut.
| Nilai |
Arti |
-
KP_EFFECTIVE_KEYLEN
|
Jenis nilai ini hanya dapat digunakan dengan kunci RC2 dan telah ditambahkan karena implementasi fungsi CryptSetKeyParam di Penyedia Kriptografi Yang Ditingkatkan Microsoft sebelum Windows 2000. Dalam implementasi sebelumnya, kunci RC2 di Penyedia yang Ditingkatkan 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 Microsoft Base adalah satu, dan maksimumnya adalah 40. Dalam 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 Microsoft Base.
|
-
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 sandi . 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 cipher diatur ke CRYPT_MODE_CBC secara default untuk Penyedia Kriptografi Microsoft Base.
|
-
KP_MODE_BITS
|
pbData menunjuk ke nilai DWORD yang menunjukkan jumlah bit yang diproses per siklus saat Umpan Balik Output (OFB) atau mode sandi Umpan Balik Sandi (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 |
Arti |
-
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
Pointer ke buffer yang diinisialisasi dengan nilai yang akan diatur sebelum memanggil CryptSetKeyParam. Bentuk data ini bervariasi tergantung pada nilai dwParam.
[in] dwFlags
Digunakan hanya 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 lain yang diizinkan saat menghasilkan jenis kunci yang sama dengan CryptGenKey. Untuk informasi tentang nilai bendera yang diizinkan, lihat CryptGenKey.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).
Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE). Untuk informasi kesalahan yang diperluas, panggil GetLastError.
Kode kesalahan yang diawali oleh "NTE" dihasilkan oleh CSP tertentu yang digunakan. Beberapa kemungkinan kode kesalahan mengikuti.
| Mengembalikan 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 nonzero, 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.
|
Jika parameter KP_Q, KP_P, atau KP_X diatur pada kunci PREGEN Diffie-Hellman atau DSS, panjang kunci harus kompatibel dengan panjang kunci diatur menggunakan 16 bit atas parameter dwFlags ketika 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
| Syarat |
Nilai |
|
klien minimum yang didukung |
Windows XP [hanya aplikasi desktop] |
| server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
| Platform Target |
Windows |
| Header |
wincrypt.h |
| Pustaka |
Advapi32.lib |
| DLL |
Advapi32.dll |
Lihat juga
ALG_ID
CryptGenKey
CryptGetKeyParam
CryptImportKey
Pembuatan Kunci dan Fungsi Exchange