Fungsi CryptGetKeyParam (wincrypt.h)

Artikel
03/15/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 CryptGetKeyParam mengambil data yang mengatur operasi kunci. Jika Penyedia Layanan Kriptografi Microsoft digunakan, materi kunci simetris dasar tidak dapat diperoleh oleh ini atau fungsi lainnya.

Sintaks

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Parameter

[in] hKey

Handel kunci yang sedang dikueri.

[in] dwParam

Menentukan jenis kueri yang sedang dibuat.

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

Nilai	Makna
KP_ALGID	Ambil algoritma kunci. Parameter pbData adalah penunjuk ke nilai ALG_ID yang menerima pengidentifikasi algoritma yang ditentukan saat kunci dibuat. Ketika AT_KEYEXCHANGE atau AT_SIGNATURE ditentukan untuk parameter Algid dari fungsi CryptGenKey , pengidentifikasi algoritma yang digunakan untuk menghasilkan kunci bergantung pada penyedia yang digunakan. Untuk informasi selengkapnya, lihat ALG_ID.
KP_BLOCKLEN	Jika kunci sesi ditentukan oleh parameter hKey , ambil panjang blok cipher kunci. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima panjang blok, dalam bit. Untuk cipher aliran, nilai ini selalu nol. Jika pasangan kunci publik/privat ditentukan oleh hKey, ambil granularitas enkripsi pasangan kunci. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima granularitas enkripsi, dalam bit. Misalnya, Penyedia Kriptografi Dasar Microsoft menghasilkan pasangan kunci RSA 512-bit, sehingga nilai 512 dikembalikan untuk kunci ini. Jika algoritma kunci publik tidak mendukung enkripsi, nilai yang diambil tidak terdefinisi.
KP_CERTIFICATE	pbData adalah alamat buffer yang menerima 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_GET_USE_COUNT	Nilai ini tidak digunakan.
KP_KEYLEN	Ambil panjang kunci yang sebenarnya. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima panjang kunci, dalam bit. KP_KEYLEN dapat digunakan untuk mendapatkan panjang jenis kunci apa pun. Penyedia layanan kriptografi (CSP) Microsoft mengembalikan panjang kunci 64 bit untuk CALG_DES, 128 bit untuk CALG_3DES_112, dan 192 bit untuk CALG_3DES. Panjang ini berbeda dari panjang yang dikembalikan ketika Anda menghitung algoritma dengan nilai dwParam dari fungsi CryptGetProvParam diatur ke PP_ENUMALGS. Panjang yang dikembalikan oleh panggilan ini adalah ukuran kunci aktual, termasuk bit paritas yang disertakan dalam kunci. CSP Microsoft yang mendukung CALG_CYLINK_MEK ALG_ID mengembalikan 64 bit untuk algoritma tersebut. CALG_CYLINK_MEK adalah kunci 40-bit tetapi memiliki paritas dan bit kunci nol untuk membuat panjang kunci 64 bit.
KP_SALT	Ambil nilai garam kunci. Parameter pbData adalah penunjuk ke array BYTE yang menerima nilai garam dalam bentuk little-endian . Ukuran nilai garam bervariasi tergantung pada CSP dan algoritma yang digunakan. Nilai garam tidak berlaku untuk pasangan kunci publik/privat.
KP_PERMISSIONS	Ambil izin kunci. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima bendera izin untuk kunci. Pengidentifikasi izin berikut saat ini ditentukan. Izin kunci bisa nol atau kombinasi dari satu atau beberapa nilai berikut. CRYPT_ARCHIVE Izinkan ekspor selama masa pakai handel kunci. Izin ini hanya dapat diatur jika sudah diatur di bidang izin internal kunci. Upaya untuk menghapus izin ini diabaikan. CRYPT_DECRYPT Izinkan dekripsi. CRYPT_ENCRYPT Izinkan enkripsi. CRYPT_EXPORT Izinkan kunci diekspor. CRYPT_EXPORT_KEY Izinkan kunci digunakan untuk mengekspor kunci. CRYPT_IMPORT_KEY Izinkan kunci digunakan untuk mengimpor kunci. CRYPT_MAC Izinkan Kode Autentikasi Pesan (MAC) digunakan dengan kunci. CRYPT_READ Perbolehkan nilai dibaca. CRYPT_WRITE Perbolehkan nilai diatur.

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

Nilai	Makna
KP_P	Ambil nomor prime modulus P dari kunci DSS. Parameter pbData adalah penunjuk ke buffer yang menerima nilai dalam bentuk little-endian. Parameter pdwDataLen berisi ukuran buffer, dalam byte.
KP_Q	Ambil nomor prime modulus Q dari kunci DSS. Parameter pbData adalah penunjuk ke buffer yang menerima nilai dalam bentuk little-endian. Parameter pdwDataLen berisi ukuran buffer, dalam byte.
KP_G	Ambil generator G kunci DSS. Parameter pbData adalah penunjuk ke buffer yang menerima nilai dalam bentuk little-endian. Parameter pdwDataLen berisi ukuran buffer, dalam byte.

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

