CryptRetrieveObjectByUrlA 函式 (wincrypt.h)

發行項
01/10/2024

CryptRetrieveObjectByUrl 函式會從 URL 指定的位置擷取公鑰基礎結構 (PKI) 物件。

這些遠端物件採用編碼格式，並以「內容」形式擷取。

語法

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
);

參數

[in] pszUrl

要擷取之 PKI 物件的位址。支援下列設定：

ldap (輕量型目錄存取通訊協定)
http
HTTPs (證書吊銷清單 (CRL) 或在線憑證狀態通訊協定， (OCSP) 僅擷取)
file

[in] pszObjectOid

Null 終止的 ANSI 字串位址，可識別要擷取的物件類型。這可以是下列其中一個值。

值	意義
NULL BLOB	擷取一或多個數據 BLOB。編碼的位會在 BLOB 的數位中傳回。 ppvObject 是接收 BLOB 陣列之 CRYPT_BLOB_ARRAY 結構指標的位址。不再需要此結構時，您必須將這個結構的位址傳遞至 CryptMemFree 函式來釋放它。
CONTEXT_OID_CERTIFICATE 憑證 (certificate)	擷取一或多個憑證。如果要擷取單一物件， ppvObject 是接收內容之CERT_CONTEXT 結構指標的位址。不再需要此內容時，您必須將 CERT_CONTEXT 結構指標傳遞至 CertFreeCertificateContext 函式，以釋放它。如果要擷取多個物件， ppvObject 是 HCERTSTORE 變數的位址，可接收包含憑證之存放區的句柄。不再需要此存放區時，您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_CRL CRL	擷取一或多個證書吊銷清單， (CRL) 。如果要擷取單一物件， ppvObject 是接收內容之 CRL_CONTEXT 結構指標的位址。不再需要此內容時，您必須將 CRL_CONTEXT 結構指標傳遞至 CertFreeCRLContext 函式來釋放它。如果要擷取多個物件， ppvObject 是 HCERTSTORE 變數的位址，可接收包含 CRL 之存放區的句柄。不再需要此存放區時，您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_CTL Ctl	擷取一或多個憑證信任清單， (CCL) 。如果要擷取單一物件， ppvObject 是接收內容之CTL_CONTEXT 結構指標的位址。不再需要此內容時，您必須將 CTL_CONTEXT 結構指標傳遞至 CertFreeCTLContext 函式來釋放它。如果要擷取多個物件， ppvObject 是 HCERTSTORE 變數的位址，可接收包含 CCL 之存放區的句柄。不再需要此存放區時，您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_PKCS7 PKCS7	ppvObject 是 HCERTSTORE 變數的位址，可接收包含訊息中物件的存放區句柄。不再需要此存放區時，您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_CAPI2_ANY 函式會決定適當的專案	ppvObject 是 HCERTSTORE 變數的位址，可接收包含物件的存放區句柄。不再需要此存放區時，您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_OCSP_RESP OCSP 回應	ppvObject 是 CRYPT_BLOB_ARRAY 結構的指標位址。

[in] dwRetrievalFlags

決定是否要使用快取的 URL 或從網路 URL 擷取的 URL。傳回物件的窗體取決於 pszObjectOid 的值。

