Fungsi CryptExportKey (wincrypt.h)

  • Artikel
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 CryptExportKey mengekspor kunci kriptografi atau pasangan kunci dari penyedia layanan kriptografi (CSP) dengan cara yang aman.

Handel ke kunci yang akan diekspor diteruskan ke fungsi, dan fungsi mengembalikan BLOB kunci. BLOB kunci ini dapat dikirim melalui transportasi yang tidak aman atau disimpan di lokasi penyimpanan yang tidak aman. Fungsi ini dapat mengekspor kunci sesi Schannel , kunci sesi reguler, kunci publik, atau pasangan kunci publik/privat. BLOB kunci yang akan diekspor tidak berguna sampai penerima yang dimaksud menggunakan fungsi CryptImportKey di dalamnya untuk mengimpor kunci atau pasangan kunci ke dalam CSP penerima.

Sintaks

BOOL CryptExportKey(
  [in]      HCRYPTKEY hKey,
  [in]      HCRYPTKEY hExpKey,
  [in]      DWORD     dwBlobType,
  [in]      DWORD     dwFlags,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen
);

Parameter

[in] hKey

Handel ke kunci yang akan diekspor.

[in] hExpKey

Handel ke kunci kriptografi pengguna tujuan. Data utama dalam BLOB kunci yang diekspor dienkripsi menggunakan kunci ini. Ini memastikan bahwa hanya pengguna tujuan yang dapat menggunakan BLOB kunci. hExpKey dan hKey harus berasal dari CSP yang sama.

Paling sering, ini adalah kunci publik pertukaran kunci pengguna tujuan. Namun, protokol tertentu di beberapa CSP mengharuskan kunci sesi milik pengguna tujuan digunakan untuk tujuan ini.

Jika jenis BLOB kunci yang ditentukan oleh dwBlobType adalah PUBLICKEYBLOB, parameter ini tidak digunakan dan harus diatur ke nol.

Jika jenis BLOB kunci yang ditentukan oleh dwBlobType adalah PRIVATEKEYBLOB, ini biasanya merupakan handel ke kunci sesi yang akan digunakan untuk mengenkripsi BLOB kunci. Beberapa CSP memungkinkan parameter ini menjadi nol, dalam hal ini aplikasi harus mengenkripsi BLOB kunci privat secara manual sehingga dapat melindunginya.

Untuk menentukan bagaimana penyedia layanan kriptografi Microsoft merespons parameter ini, lihat bagian BLOB kunci privatdari Penyedia Layanan Kriptografi Microsoft.

Catatan Beberapa CSP dapat memodifikasi parameter ini sebagai akibat dari operasi. Aplikasi yang kemudian menggunakan kunci ini untuk tujuan lain harus memanggil fungsi CryptDuplicateKey untuk membuat handel kunci duplikat. Ketika aplikasi telah selesai menggunakan handel, lepaskan dengan memanggil fungsi CryptDestroyKey .
 

[in] dwBlobType

Menentukan jenis BLOB kunci yang akan diekspor dalam pbData. Ini harus menjadi salah satu konstanta berikut seperti yang dibahas dalam Penyimpanan dan Pertukaran Kunci Kriptografi.

Nilai Makna
OPAQUEKEYBLOB
 Digunakan untuk menyimpan kunci sesi dalam CSP Schannel atau format khusus vendor lainnya. OPAQUEKEYBLOBLOB tidak dapat ditransfer dan harus digunakan dalam CSP yang menghasilkan BLOB.
PRIVATEKEYBLOB
 Digunakan untuk mengangkut pasangan kunci publik/privat.
PUBLICKEYBLOB
 Digunakan untuk mengangkut kunci umum.
SIMPLEBLOB
 Digunakan untuk mengangkut kunci sesi.
PLAINTEXTKEYBLOB
 PLAINTEXTKEYBLOB yang digunakan untuk mengekspor kunci apa pun yang didukung oleh CSP yang digunakan.
SYMMETRICWRAPKEYBLOB
 Digunakan untuk mengekspor dan mengimpor kunci konten yang dibungkus dengan kunci konten lainnya. Kunci yang dibungkus aktual dalam format yang ditentukan dalam standar IETF RFC 3217 .

[in] dwFlags

Menentukan opsi tambahan untuk fungsi tersebut. Parameter ini bisa nol atau kombinasi dari satu atau beberapa nilai berikut.

Nilai Makna
CRYPT_BLOB_VER3
0x00000080
 Bendera ini menyebabkan fungsi ini mengekspor versi 3 dari jenis BLOB.
CRYPT_DESTROYKEY
0x00000004
 Bendera ini menghancurkan kunci asli di OPAQUEKEYBLOB. Bendera ini hanya tersedia di CSP Schannel.
CRYPT_OAEP
0x00000040
 Bendera ini menyebabkan pemformatan PKCS #1 versi 2 dibuat dengan enkripsi dan dekripsi RSA saat mengekspor SIMPLEBLOB.
