Fungsi CryptRetrieveObjectByUrlA (wincrypt.h)

2024-11-20

Fungsi CryptRetrieveObjectByUrl mengambil objek infrastruktur kunci publik (PKI) dari lokasi yang ditentukan oleh URL.

Objek jarak jauh ini dalam format yang dikodekan dan diambil dalam formulir "konteks".

Sintaksis

BOOL CryptRetrieveObjectByUrlA(
  [in]           LPCSTR                   pszUrl,
  [in]           LPCSTR                   pszObjectOid,
  [in]           DWORD                    dwRetrievalFlags,
  [in]           DWORD                    dwTimeout,
  [out]          LPVOID                   *ppvObject,
  [in]           HCRYPTASYNC              hAsyncRetrieve,
  [in, optional] PCRYPT_CREDENTIALS       pCredentials,
  [in, optional] LPVOID                   pvVerify,
  [in]           PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
);

Parameter

[in] pszUrl

Alamat objek PKI yang akan diambil. Skema berikut didukung:

ldap (Protokol Akses Direktori Ringan )
http
https (daftar pencabutan sertifikat (CRL) atau pengambilan protokol status sertifikat online (OCSP) saja)
arsip

[in] pszObjectOid

Alamat string ANSI yang dihentikan null yang mengidentifikasi jenis objek yang akan diambil. Ini bisa menjadi salah satu nilai berikut.

Nilai	Arti
NULL GUMPALAN	Ambil satu atau beberapa data blob. Bit yang dikodekan dikembalikan dalam array BLOB. ppvObject adalah alamat penunjuk struktur CRYPT_BLOB_ARRAY yang menerima array BLOB. Ketika struktur ini tidak lagi diperlukan, Anda harus membebaskannya dengan meneruskan alamat struktur ini ke fungsi CryptMemFree.
CONTEXT_OID_CERTIFICATE sertifikat	Ambil satu atau beberapa sertifikat. Jika satu objek diambil, ppvObject adalah alamat penunjuk struktur CERT_CONTEXT yang menerima konteks. Ketika konteks ini tidak lagi diperlukan, Anda harus membebaskannya dengan meneruskan penunjuk struktur CERT_CONTEXT ke fungsi CertFreeCertificateContext. Jika beberapa objek diambil, ppvObject adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan yang berisi sertifikat. Ketika penyimpanan ini tidak lagi diperlukan, Anda harus menutupnya dengan meneruskan handel ini ke fungsi CertCloseStore.
CONTEXT_OID_CRL CRL	Ambil satu atau beberapa daftar pencabutan sertifikat (CRL). Jika satu objek sedang diambil, ppvObject adalah alamat penunjuk struktur CRL_CONTEXT yang menerima konteks. Ketika konteks ini tidak lagi diperlukan, Anda harus membebaskannya dengan meneruskan penunjuk struktur CRL_CONTEXT ke fungsi CertFreeCRLContext . Jika beberapa objek diambil, ppvObject adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan yang berisi CRL. Ketika penyimpanan ini tidak lagi diperlukan, Anda harus menutupnya dengan meneruskan handel ini ke fungsi CertCloseStore.
CONTEXT_OID_CTL CTL	Ambil satu atau beberapa daftar kepercayaan sertifikat (CTL). Jika satu objek sedang diambil, ppvObject adalah alamat penunjuk struktur CTL_CONTEXT yang menerima konteks. Ketika konteks ini tidak lagi diperlukan, Anda harus membebaskannya dengan meneruskan penunjuk struktur CTL_CONTEXT ke fungsi CertFreeCTLContext. Jika beberapa objek diambil, ppvObject adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan yang berisi CTL. Ketika penyimpanan ini tidak lagi diperlukan, Anda harus menutupnya dengan meneruskan handel ini ke fungsi CertCloseStore.
CONTEXT_OID_PKCS7 PKCS7	ppvObject adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan yang berisi objek dari pesan. Ketika penyimpanan ini tidak lagi diperlukan, Anda harus menutupnya dengan meneruskan handel ini ke fungsi CertCloseStore.
CONTEXT_OID_CAPI2_ANY Fungsi akan menentukan item yang sesuai	ppvObject adalah alamat variabel HCERTSTORE yang menerima handel penyimpanan yang berisi objek. Ketika penyimpanan ini tidak lagi diperlukan, Anda harus menutupnya dengan meneruskan handel ini ke fungsi CertCloseStore.
CONTEXT_OID_OCSP_RESP Respons OCSP	ppvObject adalah alamat penunjuk ke struktur CRYPT_BLOB_ARRAY.

