Fungsi CryptGetProvParam (wincrypt.h)
Sintaks
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parameter
[in] hProv
Handel dari target CSP kueri. Handel ini harus dibuat dengan menggunakan fungsi CryptAcquireContext .
[in] dwParam
Sifat kueri. Kueri berikut ditentukan.
| Nilai | Makna |
|---|---|
|
Mengembalikan nomor identifikasi pribadi (PIN) administrator dalam parameter pbData sebagai LPSTR. |
|
Konstanta ini tidak digunakan. |
|
Konstanta ini tidak digunakan. |
|
Mengembalikan rantai sertifikat yang terkait dengan handel hProv . Rantai sertifikat yang dikembalikan X509_ASN_ENCODING dikodekan. |
|
Nama kontainer kunci saat ini sebagai string CHAR yang dihentikan null. String ini persis sama dengan yang diteruskan dalam parameter pszContainer dari fungsi CryptAcquireContext untuk menentukan kontainer kunci yang akan digunakan. Parameter pszContainer dapat dibaca untuk menentukan nama kontainer kunci default. |
|
Tidak diimplementasikan oleh Microsoft CSP. Perilaku ini dapat diimplementasikan oleh CSP lain.
Windows XP: Parameter ini tidak didukung. |
|
Struktur PROV_ENUMALGS yang berisi informasi tentang satu algoritma yang didukung oleh CSP yang sedang dikueri.
Pertama kali nilai ini dibaca, parameter dwFlags harus berisi bendera CRYPT_FIRST . Melakukannya menyebabkan fungsi ini mengambil elemen pertama dalam enumerasi. Elemen berikutnya kemudian dapat diambil dengan mengatur bendera CRYPT_NEXT di parameter dwFlags . Ketika fungsi ini gagal dengan kode kesalahan ERROR_NO_MORE_ITEMS , akhir enumerasi telah tercapai. Fungsi ini tidak aman untuk utas, dan semua algoritma yang tersedia mungkin tidak dijumlahkan jika fungsi ini digunakan dalam konteks multithread. |
|
Struktur PROV_ENUMALGS_EX yang berisi informasi tentang satu algoritma yang didukung oleh CSP yang sedang dikueri. Struktur yang dikembalikan berisi lebih banyak informasi tentang algoritma daripada struktur yang dikembalikan untuk PP_ENUMALGS.
Pertama kali nilai ini dibaca, parameter dwFlags harus berisi bendera CRYPT_FIRST . Melakukannya menyebabkan fungsi ini mengambil elemen pertama dalam enumerasi. Elemen berikutnya kemudian dapat diambil dengan mengatur bendera CRYPT_NEXT di parameter dwFlags . Ketika fungsi ini gagal dengan kode kesalahan ERROR_NO_MORE_ITEMS , akhir enumerasi telah tercapai. Fungsi ini tidak aman untuk utas dan semua algoritma yang tersedia mungkin tidak dijumlahkan jika fungsi ini digunakan dalam konteks multithread. |
|
Nama salah satu kontainer kunci yang dikelola oleh CSP dalam bentuk string CHAR yang dihentikan null.
Pertama kali nilai ini dibaca, parameter dwFlags harus berisi bendera CRYPT_FIRST . Melakukannya menyebabkan fungsi ini mengambil elemen pertama dalam enumerasi. Elemen berikutnya kemudian dapat diambil dengan mengatur bendera CRYPT_NEXT di parameter dwFlags . Ketika fungsi ini gagal dengan kode kesalahan ERROR_NO_MORE_ITEMS , akhir enumerasi telah tercapai. Untuk menghitung kontainer kunci yang terkait dengan komputer, pertama-tama panggil CryptAcquireContext menggunakan bendera CRYPT_MACHINE_KEYSET , lalu gunakan handel yang dikembalikan dari CryptAcquireContext sebagai parameter hProv dalam panggilan ke CryptGetProvParam. Fungsi ini tidak aman untuk utas dan semua algoritma yang tersedia mungkin tidak dijumlahkan jika fungsi ini digunakan dalam konteks multithread. |
|
Konstanta ini tidak digunakan. |
|
Menunjukkan bahwa CSP saat ini mendukung anggota dwProtocols dari struktur PROV_ENUMALGS_EX . Jika fungsi ini berhasil, CSP mendukung anggota dwProtocols dari struktur PROV_ENUMALGS_EX . Jika fungsi ini gagal dengan kode kesalahan NTE_BAD_TYPE , CSP tidak mendukung anggota dwProtocols . |
|
Konstanta ini tidak digunakan. |
|
Nilai DWORD yang menunjukkan bagaimana CSP diimplementasikan. Untuk tabel nilai yang mungkin, lihat Keterangan. |
|
Kueri ini tidak digunakan. |
|
Menentukan bahwa PIN pertukaran kunci terkandung dalam pbData. PIN direpresentasikan sebagai string ASCII yang dihentikan null. |
|
Mengambil deskriptor keamanan untuk kontainer penyimpanan kunci. Parameter pbData adalah alamat struktur SECURITY_DESCRIPTOR yang menerima pendeskripsi keamanan untuk kontainer penyimpanan kunci. Deskriptor keamanan dikembalikan dalam format relatif mandiri. |
|
Menentukan apakah parameter hProv adalah set kunci komputer. Parameter pbData harus berupa DWORD; DWORD akan diatur ke bendera CRYPT_MACHINE_KEYSET jika bendera tersebut diteruskan ke fungsi CryptAcquireContext . |
|
Mengembalikan informasi tentang nilai penentu kunci yang didukung CSP. Nilai penentu kunci digabungkan dalam OR logis dan dikembalikan dalam parameter pbData panggilan sebagai DWORD. Misalnya, Penyedia Kriptografi Dasar Microsoft versi 1.0 mengembalikan nilai DWORD AT_SIGNATURE | AT_KEYEXCHANGE. |
|
Mengembalikan nilai DWORD CRYPT_SEC_DESCR. |
|
Jumlah bit untuk panjang kenaikan AT_KEYEXCHANGE. Informasi ini digunakan dengan informasi yang dikembalikan dalam nilai PP_ENUMALGS_EX. Dengan informasi yang dikembalikan saat menggunakan PP_ENUMALGS_EX dan PP_KEYX_KEYSIZE_INC, panjang kunci yang valid untuk AT_KEYEXCHANGE dapat ditentukan. Panjang kunci ini kemudian dapat digunakan dengan CryptGenKey. Misalnya jika CSP menghitung CALG_RSA_KEYX (AT_KEYEXCHANGE) dengan panjang kunci minimum 512 bit dan maksimum 1024 bit, dan mengembalikan panjang kenaikan sebagai 64 bit, panjang kunci yang valid adalah 512, 576, 640,... 1024. |
|
Nama CSP dalam bentuk string CHAR yang dihentikan null. String ini identik dengan yang diteruskan dalam parameter pszProvider dari fungsi CryptAcquireContext untuk menentukan bahwa CSP saat ini digunakan. |
|
Nilai DWORD yang menunjukkan jenis penyedia CSP. |
|
Mendapatkan penyimpanan sertifikat akar untuk kartu pintar. Penyimpanan sertifikat ini berisi semua sertifikat akar yang disimpan pada kartu pintar.
Parameter pbData adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan sertifikat. Ketika handel ini tidak lagi diperlukan, pemanggil harus menutupnya dengan menggunakan fungsi CertCloseStore . Windows Server 2003 dan Windows XP: Parameter ini tidak didukung. |
|
Ukuran, dalam bit, dari kunci sesi. |
|
Digunakan dengan kriptografi berpagar server. |
|
Jumlah bit untuk panjang kenaikan AT_SIGNATURE. Informasi ini digunakan dengan informasi yang dikembalikan dalam nilai PP_ENUMALGS_EX. Dengan informasi yang dikembalikan saat menggunakan PP_ENUMALGS_EX dan PP_SIG_KEYSIZE_INC, panjang kunci yang valid untuk AT_SIGNATURE dapat ditentukan. Panjang kunci ini kemudian dapat digunakan dengan CryptGenKey.
Misalnya, jika CSP menghitung CALG_RSA_SIGN (AT_SIGNATURE) dengan panjang kunci minimum 512 bit dan maksimum 1024 bit, dan mengembalikan panjang kenaikan sebagai 64 bit, panjang kunci yang valid adalah 512, 576, 640,... 1024. |
|
Menentukan bahwa PIN tanda tangan kunci terkandung dalam pbData. PIN direpresentasikan sebagai string ASCII yang dihentikan null. |
|
Mendapatkan pengidentifikasi kartu pintar. Parameter pbData adalah alamat struktur GUID yang menerima pengidentifikasi kartu pintar.
Windows Server 2003 dan Windows XP: Parameter ini tidak didukung. |
|
Mendapatkan nama pembaca kartu pintar. Parameter pbData adalah alamat array karakter ANSI yang menerima string ANSI yang dihentikan null yang berisi nama pembaca kartu pintar. Ukuran buffer ini, yang terkandung dalam variabel yang diarahkan oleh parameter pdwDataLen , harus menyertakan terminator NULL .
Windows Server 2003 dan Windows XP: Parameter ini tidak didukung. |
|
Ukuran kunci konten. |
|
Kueri ini tidak digunakan. |
|
Nama kontainer unik dari kontainer kunci saat ini dalam bentuk string CHAR yang dihentikan null. Untuk banyak CSP, nama ini adalah nama yang sama yang dikembalikan saat nilai PP_CONTAINER digunakan. Fungsi CryptAcquireContext harus berfungsi dengan nama kontainer ini. |
|
Menunjukkan apakah generator angka acak perangkat keras (RNG) didukung. Ketika PP_USE_HARDWARE_RNG ditentukan, fungsi berhasil dan mengembalikan TRUE jika RNG perangkat keras didukung. Fungsi gagal dan mengembalikan FALSE jika RNG perangkat keras tidak didukung. Jika RNG didukung, PP_USE_HARDWARE_RNG dapat diatur di CryptSetProvParam untuk menunjukkan bahwa CSP harus secara eksklusif menggunakan RNG perangkat keras untuk konteks penyedia ini. Ketika PP_USE_HARDWARE_RNG digunakan, parameter pbData harus NULL dan dwFlags harus nol.
Tidak ada CSP Microsoft yang saat ini mendukung penggunaan RNG perangkat keras. |
|
Mendapatkan penyimpanan sertifikat pengguna untuk kartu pintar. Penyimpanan sertifikat ini berisi semua sertifikat pengguna yang disimpan di kartu pintar. Sertifikat di penyimpanan ini dikodekan dengan menggunakan pengodean PKCS_7_ASN_ENCODING atau X509_ASN_ENCODING dan harus berisi properti CERT_KEY_PROV_INFO_PROP_ID .
Parameter pbData adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan sertifikat dalam memori. Ketika handel ini tidak lagi diperlukan, pemanggil harus menutupnya dengan menggunakan fungsi CertCloseStore . Windows Server 2003 dan Windows XP: Parameter ini tidak didukung. |
|
Nomor versi CSP. Byte yang paling tidak signifikan berisi nomor versi minor dan byte paling signifikan berikutnya nomor versi utama. Versi 2.0 direpresentasikan sebagai 0x00000200. Untuk mempertahankan kompatibilitas mundur dengan versi Penyedia Kriptografi Microsoft Base yang lebih lama dan Penyedia Kriptografi yang Ditingkatkan Microsoft, nama penyedia mempertahankan penandaan "v1.0" di versi yang lebih baru. |
[out] pbData
Penunjuk ke buffer untuk menerima data. Bentuk data ini bervariasi tergantung pada nilai dwParam. Ketika dwParam diatur ke PP_USE_HARDWARE_RNG, pbData harus diatur ke NULL.
Parameter ini dapat berupa NULL untuk mengatur ukuran informasi ini untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.
[in, out] pdwDataLen
Penunjuk ke nilai DWORD yang menentukan ukuran, dalam byte, dari buffer yang diacu oleh parameter pbData . Saat fungsi kembali, nilai DWORD berisi jumlah byte yang disimpan atau disimpan dalam buffer.
Jika PP_ENUMALGS, atau PP_ENUMALGS_EX diatur, parameter pdwDataLen bekerja agak berbeda. Jika pbData adalah NULL atau nilai yang diarahkan oleh pdwDataLen terlalu kecil, nilai yang dikembalikan dalam parameter ini adalah ukuran item terbesar dalam daftar enumerasi alih-alih ukuran item yang saat ini sedang dibaca.
Jika PP_ENUMCONTAINERS diatur, panggilan pertama ke fungsi mengembalikan ukuran kontainer kunci maksimum yang diizinkan oleh penyedia saat ini. Ini berbeda dengan perilaku lain yang mungkin, seperti mengembalikan panjang kontainer terpanjang yang ada, atau panjang kontainer saat ini. Panggilan enumerasi berikutnya tidak akan mengubah parameter dwLen . Untuk setiap kontainer yang dijumlahkan, pemanggil dapat menentukan panjang string yang dihentikan null secara terprogram, jika diinginkan. Jika salah satu nilai enumerasi dibaca dan parameter pbData adalah NULL, bendera CRYPT_FIRST harus ditentukan agar informasi ukuran diambil dengan benar.
[in] dwFlags
Jika dwParamPP_KEYSET_SEC_DESCR, deskriptor keamanan pada kontainer kunci tempat kunci disimpan diambil. Untuk kasus ini, dwFlags digunakan untuk meneruskan bendera bit SECURITY_INFORMATION yang menunjukkan informasi keamanan yang diminta, seperti yang didefinisikan dalam Platform SDK. SECURITY_INFORMATION bendera bit dapat dikombinasikan dengan operasi bitwise-OR.
Nilai berikut didefinisikan untuk digunakan dengan PP_KEYSET_SEC_DESCR.
Nilai berikut didefinisikan untuk digunakan dengan PP_ENUMALGS, PP_ENUMALGS_EX, dan PP_ENUMCONTAINERS.
| Nilai | Makna |
|---|---|
|
Ambil elemen pertama dalam enumerasi. Ini memiliki efek yang sama dengan mengatur ulang enumerator. |
|
Ambil elemen berikutnya dalam enumerasi. Ketika tidak ada lagi elemen untuk diambil, fungsi ini akan gagal dan mengatur kesalahan terakhir ke ERROR_NO_MORE_ITEMS. |
|
Ambil sertifikat yang diaktifkan kriptografi terjaga server (SGC). Sertifikat yang diaktifkan SGC tidak lagi didukung. |
|
Bendera ini tidak digunakan. |
|
Bendera ini tidak digunakan. |
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 |
|---|---|
|
Salah satu parameter menentukan handel yang tidak valid. |
|
Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid. |
|
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. |
|
Akhir daftar enumerasi telah tercapai. Tidak ada data yang valid yang ditempatkan di buffer pbData . Kode kesalahan ini dikembalikan hanya ketika dwParam sama dengan PP_ENUMALGS atau PP_ENUMCONTAINERS. |
|
Parameter dwFlags menentukan bendera yang tidak valid. |
|
Parameter dwParam menentukan nomor nilai yang tidak diketahui. |
|
Konteks CSP yang ditentukan oleh hProv tidak valid. |
Keterangan
Fungsi ini tidak boleh digunakan pada utas program multithreaded.
Nilai berikut dikembalikan dalam pbData jika dwParam PP_IMPTYPE.
| Nilai | Makna |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
Implementasinya ada di perangkat keras. |
| CRYPT_IMPL_SOFTWARE 0x02 |
Implementasi ada dalam perangkat lunak. |
| CRYPT_IMPL_MIXED 0x03 |
Implementasi melibatkan perangkat keras dan perangkat lunak. |
| CRYPT_IMPL_UNKNOWN 0x04 |
Jenis implementasi tidak diketahui. |
| CRYPT_IMPL_REMOVABLE 0x08 |
Implementasi berada di media yang dapat dilepas. |
Parameter dwFlags digunakan untuk meneruskan bendera bit SECURITY_INFORMATION yang menunjukkan informasi keamanan yang diminta. Penunjuk ke deskriptor keamanan dikembalikan dalam parameter pbData dan panjang deskriptor keamanan dikembalikan dalam parameter pdwDataLen . Keamanan kontainer kunci ditangani dengan SetFileSecurity dan GetFileSecurity.
Kelas algoritma yang dijumlahkan dengan dwParam diatur ke PP_ENUMALGS atau PP_ENUMALGS_EX dapat ditentukan. Ini mungkin dilakukan untuk menampilkan daftar algoritma enkripsi yang didukung dan mengabaikan sisanya. Makro GET_ALG_CLASS(x) mengambil pengidentifikasi algoritma sebagai argumen dan mengembalikan kode yang menunjukkan kelas umum algoritma tersebut. Kemungkinan nilai yang dikembalikan meliputi:
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
Tabel berikut mencantumkan algoritma yang didukung oleh Penyedia Kriptografi Dasar Microsoft bersama dengan kelas setiap algoritma.
| Nama | Pengidentifikasi | Kelas |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
Aplikasi tidak boleh menggunakan algoritma dengan pengidentifikasi algoritma yang tidak dikenali. Menggunakan algoritma kriptografi yang tidak diketahui dapat menghasilkan hasil yang tidak dapat diprediksi.
Contoh
Contoh berikut menunjukkan menemukan nama CSP yang terkait dengan handel penyedia layanan kriptografi dan nama kontainer kunci yang terkait dengan handel. Untuk konteks lengkap untuk contoh ini, lihat Contoh Program C: Menggunakan CryptAcquireContext.
Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Menghitung Penyedia CSP dan Jenis Penyedia.
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
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
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk