PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET fungsi panggilan balik (wincrypt.h)

Artikel
08/27/2023

Fungsi panggilan balik PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET mengambil objek . Anda harus menerapkan fungsi ini sebagai bagian dari penyedia kustom Anda. Fungsi ini saat ini hanya dipanggil oleh paket keamanan Saluran Aman (Schannel).

Sintaks

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

Parameter

[in, optional] pPluginContext

Penunjuk ke buffer opsional yang ditentukan oleh penyedia ini dan dikembalikan oleh fungsi PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE . Buffer tidak dimodifikasi oleh pemanggil. Penyedia Anda dapat menggunakan data untuk membantunya menentukan tindakan apa yang harus dilakukan atau untuk mempertahankan informasi tambahan.

[in, optional] pIdentifier

Penunjuk ke struktur CRYPTOAPI_BLOB yang berisi pengidentifikasi objek. Nilai ini harus selalu NULL pada panggilan pertama ke fungsi ini.

[in] dwNameType

Format nama parameter pNameBlob . Nilai yang mungkin tercantum di bawah ini. Implementasi fungsi ini harus dapat memproses CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, yang diteruskan oleh Schannel.

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE (1 (0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE (32 (0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE (33 (0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE (0x0000FFFF)

[in] pNameBlob

Penunjuk ke struktur CRYPTOAPI_BLOB yang berisi nama yang digunakan aplikasi panggilan untuk mengidentifikasi objek secara unik. Penyedia Anda menggunakan nama ini untuk menemukan objek yang diminta. Schannel saat ini mengirimkan nama host DNS (sistem nama domain) yang dikodekan di UTF8 dengan nama IDN yang dikonversi dari punycode.

[out] ppbContent

Penunjuk ke array byte yang berisi objek yang akan dikembalikan.

[out] pcbContent

Ukuran, dalam byte, dari objek yang dirujuk oleh parameter ppbContent .

[out] ppwszPassword

Untai (karakter) Unicode yang dihentikan null yang berisi kata sandi, jika ada, digunakan untuk mengenkripsi objek. Jika objek adalah file pertukaran informasi pribadi (PFX), kata sandi biasanya akan digunakan untuk melakukan enkripsi. Nilai ini bisa NULL jika tidak ada kata sandi yang diperlukan.

[out] ppIdentifier

Alamat yang menerima penunjuk ke pengidentifikasi opsional yang dapat digunakan selama panggilan berikutnya ke fungsi ini dan untuk pemberitahuan perubahan. Untuk informasi selengkapnya, lihat Keterangan. Jika penyedia Anda menetapkan nilai ini ke NULL, Schannel secara internal menggunakan nilai parameter pNameBlob .

Mengembalikan nilai

Jika fungsi berhasil, kembalikan bukan nol (TRUE).

Jika fungsi gagal, kembalikan nol (FALSE) dan tentukan kesalahan yang sesuai dalam fungsi SetLastError . Sebagian besar kesalahan diteruskan melalui Schannel yang tidak diubah tetapi perilaku ini tidak dijamin. Beberapa kesalahan mungkin dipetakan ke kesalahan lain.

Jika objek tidak dapat dikembalikan untuk nama DNS tertentu (pNameBlob) atau pengidentifikasi (pIdentifier), kembalikan FALSE dan tentukan CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND dalam fungsi SetLastError .

Keterangan

Fungsi panggilan balik PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET saat ini hanya dipanggil oleh paket keamanan Saluran Aman (Schannel). Anda bisa mengembalikan objek yang merangkum salah satu hal berikut ini:

Array byte pertukaran informasi pribadi (PFX)
Penyimpanan sertifikat.
BLOB generik. Ini saat ini tidak didukung oleh Schannel.

Ketika fungsi ini pertama kali dipanggil, Schannel mengirimkan nama host DNS dalam argumen pNameBlob untuk menentukan host yang objeknya dimaksudkan. Penyedia Anda harus memproses nama (cocok dengan kartubebas, membangun jalur file, dan sebagainya) untuk menentukan objek apa yang akan ditemukan.

Karena banyak nama host dapat dipetakan ke satu objek, penyedia Anda dapat menggunakan parameter ppIdentifier untuk mengembalikan pengidentifikasi yang ditentukan secara internal yang dapat digunakan dalam panggilan berikutnya oleh fungsi API kriptografi (CAPI) ke penyedia. Penyedia kemudian dapat menggunakan pengidentifikasi untuk membantu menemukan objek yang sesuai.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [khusus aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincrypt.h

Lihat juga

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Bagikan melalui