Fungsi NCryptTranslateHandle (ncrypt.h)

Artikel
08/25/2023

Fungsi NCryptTranslateHandle menerjemahkan handel CryptoAPI ke dalam handel kunci CNG.

Sintaks

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

Parameter

[out, optional] phProvider

Penunjuk ke variabel NCRYPT_PROV_HANDLE yang menerima handel penyedia penyimpanan kunci CNG yang memiliki kunci CNG yang ditempatkan dalam parameter phKey . Parameter ini bisa NULL jika handel ini tidak diperlukan.

[out] phKey

Penunjuk ke variabel NCRYPT_KEY_HANDLE yang menerima handel kunci CNG.

[in] hLegacyProv

Handel penyedia CryptoAPI yang berisi kunci untuk diterjemahkan. Fungsi ini akan menerjemahkan kunci CryptoAPI yang ada dalam kontainer di penyedia ini.

[in, optional] hLegacyKey

Handel kunci CryptoAPI yang digunakan untuk membantu menentukan spesifikasi kunci untuk kunci yang dikembalikan. Parameter ini diabaikan jika parameter dwLegacyKeySpec berisi nilai selain nol.

Jika hLegacyKey adalah NULL dan dwLegacyKeySpec adalah nol, fungsi ini akan mencoba menentukan spesifikasi kunci dari handel hLegacyProv .

[in, optional] dwLegacyKeySpec

Menentukan spesifikasi kunci untuk kunci. Ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
0	Kunci tidak ada dari jenis di bawah ini.
AT_KEYEXCHANGE 1	Kuncinya adalah kunci pertukaran kunci.
AT_SIGNATURE 2	Kuncinya adalah kunci tanda tangan.

Jika hLegacyKey adalah NULL dan dwLegacyKeySpec adalah nol, fungsi ini akan mencoba menentukan spesifikasi kunci dari handel hLegacyProv .

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Tidak ada bendera yang ditentukan untuk fungsi ini.

Nilai kembali

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini.

Menampilkan kode	Deskripsi
ERROR_SUCCESS	Fungsi berhasil.
NTE_BAD_FLAGS	Parameter dwFlags berisi nilai yang tidak valid.
NTE_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
NTE_NO_MEMORY	Terjadi kegagalan alokasi memori.

Keterangan

Ini adalah fungsi pembantu yang dimaksudkan untuk membantu aplikasi dan komponen sistem yang saat ini menggunakan CryptoAPI untuk melakukan transisi yang baik untuk menggunakan CNG.

Fungsi ini hanya akan berhasil jika penyedia penyimpanan kunci CNG terdaftar dengan nama atau alias yang identik dengan nama penyedia layanan kriptografi (CSP) yang disebut oleh parameter hLegacyProv .

Fungsi ini akan melakukan langkah-langkah berikut untuk menerjemahkan handel CSP ke dalam handel kunci CNG:

Dapatkan nama CSP dari handel hLegacyProv .
Buka penyedia CNG yang nama atau aliasnya identik dengan nama CSP.
Dapatkan nama kontainer kunci saat ini di CSP.
Dapatkan kunci CryptoAPI, terjemahkan ke dalam kunci CNG, dan kembalikan dalam parameter phKey .

Layanan tidak boleh memanggil fungsi ini dari Fungsi StartService-nya. Jika layanan memanggil fungsi ini dari fungsi StartService-nya, kebuntuan dapat terjadi, dan layanan mungkin berhenti merespons.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	ncrypt.h
Pustaka	Ncrypt.lib
DLL	Ncrypt.dll

Bagikan melalui