值	意義
CRYPT_AIA_RETRIEVAL	先驗證網路 URL 所擷取的內容，再將URL寫入快取。預設提供者不支援 AIA 擷取的 HTTPS 通訊協定。
CRYPT_ASYNC_RETRIEVAL	不支援此值。
CRYPT_CACHE_ONLY_RETRIEVAL	只從 URL 快取擷取編碼位。請勿使用網路來擷取 URL。
CRYPT_DONT_CACHE_RESULT	不會將擷取的編碼位儲存至URL快取。如果未設定此旗標，則會快取擷取的URL。
CRYPT_HTTP_POST_RETRIEVAL	使用 POST 方法，而不是 HTTP 擷取的預設 GET 方法。在 POST URL 中，其他二進位數據和標頭字串會以下列格式附加至基底 URL： BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData？OptionalAdditionalHTTPHeaders 下列範例顯示最後一個斜線標記 (/) 分隔的其他二進位數據，以及以問號分隔 (？) 附加至基底 URL 的 Content-Type 標頭。 `http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request` 設定此旗標時， CryptRetrieveObjectByUrl 函式會使用最後一個斜線標記 (/) 和問號 (？) 分隔符來剖析 URL。以斜線標記分隔的字串 (/) ，包含未逸出的 URL (，也就是沒有逸出字元的純文本 URL，或逸出序列，) 和 Base64 數據譯碼為二進位格式，再傳遞至 WinHttpSendRequest 函式做為 lpOptional 參數。以問號 (？) 分隔的字串會傳遞至 WinHttpSendRequest 函式做為 pwszHeaders 參數。
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL	在提供的主機字串上執行僅限記錄的 DNS 查閱，以避免解析主機名時產生 false DNS 查詢。傳遞主機名而非功能變數名稱時，應該使用這個旗標。
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE	擷取每個LDAP物件的專案索引和屬性名稱。每個傳回 BLOB 的開頭都包含下列 ANSI 字串： “decimal\0屬性名稱\0 中的專案索引” 設定此旗標時， pszObjectOid 必須是 NULL ，才能傳回 BLOB。此旗標僅適用於ldap配置。
CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL	如果LDAP搜尋範圍未設定為URL中的基底，就會失敗。僅搭配LDAP使用。
CRYPT_LDAP_SIGN_RETRIEVAL	使用 Kerberos 驗證通訊協定，以數位方式簽署來自伺服器的所有 LDAP 流量。這項功能提供某些應用程式所需的完整性。
CRYPT_NO_AUTH_RETRIEVAL	禁止自動驗證處理。
CRYPT_NOT_MODIFIED_RETRIEVAL	啟用條件式 HTTP URL 擷取。設定此旗標時，針對傳回 HTTP_STATUS_NOT_MODIFIED的條件式擷取， CryptRetrieveObjectByUrl 會傳回 TRUE ，並將 ppvObject 設定為 NULL。如果 pAuxInfo 不是 NULL，dwHttpStatusCode 會設定為 HTTP_STATUS_NOT_MODIFIED。否則， ppvObject 會更新為成功擷取。
CRYPT_OFFLINE_CHECK_RETRIEVAL	在後續擷取上線之前，持續追蹤脫機失敗和延遲。此值僅適用於網路擷取。
CRYPT_PROXY_CACHE_RETRIEVAL	啟用物件的 Proxy 快取擷取。如果未明確略過 Proxy 快取，fProxyCacheRetrieval 會在 pAuxInfo 中設定為 TRUE。此值僅適用於 HTTP URL 擷取。
CRYPT_RETRIEVE_MULTIPLE_OBJECTS	如果有的話，擷取多個物件。除非物件標識碼 (OID) CONTEXT_OID_CAPI2_ANY 值，否則所有對象都必須是 pszObjectOid 的值所決定的同質物件類型。
CRYPT_STICKY_CACHE_RETRIEVAL	將 URL 標記為豁免從快取排清。如需詳細資訊，請參閱 INTERNET_CACHE_ENTRY_INFO 中的STICKY_CACHE_ENTRY。
CRYPT_VERIFY_CONTEXT_SIGNATURE	取得所建立內容上的簽章驗證。在此情況下，pszObjectOid 必須是非 NULL，pvVerify 指向簽署者憑證內容。
CRYPT_VERIFY_DATA_HASH	此旗標未實作。不要使用它。
CRYPT_WIRE_ONLY_RETRIEVAL	只從線路擷取編碼位。不使用 URL 快取。

[in] dwTimeout

指定要等候擷取的最大毫秒數。如果指定零的值，則此函式不會逾時。如果 URL 配置 file:///，則不會使用此參數。

[out] ppvObject

所傳回物件的指標位址。傳回型別可以是 pszObjectOid 中顯示的其中一種支持類型。

[in] hAsyncRetrieve

此參數是保留的，而且必須設定為 NULL。

[in, optional] pCredentials

不使用這個參數。

[in, optional] pvVerify

驗證物件的指標。這個物件是 dwRetrievalFlags 參數的函式 。如果 dwRetrievalFlags 已CRYPT_VERIFY_CONTEXT_SIGNATURE，則為 NULL，表示呼叫端對取得簽署者的憑證內容或索引不感興趣。

[in] pAuxInfo

CRYPT_RETRIEVE_AUX_INFO 結構的選擇性指標。如果不是 NULL ，而且已設定結構的 cbSize 成員，此參數會傳回上次成功擷取線路的時間。

傳回值

如果函式成功，則傳回值為非零 (TRUE) 。

如果函式失敗，則傳回值為零， (FALSE) 。

備註

遠程物件擷取管理員會公開兩個提供者模型。其中一個是配置提供者模型，允許 URL 配置所定義的可安裝通訊協定提供者，也就是 ldap、HTTP、ftp 或檔案。配置提供者進入點與 CryptRetrieveObjectByUrl 函式相同;不過，傳回的 *ppvObject 一律是編碼位的計數陣列， (每個擷取) 一個物件。

第二個提供者模型是內容提供者模型，可讓您根據擷取的編碼位，將內容句柄 (物件) 的可安裝建立者。這些會根據呼叫 CryptRetrieveObjectByUrl 中指定的物件標識碼 (OID) 來分派。

可以擷取個別的 PKI 物件，例如憑證、信任清單、撤銷清單、PKCS #7 訊息和多個同質物件。從 Windows Vista 搭配 Service Pack 1 (SP1) 和 Windows Server 2008 開始，已強化 “HTTP：” 和 “ldap：” 擷取的安全性。此函式支援 “HTTP：” 和 “ldap：” URL 配置，以及新定義的配置。

Windows XP： “ftp：” 不支持網络擷取。

注意根據預設，網路擷取不支援「file：“。

注意

wincrypt.h 標頭會根據 UNICODE 預處理器常數的定義，將 CryptRetrieveObjectByUrl 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Cryptnet.lib
Dll	Cryptnet.dll

另請參閱

CryptGetObjectUrl

共用方式為

CryptRetrieveObjectByUrlA 函式 (wincrypt.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源