Bagikan melalui


Fungsi CryptSetKeyParam (wincrypt.h)

Important 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 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.

Komentar

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