Nilai	Makna
KP_EFFECTIVE_KEYLEN	Ambil panjang kunci yang efektif dari kunci RC2. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima panjang kunci yang efektif.
KP_IV	Ambil vektor inisialisasi kunci. Parameter pbData adalah penunjuk ke array BYTE yang menerima vektor inisialisasi. Ukuran array ini adalah ukuran blok, dalam byte. Misalnya, jika panjang blok adalah 64 bit, vektor inisialisasi terdiri dari 8 byte.
KP_PADDING	Ambil 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 (dtk 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	Ambil mode cipher. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima pengidentifikasi mode sandi. Untuk informasi selengkapnya tentang mode cipher, lihat Enkripsi dan Dekripsi Data. Pengidentifikasi mode sandi berikut saat ini ditentukan. CRYPT_MODE_CBC Mode cipher adalah rantai blok cipher. CRYPT_MODE_CFB Mode cipher adalah cipher feedback (CFB). Microsoft CSP saat ini hanya mendukung umpan balik 8-bit dalam mode umpan balik sandi. CRYPT_MODE_ECB Mode sandi adalah buku kode elektronik. CRYPT_MODE_OFB Mode cipher adalah Output Feedback (OFB). Microsoft CSP saat ini tidak mendukung Mode Umpan Balik Output. CRYPT_MODE_CTS Mode cipher adalah mode mencuri ciphertext .
KP_MODE_BITS	Ambil jumlah bit untuk disalurkan kembali. Parameter pbData adalah penunjuk ke nilai DWORD yang menerima jumlah bit yang diproses per siklus ketika mode cipher OFB atau CFB digunakan.

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

Nilai	Makna
KP_VERIFY_PARAMS	Memverifikasi parameter algoritma Diffie-Hellman atau kunci DSA. Parameter pbData tidak digunakan, dan nilai yang diarahkan oleh pdwDataLen menerima nol. Fungsi ini mengembalikan nilai bukan nol jika parameter kunci valid atau nol sebaliknya.
KP_KEYVAL	Nilai ini tidak digunakan. Windows Vista, Windows Server 2003, dan Windows XP: Ambil nilai perjanjian rahasia dari kunci algoritma Diffie-Hellman yang diimpor jenis CALG_AGREEDKEY_ANY. Parameter pbData adalah alamat buffer yang menerima nilai perjanjian rahasia, dalam format little-endian. Buffer ini harus memiliki panjang yang sama dengan kunci. Parameter dwFlags harus diatur ke 0xF42A19B6. Properti ini hanya dapat diambil oleh utas yang berjalan di bawah akun sistem lokal. Properti ini tersedia untuk digunakan dalam sistem operasi yang tercantum di atas. Ini dapat diubah atau tidak tersedia dalam versi berikutnya.

Nilai

Makna

KP_VERIFY_PARAMS

Memverifikasi parameter algoritma Diffie-Hellman atau kunci DSA. Parameter pbData tidak digunakan, dan nilai yang diarahkan oleh pdwDataLen menerima nol.

Fungsi ini mengembalikan nilai bukan nol jika parameter kunci valid atau nol sebaliknya.

KP_KEYVAL

Nilai ini tidak digunakan.

Windows Vista, Windows Server 2003, dan Windows XP: Ambil nilai perjanjian rahasia dari kunci algoritma Diffie-Hellman yang diimpor jenis CALG_AGREEDKEY_ANY. Parameter pbData adalah alamat buffer yang menerima nilai perjanjian rahasia, dalam format little-endian. Buffer ini harus memiliki panjang yang sama dengan kunci. Parameter dwFlags harus diatur ke 0xF42A19B6. Properti ini hanya dapat diambil oleh utas yang berjalan di bawah akun sistem lokal. Properti ini tersedia untuk digunakan dalam sistem operasi yang tercantum di atas. Ini dapat diubah atau tidak tersedia dalam versi berikutnya.

Jika sertifikat ditentukan oleh hKey, nilai dwParam juga dapat diatur ke nilai berikut.

Nilai	Makna
KP_CERTIFICATE	Buffer yang berisi sertifikat X.509 yang dikodekan DER. Parameter pbData tidak digunakan, dan nilai yang diarahkan oleh pdwDataLen menerima nol. Fungsi ini mengembalikan nilai bukan nol jika parameter kunci valid atau nol sebaliknya.

[out] pbData

Penunjuk ke buffer yang menerima data. Bentuk data ini tergantung pada nilai dwParam.

Jika ukuran buffer ini tidak diketahui, ukuran yang diperlukan dapat diambil pada durasi dengan meneruskan NULL untuk parameter ini dan mengatur nilai yang ditunjukkan oleh pdwDataLen ke nol. Fungsi ini akan menempatkan ukuran buffer yang diperlukan, dalam byte, dalam nilai yang ditunjukkan oleh pdwDataLen. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.

[in, out] pdwDataLen

Penunjuk ke nilai DWORD yang, pada entri, berisi ukuran, dalam byte, dari buffer yang diacu oleh parameter pbData . 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 mungkin sedikit lebih kecil dari ukuran buffer yang ditentukan pada input. Pada input, ukuran buffer terkadang 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.

[in] dwFlags

Parameter ini dicadangkan untuk digunakan di masa mendatang dan harus diatur ke nol.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan bukan nol.

Jika fungsi gagal, fungsi akan mengembalikan nol. Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Kode kesalahan yang diawali oleh "NTE" dihasilkan oleh CSP tertentu yang digunakan. Beberapa kemungkinan kode kesalahan termasuk yang berikut ini.

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	Jika buffer yang ditentukan oleh parameter pbData tidak cukup besar untuk menyimpan data yang dikembalikan, fungsi mengatur kode ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan, dalam byte, dalam variabel yang ditunjukkan oleh pdwDataLen.
NTE_BAD_FLAGS	Parameter dwFlags bukan nol.
NTE_BAD_KEY atau NTE_NO_KEY	Kunci yang ditentukan oleh parameter hKey tidak valid.
NTE_BAD_TYPE	Parameter dwParam menentukan nomor nilai yang tidak diketahui.
NTE_BAD_UID	Konteks CSP yang ditentukan ketika kunci dibuat tidak dapat ditemukan.

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

Lihat juga

CryptSetKeyParam

Pembuatan Kunci dan Fungsi Exchange