Fungsi CryptAcquireContextA (wincrypt.h)
Fungsi ini pertama kali mencoba menemukan CSP dengan karakteristik yang dijelaskan dalam parameter dwProvType dan pszProvider . Jika CSP ditemukan, fungsi mencoba menemukan kontainer kunci dalam CSP yang cocok dengan nama yang ditentukan oleh parameter pszContainer . Untuk memperoleh konteks dan kontainer kunci kunci privat yang terkait dengan kunci publik sertifikat, gunakan CryptAcquireCertificatePrivateKey.
Dengan pengaturan dwFlags yang sesuai, fungsi ini juga dapat membuat dan menghancurkan kontainer kunci dan dapat menyediakan akses ke CSP dengan kontainer kunci sementara jika akses ke kunci privat tidak diperlukan.
Sintaks
BOOL CryptAcquireContextA(
[out] HCRYPTPROV *phProv,
[in] LPCSTR szContainer,
[in] LPCSTR szProvider,
[in] DWORD dwProvType,
[in] DWORD dwFlags
);
Parameter
[out] phProv
Penunjuk ke handel CSP. Setelah Anda selesai menggunakan CSP, lepaskan handel dengan memanggil fungsi CryptReleaseContext .
[in] szContainer
Nama kontainer kunci. Ini adalah string null-terminated yang mengidentifikasi kontainer kunci ke CSP. Nama ini tidak bergantung pada metode yang digunakan untuk menyimpan kunci. Beberapa CSP menyimpan kontainer kunci mereka secara internal (dalam perangkat keras), beberapa menggunakan registri sistem, dan yang lain menggunakan sistem file. Dalam kebanyakan kasus, ketika dwFlags diatur ke CRYPT_VERIFYCONTEXT, pszContainer harus diatur ke NULL. Namun, untuk CSP berbasis perangkat keras, seperti CSP kartu pintar, dapat mengakses informasi yang tersedia untuk umum dalam kontainer yang ditentukan.
Untuk informasi selengkapnya tentang penggunaan parameter pszContainer , lihat Keterangan.
[in] szProvider
String null-terminated yang berisi nama CSP yang akan digunakan.
Jika parameter ini NULL, penyedia default pengguna akan digunakan. Untuk informasi selengkapnya, lihat Konteks Penyedia Layanan Kriptografi. Untuk daftar penyedia kriptografi yang tersedia, lihat Nama Penyedia Kriptografi.
Aplikasi dapat memperoleh nama CSP yang digunakan dengan menggunakan fungsi CryptGetProvParam untuk membaca nilai CSP PP_NAME dalam parameter dwParam .
CSP default dapat berubah di antara rilis sistem operasi. Untuk memastikan interoperabilitas pada platform sistem operasi yang berbeda, CSP harus diatur secara eksplisit dengan menggunakan parameter ini alih-alih menggunakan CSP default.
[in] dwProvType
Menentukan jenis penyedia yang akan diperoleh. Jenis penyedia yang ditentukan dibahas dalam Jenis Penyedia Kriptografi.
[in] dwFlags
Bendera nilai. Parameter ini biasanya diatur ke nol, tetapi beberapa aplikasi menetapkan satu atau beberapa bendera berikut.
| Nilai | Makna |
|---|---|
|
Opsi ini ditujukan untuk aplikasi yang menggunakan kunci sementara, atau aplikasi yang tidak memerlukan akses ke kunci privat yang bertahan, seperti aplikasi yang hanya melakukan hash,enkripsi, dan verifikasi tanda tangan digital . Hanya aplikasi yang membuat tanda tangan atau mendekripsi pesan yang memerlukan akses ke kunci privat. Dalam kebanyakan kasus, bendera ini harus diatur.
Untuk CSP berbasis file, ketika bendera ini diatur, parameter pszContainer harus diatur ke NULL. Aplikasi ini tidak memiliki akses ke kunci privat yang dipertahankan dari pasangan kunci publik/privat. Ketika bendera ini diatur, pasangan kunci publik/privat sementara dapat dibuat, tetapi tidak bertahan. Untuk CSP berbasis perangkat keras, seperti CSP kartu pintar, jika parameter pszContainerNULL atau kosong, bendera ini menyiratkan bahwa tidak ada akses ke kunci apa pun yang diperlukan, dan bahwa tidak ada UI yang harus disajikan kepada pengguna. Formulir ini digunakan untuk menyambungkan ke CSP untuk mengkueri kemampuannya tetapi tidak benar-benar menggunakan kuncinya. Jika parameter pszContainer bukan NULL dan tidak kosong, maka bendera ini menyiratkan bahwa akses hanya ke informasi yang tersedia untuk umum dalam kontainer yang ditentukan diperlukan. CSP tidak boleh meminta PIN. Upaya untuk mengakses informasi privat (misalnya, fungsi CryptSignHash ) akan gagal. Ketika CryptAcquireContext dipanggil, banyak CSP memerlukan input dari pengguna pemilik sebelum memberikan akses ke kunci privat dalam kontainer kunci. Misalnya, kunci privat dapat dienkripsi, memerlukan kata sandi dari pengguna sebelum dapat digunakan. Namun, jika bendera CRYPT_VERIFYCONTEXT ditentukan, akses ke kunci privat tidak diperlukan dan antarmuka pengguna dapat dilewati. |
|
Membuat kontainer kunci baru dengan nama yang ditentukan oleh pszContainer. Jika pszContainer adalah NULL, kontainer kunci dengan nama default dibuat. |
|
Secara default, kunci dan kontainer kunci disimpan sebagai kunci pengguna. Untuk Penyedia Dasar, ini berarti bahwa kontainer kunci pengguna disimpan di profil pengguna. Kontainer kunci yang dibuat tanpa bendera ini oleh administrator hanya dapat diakses oleh pengguna yang membuat kontainer kunci dan pengguna dengan hak istimewa administrasi.
Windows XP: Kontainer kunci yang dibuat tanpa bendera ini oleh administrator hanya dapat diakses oleh pengguna yang membuat kontainer kunci dan akun sistem lokal. Kontainer kunci yang dibuat tanpa bendera ini oleh pengguna yang bukan administrator hanya dapat diakses oleh pengguna yang membuat kontainer kunci dan akun sistem lokal. Bendera CRYPT_MACHINE_KEYSET dapat dikombinasikan dengan semua bendera lain untuk menunjukkan bahwa kontainer kunci yang menarik adalah kontainer kunci komputer dan CSP memperlakukannya dengan demikian. Untuk Penyedia Dasar, ini berarti bahwa kunci disimpan secara lokal di komputer yang membuat kontainer kunci. Jika kontainer kunci adalah menjadi kontainer komputer, bendera CRYPT_MACHINE_KEYSET harus digunakan dengan semua panggilan ke CryptAcquireContext yang mereferensikan kontainer komputer. Kontainer kunci yang dibuat dengan CRYPT_MACHINE_KEYSET oleh administrator hanya dapat diakses oleh pembuatnya dan oleh pengguna dengan hak istimewa administrator kecuali hak akses ke kontainer diberikan menggunakan CryptSetProvParam. Windows XP: Kontainer kunci yang dibuat dengan CRYPT_MACHINE_KEYSET oleh administrator hanya dapat diakses oleh pembuatnya dan oleh akun sistem lokal kecuali hak akses ke kontainer diberikan menggunakan CryptSetProvParam. Kontainer kunci yang dibuat dengan CRYPT_MACHINE_KEYSET oleh pengguna yang bukan administrator hanya dapat diakses oleh pembuatnya dan oleh akun sistem lokal kecuali hak akses ke kontainer diberikan menggunakan CryptSetProvParam. Bendera CRYPT_MACHINE_KEYSET berguna saat pengguna mengakses dari layanan atau akun pengguna yang tidak masuk secara interaktif. Saat kontainer kunci dibuat, sebagian besar CSP tidak secara otomatis membuat pasangan kunci publik/privat apa pun. Kunci ini harus dibuat sebagai langkah terpisah dengan fungsi CryptGenKey . |
|
Hapus kontainer kunci yang ditentukan oleh pszContainer. Jika pszContainer adalah NULL, kontainer kunci dengan nama default akan dihapus. Semua pasangan kunci dalam kontainer kunci juga dihancurkan.
Ketika bendera ini diatur, nilai yang dikembalikan dalam phProv tidak ditentukan, dan dengan demikian, fungsi CryptReleaseContext tidak perlu dipanggil setelahnya. |
|
Aplikasi meminta agar CSP tidak menampilkan antarmuka pengguna (UI) apa pun untuk konteks ini. Jika CSP harus menampilkan UI untuk beroperasi, panggilan gagal dan kode kesalahan NTE_SILENT_CONTEXT diatur sebagai kesalahan terakhir. Selain itu, jika panggilan dilakukan ke CryptGenKey dengan bendera CRYPT_USER_PROTECTED dengan konteks yang telah diperoleh dengan bendera CRYPT_SILENT, panggilan gagal dan set CSP NTE_SILENT_CONTEXT.
CRYPT_SILENT ditujukan untuk digunakan dengan aplikasi yang UI-nya tidak dapat ditampilkan oleh CSP. |
|
Mendapatkan konteks untuk CSP kartu pintar yang dapat digunakan untuk operasi hashing dan kunci simetris tetapi tidak dapat digunakan untuk operasi apa pun yang memerlukan autentikasi ke kartu pintar menggunakan PIN. Jenis konteks ini paling sering digunakan untuk melakukan operasi pada kartu pintar kosong, seperti mengatur PIN dengan menggunakan CryptSetProvParam. Bendera ini hanya dapat digunakan dengan CSP kartu pintar.
Windows Server 2003 dan Windows XP: Bendera ini tidak didukung. |
Mengembalikan nilai
Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).
Jika fungsi gagal, fungsi mengembalikan 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 yang ditentukan dalam Winerror.h mengikuti.
| Mengembalikan kode/nilai | Deskripsi |
|---|---|
|
Beberapa CSP mengatur kesalahan ini jika nilai bendera CRYPT_DELETEKEYSET diatur dan utas atau proses lain menggunakan kontainer kunci ini. |
|
Profil pengguna tidak dimuat dan tidak dapat ditemukan. Ini terjadi ketika aplikasi meniru pengguna, misalnya, akun IUSR_ComputerName . |
|
Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid. |
|
Sistem operasi kehabisan memori selama operasi. |
|
Parameter dwFlags memiliki nilai yang tidak valid. |
|
Kata sandi pengguna telah berubah sejak kunci privat dienkripsi. |
|
Kontainer kunci tidak dapat dibuka. Penyebab umum kesalahan ini adalah bahwa kontainer kunci tidak ada. Untuk membuat kontainer kunci, panggil CryptAcquireContext menggunakan bendera CRYPT_NEWKEYSET. Kode kesalahan ini juga dapat menunjukkan bahwa akses ke kontainer kunci yang ada ditolak. Hak akses ke kontainer dapat diberikan oleh pembuat set kunci dengan menggunakan CryptSetProvParam. |
|
Parameter pszContainer atau pszProvider diatur ke nilai yang tidak valid. |
|
Nilai parameter dwProvType berada di luar rentang. Semua jenis penyedia harus dari 1 hingga 999, inklusif. |
|
Tanda tangan DLL penyedia tidak dapat diverifikasi. DLL atau tanda tangan digital telah dirusak. |
|
Parameter dwFlags CRYPT_NEWKEYSET, tetapi kontainer kunci sudah ada. |
|
Kontainer kunci pszContainer ditemukan tetapi rusak. |
|
Penyedia yang diminta tidak ada. |
|
CSP kehabisan memori selama operasi. |
|
File DLL penyedia tidak ada atau tidak ada di jalur saat ini. |
|
Jenis penyedia yang ditentukan oleh dwProvType rusak. Kesalahan ini dapat berhubungan dengan daftar CSP default pengguna atau daftar CSP default komputer. |
|
Tipe penyedia yang ditentukan oleh dwProvType tidak cocok dengan jenis penyedia yang ditemukan. Perhatikan bahwa kesalahan ini hanya dapat terjadi ketika pszProvider menentukan nama CSP yang sebenarnya. |
|
Tidak ada entri untuk jenis penyedia yang ditentukan oleh dwProvType. |
|
File DLL penyedia tidak dapat dimuat atau gagal diinisialisasi. |
|
Terjadi kesalahan saat memuat gambar file DLL, sebelum memverifikasi tanda tangannya. |
Keterangan
Parameter pszContainer menentukan nama kontainer yang digunakan untuk menahan kunci. Setiap kontainer dapat berisi satu kunci. Jika Anda menentukan nama kontainer yang ada saat membuat kunci, kunci baru akan menimpa yang sebelumnya.
Kombinasi nama CSP dan nama kontainer kunci secara unik mengidentifikasi satu kunci pada sistem. Jika satu aplikasi mencoba memodifikasi kontainer kunci saat aplikasi lain menggunakannya, perilaku yang tidak dapat diprediksi dapat mengakibatkan.
Jika Anda mengatur parameter pszContainer ke NULL, nama kontainer kunci default akan digunakan. Ketika CSP perangkat lunak Microsoft dipanggil dengan cara ini, kontainer baru dibuat setiap kali fungsi CryptAcquireContext dipanggil. Namun, CSP yang berbeda mungkin ber perilaku berbeda dalam hal ini. Secara khusus, CSP mungkin memiliki satu kontainer default yang dibagikan oleh semua aplikasi yang mengakses CSP. Oleh karena itu, aplikasi tidak boleh menggunakan kontainer kunci default untuk menyimpan kunci privat. Sebagai gantinya, cegah penyimpanan kunci dengan meneruskan bendera CRYPT_VERIFYCONTEXT dalam parameter dwFlags , atau gunakan kontainer khusus aplikasi yang tidak mungkin digunakan oleh aplikasi lain.
Aplikasi dapat memperoleh nama kontainer kunci yang digunakan dengan menggunakan fungsi CryptGetProvParam untuk membaca nilai PP_CONTAINER.
Untuk alasan performa, kami sarankan Anda mengatur parameter pszContainer ke NULL dan parameter dwFlags ke CRYPT_VERIFYCONTEXT dalam semua situasi di mana Anda tidak memerlukan kunci yang bertahan. Secara khusus, pertimbangkan untuk mengatur parameter pszContainer ke NULL dan parameter dwFlags ke CRYPT_VERIFYCONTEXT untuk skenario berikut:
- Anda membuat hash.
- Anda membuat kunci konten untuk mengenkripsi atau mendekripsi data.
- Anda mendapatkan kunci konten dari hash untuk mengenkripsi atau mendekripsi data.
- Anda sedang memverifikasi tanda tangan. Dimungkinkan untuk mengimpor kunci publik dari PUBLICKEYBLOB atau dari sertifikat dengan menggunakan CryptImportKey atau CryptImportPublicKeyInfo. Konteks dapat diperoleh dengan menggunakan bendera CRYPT_VERIFYCONTEXT jika Anda hanya berencana mengimpor kunci publik.
- Anda berencana untuk mengekspor kunci konten, tetapi tidak mengimpornya dalam masa pakai konteks kripto. Konteks dapat diperoleh dengan menggunakan bendera CRYPT_VERIFYCONTEXT jika Anda hanya berencana mengimpor kunci publik untuk dua skenario terakhir.
- Anda melakukan operasi kunci privat, tetapi Anda tidak menggunakan kunci privat tetap yang disimpan dalam kontainer kunci.
Contoh
Contoh berikut menunjukkan memperoleh konteks kriptografi dan akses ke pasangan kunci publik/privat dalam kontainer kunci. Jika kontainer kunci yang diminta tidak ada, kontainer tersebut dibuat.
Misalnya yang menyertakan konteks lengkap untuk contoh ini, lihat Contoh Program C: Membuat Kontainer Kunci dan Membuat Kunci. Untuk contoh tambahan, lihat Contoh Program C: Menggunakan CryptAcquireContext.
//-------------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv = NULL; // handle for a cryptographic
// provider context
LPCSTR UserName = "MyKeyContainer"; // name of the key container
// to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.
if(CryptAcquireContext(
&hCryptProv, // handle to the CSP
UserName, // container name
NULL, // use the default provider
PROV_RSA_FULL, // provider type
0)) // flag values
{
printf("A cryptographic context with the %s key container \n",
UserName);
printf("has been acquired.\n\n");
}
else
{
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key
// container. Error codes are defined in Winerror.h.
if (GetLastError() == NTE_BAD_KEYSET)
{
if(CryptAcquireContext(
&hCryptProv,
UserName,
NULL,
PROV_RSA_FULL,
CRYPT_NEWKEYSET))
{
printf("A new key container has been created.\n");
}
else
{
printf("Could not create a new key container.\n");
exit(1);
}
}
else
{
printf("A cryptographic service handle could not be "
"acquired.\n");
exit(1);
}
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.
//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.
if (CryptReleaseContext(hCryptProv,0))
{
printf("The handle has been released.\n");
}
else
{
printf("The handle could not be released.\n");
}
Catatan
Header wincrypt.h mendefinisikan CryptAcquireContext sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
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