[in] dwRetrievalFlags

Menentukan apakah akan menggunakan URL yang di-cache atau URL yang diambil dari URL kawat. Formulir tempat objek dikembalikan ditentukan oleh nilai pszObjectOid.

Nilai	Arti
CRYPT_AIA_RETRIEVAL	Memvalidasi konten yang diambil oleh URL kawat sebelum menulis URL ke cache. Penyedia default tidak mendukung protokol HTTPS untuk pengambilan AIA.
CRYPT_ASYNC_RETRIEVAL	Nilai ini tidak didukung.
CRYPT_CACHE_ONLY_RETRIEVAL	Mengambil bit yang dikodekan dari cache URL saja. Jangan gunakan kawat untuk mengambil URL.
CRYPT_DONT_CACHE_RESULT	Tidak menyimpan bit yang dikodekan yang diambil ke cache URL. Jika bendera ini tidak diatur, URL yang diambil akan di-cache.
CRYPT_HTTP_POST_RETRIEVAL	Menggunakan metode POST alih-alih metode GET default untuk pengambilan HTTP. Dalam URL POST, data biner dan string header tambahan ditambahkan ke URL dasar dalam format berikut: BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData? OpsionalHttpHeaders Contoh berikut menunjukkan data biner tambahan yang dibatasi oleh tanda garis miring terakhir (/) dan header Tipe Konten yang dibatasi oleh tanda tanya (?) ditambahkan ke URL dasar. `http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request` Ketika bendera ini diatur, fungsi CryptRetrieveObjectByUrl mengurai URL dengan menggunakan pemisah tanda garis miring terakhir (/) dan tanda tanya (?). String, yang dibatasi oleh tanda garis miring (/), berisi URL yang tidak dilewati (yaitu, URL teks biasa tanpa karakter escape atau urutan escape) dan data Base64 yang didekodekan ke dalam bentuk biner sebelum diteruskan ke fungsi WinHttpSendRequest sebagai parameter lpOptional. String yang dibatasi oleh tanda tanya (?) diteruskan ke fungsi WinHttpSendRequest sebagai parameter pwszHeaders.
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL	Melakukan pencarian DNS khusus A-Record pada string host yang disediakan, mencegah pembuatan kueri DNS palsu saat menyelesaikan nama host. Bendera ini harus digunakan saat meneruskan nama host dibandingkan dengan nama domain.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE	Mengambil indeks entri dan nama atribut untuk setiap objek LDAP. Awal setiap BLOB yang dikembalikan berisi string ANSI berikut: "indeks entri dalam nama atributdesimal \0\0" Ketika bendera ini diatur, pszObjectOid harus null sehingga BLOB dikembalikan. Bendera ini hanya berlaku untuk skema ldap.
CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL	Gagal jika cakupan pencarian LDAP tidak diatur ke basis di URL. Gunakan hanya dengan LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL	Menandatangani secara digital semua lalu lintas LDAP ke dan dari server dengan menggunakan protokol autentikasi Kerberos. Fitur ini memberikan integritas yang diperlukan oleh beberapa aplikasi.
CRYPT_NO_AUTH_RETRIEVAL	Menghambat penanganan autentikasi otomatis.
CRYPT_NOT_MODIFIED_RETRIEVAL	Mengaktifkan pengambilan URL HTTP bersyarah. Ketika bendera ini diatur, untuk pengambilan bersyarkat yang mengembalikan HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl mengembalikan TRUE dan ppvObject diatur ke NULL. Jika pAuxInfo tidak NULL , dwHttpStatusCode diatur ke HTTP_STATUS_NOT_MODIFIED. Jika tidak, ppvObject diperbarui untuk pengambilan yang berhasil.
CRYPT_OFFLINE_CHECK_RETRIEVAL	Melacak kegagalan offline dan penundaan sebelum mencapai kawat pada pengambilan berikutnya. Nilai ini hanya untuk pengambilan kawat.
CRYPT_PROXY_CACHE_RETRIEVAL	Mengaktifkan pengambilan cache proksi objek. Jika cache proksi tidak dilewati secara eksplisit, fProxyCacheRetrieval diatur ke TRUE di pAuxInfo. Nilai ini hanya berlaku untuk pengambilan URL HTTP.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS	Mengambil beberapa objek jika tersedia. Semua objek harus dari jenis objek homogen seperti yang ditentukan oleh nilai pszObjectOid , kecuali nilai pengidentifikasi objek (OID) CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL	Menandai URL sebagai dikecualikan agar tidak dihapus dari cache. Untuk informasi selengkapnya, lihat STICKY_CACHE_ENTRY di INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE	Memperoleh verifikasi tanda tangan pada konteks yang dibuat. Dalam hal ini pszObjectOid harus NULL non-dan pvVerify menunjuk ke konteks sertifikat penanda tangan.
CRYPT_VERIFY_DATA_HASH	Bendera ini tidak diimplementasikan. Jangan gunakan itu.
CRYPT_WIRE_ONLY_RETRIEVAL	Mengambil bit yang dikodekan dari kawat saja. Tidak menggunakan cache URL.

