Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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 ini pertama-tama mencoba menemukan CSP dengan karakteristik yang dijelaskan dalam parameter dwProvType dan szProvider. Jika CSP ditemukan, fungsi mencoba menemukan kontainer kunci dalam CSP yang cocok dengan nama yang ditentukan oleh parameter szContainer
Dengan pengaturan yang sesuai dwFlags, 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.
Sintaksis
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
[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, szContainer 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 szContainer
[in] szProvider
String null-terminated yang berisi nama CSP yang akan digunakan.
Jika parameter ini null, penyedia default pengguna 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
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 mengatur satu atau beberapa bendera berikut.
| Nilai | Arti |
|---|---|
|
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 hashing , 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 szContainer Untuk CSP berbasis perangkat keras, seperti CSP kartu pintar, jika parameter szContainer 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 szContainer. Jika szContainerNULL, 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 seperti itu. 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 untuk 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 ketika pengguna mengakses dari layanan atau akun pengguna yang tidak masuk secara interaktif. Ketika kontainer kunci dibuat, sebagian besar CSP tidak secara otomatis membuat pasangan kunci publik/privat . Kunci ini harus dibuat sebagai langkah terpisah dengan fungsi |
|
Hapus kontainer kunci 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 dioperasikan, panggilan gagal dan kode kesalahan NTE_SILENT_CONTEXT diatur sebagai kesalahan terakhir. Selain itu, jika panggilan dilakukan untuk 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 hashing dan operasi kunci konten 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 nonzero (TRUE).
Jika fungsi gagal, fungsi akan mengembalikan 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 yang ditentukan dalam Winerror.h ikuti.
| Mengembalikan kode/nilai | Deskripsi |
|---|---|
|
Beberapa CSP mengatur kesalahan ini jika nilai bendera CRYPT_DELETEKEYSET diatur dan utas lain atau proses 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 |
|
Parameter szContainer |
|
Nilai parameter |
|
Tanda tangan DLL penyedia tidak dapat diverifikasi. DLL atau tanda tangan digital telah dirusak. |
|
Parameter |
|
Kontainer kunci szContainer |
|
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. |
|
Jenis penyedia yang ditentukan oleh dwProvType tidak cocok dengan jenis penyedia yang ditemukan. Perhatikan bahwa kesalahan ini hanya dapat terjadi ketika szProvider 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. |
Komentar
Parameter szContainer
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 dihasilkan.
Jika Anda mengatur parameter szContainer
Aplikasi dapat memperoleh nama kontainer kunci yang digunakan dengan menggunakan fungsi
Untuk alasan performa, kami sarankan Anda mengatur parameter szContainer
- Anda membuat hash.
- Anda membuat kunci konten untuk mengenkripsi atau mendekripsi data.
- Anda mengambil 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.
Untuk contoh 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");
}
Nota
Header wincrypt.h mendefinisikan CryptAcquireContext sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur 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
| 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
Fungsi Penyedia Layanan