Fungsi CryptImportKey (wincrypt.h)
Sintaks
BOOL CryptImportKey(
[in] HCRYPTPROV hProv,
[in] const BYTE *pbData,
[in] DWORD dwDataLen,
[in] HCRYPTKEY hPubKey,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
Parameter
[in] hProv
Handel CSP yang diperoleh dengan fungsi CryptAcquireContext .
[in] pbData
Array BYTE yang berisi header BLOB PUBLICKEYSTRUC diikuti oleh kunci terenkripsi. BLOB kunci ini dibuat oleh fungsi CryptExportKey , baik dalam aplikasi ini atau oleh aplikasi lain yang mungkin berjalan di komputer yang berbeda.
[in] dwDataLen
Berisi panjang, dalam byte, dari BLOB kunci.
[in] hPubKey
Handel ke kunci kriptografi yang mendekripsi kunci yang disimpan dalam pbData. Kunci ini harus berasal dari CSP yang sama yang dirujuk hProv . Arti parameter ini berbeda tergantung pada jenis CSP dan jenis BLOB kunci yang diimpor:
- Jika BLOB kunci dienkripsi dengan pasangan kunci pertukaran kunci, misalnya, SIMPLEBLOB, parameter ini dapat menjadi pegangan ke kunci pertukaran kunci.
- Jika BLOB kunci dienkripsi dengan kunci sesi, misalnya, PRIVATEKEYBLOB terenkripsi, parameter ini berisi handel kunci sesi ini.
- Jika BLOB kunci tidak dienkripsi, misalnya, PUBLICKEYBLOB, parameter ini tidak digunakan dan harus nol.
- Jika BLOB kunci dienkripsi dengan kunci sesi dalam CSP Schannel , misalnya, OPAQUEKEYBLOB terenkripsi atau OPAQUEKEYBLOB khusus vendor lainnya, parameter ini tidak digunakan dan harus diatur ke nol.
[in] dwFlags
Saat ini hanya digunakan ketika pasangan kunci publik/privat dalam bentuk PRIVATEKEYBLOB diimpor ke CSP.
Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Kunci yang diimpor akhirnya akan diekspor ulang. Jika bendera ini tidak digunakan, maka panggilan ke CryptExportKey dengan handel kunci gagal. |
|
Bendera ini menyebabkan pemformatan PKCS #1 versi 2 diperiksa dengan enkripsi dan dekripsi RSA saat mengimpor SIMPLEBLOBs. |
|
Nilai tanpa garam dialokasikan untuk kunci konten 40-bit. Untuk informasi selengkapnya, lihat Fungsionalitas Nilai Garam. |
|
Jika bendera ini diatur, CSP memberi tahu pengguna melalui kotak dialog atau beberapa metode lain ketika tindakan tertentu dicoba menggunakan kunci ini. Perilaku yang tepat ditentukan oleh CSP atau jenis CSP yang digunakan. Jika konteks penyedia diperoleh dengan set CRYPT_SILENT, menggunakan bendera ini menyebabkan kegagalan dan kesalahan terakhir diatur ke NTE_SILENT_CONTEXT. |
|
Memungkinkan impor kunci RC2 yang lebih besar dari 16 byte. Jika bendera ini tidak diatur, panggilan ke fungsi CryptImportKey dengan kunci RC2 yang lebih besar dari 16 byte gagal, dan panggilan ke GetLastError akan mengembalikan NTE_BAD_DATA. |
[out] phKey
Penunjuk ke nilai HCRYPTKEY yang menerima handel kunci yang diimpor. Setelah Anda selesai menggunakan kunci, lepaskan handel dengan memanggil fungsi CryptDestroyKey .
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 mengikuti.
| Menampilkan kode | Deskripsi |
|---|---|
|
Beberapa CSP mengatur kesalahan ini jika kunci privat diimpor ke dalam kontainer saat utas atau proses lain menggunakan kunci ini. |
|
Salah satu parameter menentukan handel yang tidak valid. |
|
Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid. |
|
BLOB kunci sederhana yang akan diimpor tidak dienkripsi dengan algoritma pertukaran kunci yang diharapkan. |
|
Algoritma yang berfungsi dengan kunci umum yang akan diimpor tidak didukung oleh CSP ini, atau upaya dilakukan untuk mengimpor kunci sesi yang dienkripsi dengan sesuatu selain salah satu kunci publik Anda. |
|
Parameter dwFlags yang ditentukan tidak valid. |
|
Jenis BLOB kunci tidak didukung oleh CSP ini dan mungkin tidak valid. |
|
Parameter hProv tidak berisi handel konteks yang valid. |
|
Nomor versi BLOB kunci tidak cocok dengan versi CSP. Ini biasanya menunjukkan bahwa CSP perlu ditingkatkan. |
Keterangan
Saat mengimpor kunci Kode Autentikasi Pesan Berbasis Hash (HMAC), pemanggil harus mengidentifikasi kunci yang diimpor sebagai jenis PLAINTEXTKEYBLOB dan mengatur pengidentifikasi algoritma yang sesuai di bidang aiKeyAlg dari header BLOB PUBLICKEYSTRUC .
Fungsi CryptImportKey dapat digunakan untuk mengimpor kunci teks biasa untuk algoritma simetris; namun, kami menyarankan agar, untuk kemudahan penggunaan, Anda menggunakan fungsi CryptGenKey sebagai gantinya. Saat Anda mengimpor kunci teks biasa, struktur BLOB kunci yang diteruskan dalam parameter pbData adalah PLAINTEXTKEYBLOB.
Anda dapat menggunakan jenis PLAINTEXTKEYBLOB dengan algoritma atau jenis kombinasi kunci apa pun yang didukung oleh CSP yang digunakan.
Untuk contoh mengimpor kunci teks biasa, lihat Contoh Program C: Mengimpor Kunci Teks Biasa.
Contoh berikut menunjukkan bagaimana Anda bisa mengatur bidang header.
keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;
Panjang kunci ditentukan dalam keyBlob.keyLength, yang diikuti oleh data kunci aktual.
Ukuran kunci berikut didukung.
| Algoritma | Ukuran kunci yang didukung |
|---|---|
| CALG_DES | 64 bit |
| CALG_3DES_112 | 128 bit |
| CALG_3DES | 192 bit |
Contoh
Contoh berikut menunjukkan cara mengimpor kunci dari BLOB kunci. Untuk contoh lengkap untuk fungsi ini, lihat Contoh Program C: Menandatangani Hash dan Memverifikasi Tanda Tangan Hash. Untuk kode tambahan yang menggunakan fungsi ini, lihat Contoh Program C: Mendekripsi File.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
HCRYPTKEY hPubKey;
//---------------------------------------------------------------
// This code assumes that a cryptographic provider (hProv)
// has been acquired and that a key BLOB (pbKeyBlob) that is
// dwBlobLen bytes long has been acquired.
//---------------------------------------------------------------
// Get the public key of the user who created the digital
// signature and import it into the CSP by using CryptImportKey.
// The key to be imported is in the buffer pbKeyBlob that is
// dwBlobLen bytes long. This function returns a handle to the
// public key in hPubKey.
if(CryptImportKey(
hProv,
pbKeyBlob,
dwBlobLen,
0,
0,
&hPubKey))
{
printf("The key has been imported.\n");
}
else
{
printf("Public key import failed.\n");
return FALSE;
}
//---------------------------------------------------------------
// Insert code that uses the imported public key here.
//---------------------------------------------------------------
//---------------------------------------------------------------
// When you have finished using the key, you must release it.
if(CryptDestroyKey(hPubKey))
{
printf("The public key has been released.");
}
else
{
printf("The public key has not been released.");
return FALSE;
}
return TRUE;
}
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