CRYPT_SSL2_FALLBACK
0x00000002
 Delapan byte pertama dari padding blok enkripsi RSA harus diatur ke 0x03 daripada data acak. Ini mencegah serangan pemutaran kembali versi dan dibahas dalam spesifikasi SSL3. Bendera ini hanya tersedia untuk CSP Schannel.
CRYPT_Y_ONLY
0x00000001
 Bendera ini tidak digunakan.

[out] pbData

Penunjuk ke buffer yang menerima data BLOB utama . Format BLOB ini bervariasi tergantung pada jenis BLOB yang diminta dalam parameter dwBlobType . Untuk format untuk PRIVATEKEYBLOBs, PUBLICKEYBLOBs, dan SIMPLEBLOB, lihat Blob Kunci Penyedia Dasar.

Jika parameter ini NULL, ukuran buffer yang diperlukan ditempatkan dalam nilai yang diarahkan oleh parameter 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 ini 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 bisa sedikit lebih kecil dari ukuran buffer yang ditentukan pada input. Pada input, ukuran buffer biasanya ditentukan cukup besar untuk memastikan bahwa data output terbesar yang mungkin cocok dalam buffer. Pada output, variabel yang diacu oleh parameter ini diperbarui untuk mencerminkan ukuran aktual data yang disalin ke buffer.
 
Untuk mengambil ukuran buffer pbData yang diperlukan, lewati NULL untuk pbData. Ukuran buffer yang diperlukan akan ditempatkan dalam nilai yang ditunjukkan oleh parameter ini.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).

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

Kode kesalahan yang diawali oleh "NTE" dihasilkan oleh CSP tertentu yang digunakan. Tabel berikut ini memperlihatkan beberapa kemungkinan kode kesalahan.

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_DATA
 Baik algoritma yang bekerja dengan kunci umum yang akan diekspor tidak didukung oleh CSP ini, atau upaya dilakukan untuk mengekspor kunci sesi yang dienkripsi dengan sesuatu selain salah satu kunci publik Anda.
NTE_BAD_FLAGS
 Parameter dwFlags bukan nol.
NTE_BAD_KEY
 Satu atau kedua kunci yang ditentukan oleh hKey dan hExpKey tidak valid.
NTE_BAD_KEY_STATE
 Anda tidak memiliki izin untuk mengekspor kunci. Artinya, ketika kunci hKey dibuat, bendera CRYPT_EXPORTABLE tidak ditentukan.
NTE_BAD_PUBLIC_KEY
 Jenis BLOB kunci yang ditentukan oleh dwBlobType adalah PUBLICKEYBLOB, tetapi hExpKey tidak berisi handel kunci publik.
NTE_BAD_TYPE
 Parameter dwBlobType menentukan jenis BLOB yang tidak diketahui.
NTE_BAD_UID
 Konteks CSP yang ditentukan ketika kunci hKey dibuat tidak dapat ditemukan.
NTE_NO_KEY
 Kunci sesi sedang diekspor, dan parameter hExpKey tidak menentukan kunci publik.

Keterangan

Untuk salah satu permutasi kunci DES yang menggunakan PLAINTEXTKEYBLOB, hanya ukuran kunci penuh, termasuk bit paritas, yang dapat diekspor. 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 mengekspor kunci kriptografi atau pasangan kunci dengan cara yang lebih aman. Contoh ini mengasumsikan bahwa konteks kriptografi telah diperoleh dan bahwa kunci publik tersedia untuk diekspor. Untuk contoh yang menyertakan konteks lengkap untuk menggunakan fungsi ini, lihat Contoh Program C: Menandatangani Hash dan Memverifikasi Tanda Tangan Hash. Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Mengekspor Kunci Sesi.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL GetExportedKey(
    HCRYPTKEY hKey, 
    DWORD dwBlobType,
    LPBYTE *ppbKeyBlob, 
    LPDWORD pdwBlobLen)
{
    DWORD dwBlobLength;
    *ppbKeyBlob = NULL;
    *pdwBlobLen = 0;

    // Export the public key. Here the public key is exported to a 
    // PUBLICKEYBLOB. This BLOB can be written to a file and
    // sent to another user.

    if(CryptExportKey(   
        hKey,    
        NULL,    
        dwBlobType,
        0,    
        NULL, 
        &dwBlobLength)) 
    {
        printf("Size of the BLOB for the public key determined. \n");
    }
    else
    {
        printf("Error computing BLOB length.\n");
        return FALSE;
    }

    // Allocate memory for the pbKeyBlob.
    if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength)) 
    {
        printf("Memory has been allocated for the BLOB. \n");
    }
    else
    {
        printf("Out of memory. \n");
        return FALSE;
    }

    // Do the actual exporting into the key BLOB.
    if(CryptExportKey(   
        hKey, 
        NULL,    
        dwBlobType,    
        0,    
        *ppbKeyBlob,    
        &dwBlobLength))
    {
        printf("Contents have been written to the BLOB. \n");
        *pdwBlobLen = dwBlobLength;
    }
    else
    {
        printf("Error exporting key.\n");
        free(*ppbKeyBlob);
        *ppbKeyBlob = NULL;

        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

CryptImportKey

Pembuatan Kunci dan Fungsi Exchange