[in] dwTimeout

Menentukan jumlah maksimum milidetik untuk menunggu pengambilan. Jika nilai nol ditentukan, fungsi ini tidak kehabisan waktu. Parameter ini tidak digunakan jika skema URL file:///.

[out] ppvObject

Alamat penunjuk ke objek yang dikembalikan. Jenis pengembalian dapat menjadi salah satu jenis yang didukung yang ditampilkan di pszObjectOid.

[in] hAsyncRetrieve

Parameter ini dicadangkan dan harus diatur ke NULL.

[in, optional] pCredentials

Parameter ini tidak digunakan.

[in, optional] pvVerify

Penunjuk ke objek verifikasi. Objek ini adalah fungsi dari parameter dwRetrievalFlags. Ini dapat null untuk menunjukkan bahwa pemanggil tidak tertarik untuk mendapatkan konteks sertifikat atau indeks penanda tangan jika dwRetrievalFlags CRYPT_VERIFY_CONTEXT_SIGNATURE.

[in] pAuxInfo

Penunjuk opsional ke struktur CRYPT_RETRIEVE_AUX_INFO. Jika tidak NULL dan jika cbSize anggota struktur diatur, parameter ini mengembalikan waktu pengambilan kawat terakhir yang berhasil.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE).

Komentar

Manajer pengambilan objek jarak jauh mengekspos dua model penyedia. Salah satunya adalah model Penyedia Skema yang memungkinkan penyedia protokol yang dapat diinstal seperti yang ditentukan oleh skema URL, yaitu, ldap, http, ftp, atau file. Titik masuk penyedia skema sama dengan fungsi CryptRetrieveObjectByUrl; namun, *ppvObject yang dikembalikan selalu merupakan array bit yang dikodekan yang dihitung (satu per objek yang diambil).

Model penyedia kedua adalah model Penyedia Konteks yang memungkinkan pembuat handel konteks (objek) yang dapat diinstal berdasarkan bit yang dikodekan yang diambil. Ini dikirim berdasarkan pengidentifikasi objek (OID) yang ditentukan dalam panggilan ke CryptRetrieveObjectByUrl.

Objek PKI individual seperti sertifikat, daftar kepercayaan, daftar pencabutan, pesan PKCS #7, dan beberapa objek homogen dapat diambil. Dimulai dengan Windows Vista dengan Paket Layanan 1 (SP1) dan Windows Server 2008, keamanan pengambilan "http:" dan "ldap:" telah diperkuat. Fungsi ini mendukung skema URL "http:" dan "ldap:" serta skema yang baru ditentukan.

Windows XP: "ftp:" tidak didukung untuk pengambilan jaringan.

Catatan Secara default, "file:" tidak didukung untuk pengambilan jaringan.

Nota

Header wincrypt.h mendefinisikan CryptRetrieveObjectByUrl 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	Cryptnet.lib
DLL	Cryptnet.dll

Lihat juga

CryptGetObjectUrl