Fungsi CryptRetrieveObjectByUrlA (wincrypt.h)
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 bentuk "konteks".
Sintaks
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)
- file
[in] pszObjectOid
Alamat string ANSI yang dihentikan null yang mengidentifikasi jenis objek yang akan diambil. Ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Ambil satu atau beberapa BLOB data. 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 . |
|
Ambil satu atau beberapa sertifikat.
Jika satu objek sedang 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 sedang 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 . |
|
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 sedang 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 . |
|
Ambil satu atau beberapa daftar kepercayaan sertifikat (CCL).
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 sedang 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 . |
|
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 . |
|
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 . |
|
ppvObject adalah alamat pointer 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 | Makna |
|---|---|
|
Memvalidasi konten yang diambil oleh URL kawat sebelum menulis URL ke cache.
Penyedia default tidak mendukung protokol HTTPS untuk pengambilan AIA. |
|
Nilai ini tidak didukung. |
|
Mengambil bit yang dikodekan dari cache URL saja. Jangan gunakan kawat untuk mengambil URL. |
|
Tidak menyimpan bit yang dikodekan yang diambil ke cache URL. Jika bendera ini tidak diatur, URL yang diambil akan di-cache. |
|
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/OpsionalURLEscaped&Base64EncodedAdditionalData?Opsional PenambalHTTPHeaders Contoh berikut menunjukkan data biner tambahan yang dibatasi oleh tanda garis miring terakhir (/) dan header Jenis Konten yang dibatasi oleh tanda tanya (?) ditambahkan ke URL dasar.
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 dilepas (yaitu, URL teks biasa tanpa karakter escape atau urutan escape) dan data Base64 yang didekodekan ke dalam formulir biner sebelum diteruskan ke fungsi WinHttpSendRequest sebagai parameter lpOptional . String yang dibatasi oleh tanda tanya (?) diteruskan ke fungsi WinHttpSendRequest sebagai parameter pwszHeaders . |
|
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. |
|
Mengambil indeks entri dan nama atribut untuk setiap objek LDAP. Awal setiap BLOB yang dikembalikan berisi string ANSI berikut: "indeks entri dalam nama atribut decimal\0\0" Ketika bendera ini diatur, pszObjectOid harus NULL sehingga BLOB dikembalikan. Bendera ini hanya berlaku untuk skema ldap. |
|
Gagal jika cakupan pencarian LDAP tidak diatur ke dasar di URL. Gunakan hanya dengan LDAP. |
|
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. |
|
Menghambat penanganan autentikasi otomatis. |
|
Mengaktifkan pengambilan URL HTTP bersyar. Ketika bendera ini diatur, untuk pengambilan kondisional yang mengembalikan HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl mengembalikan TRUE dan ppvObject diatur ke NULL. Jika pAuxInfo bukan NULL, dwHttpStatusCode diatur ke HTTP_STATUS_NOT_MODIFIED. Jika tidak, ppvObject diperbarui untuk pengambilan yang berhasil. |
|
Melacak kegagalan offline dan penundaan sebelum menekan kawat pada pengambilan berikutnya. Nilai ini hanya untuk pengambilan kawat. |
|
Mengaktifkan pengambilan singgahan proksi objek. Jika cache proksi tidak dilewati secara eksplisit, fProxyCacheRetrieval diatur ke TRUE di pAuxInfo. Nilai ini hanya berlaku untuk pengambilan URL HTTP. |
|
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. |
|
Menandai URL sebagai dikecualikan agar tidak dihapus dari cache. Untuk informasi selengkapnya, lihat STICKY_CACHE_ENTRY di INTERNET_CACHE_ENTRY_INFO. |
|
Memperoleh verifikasi tanda tangan pada konteks yang dibuat. Dalam hal ini pszObjectOid harus non-NULL dan pvVerify menunjuk ke konteks sertifikat penanda tangan. |
|
Bendera ini tidak diimplementasikan. Jangan gunakan metode tersebut. |
|
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 ditunjukkan dalam 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 . Dapat berupa 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 bukan NULL dan jika anggota cbSize struktur diatur, parameter ini mengembalikan waktu pengambilan kawat terakhir yang berhasil.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).
Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE).
Keterangan
Manajer pengambilan objek jarak jauh mengekspos dua model penyedia. Salah satunya adalah model Penyedia Skema yang memungkinkan penyedia protokol yang dapat diinstal seperti yang didefinisikan oleh skema URL, yaitu, ldap, http, ftp, atau file. Titik masuk penyedia skema sama dengan fungsi CryptRetrieveObjectByUrl ; namun, *ppvObject yang dikembalikan selalu merupakan array yang dihitung dari bit yang dikodekan (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
Header wincrypt.h mendefinisikan CryptRetrieveObjectByUrl sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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
| 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 | Cryptnet.lib |
| DLL | Cryptnet.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