共用方式為


CryptRetrieveObjectByUrlA 函式 (wincrypt.h)

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 物件的位址。 支援下列設定:

[in] pszObjectOid

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

意義
NULL
BLOB
擷取一或多個數據 BLOB。 編碼的位會在 BLOB 的數位中傳回。 ppvObject 是接收 BLOB 陣列之 CRYPT_BLOB_ARRAY 結構指標的位址。 不再需要此結構時,您必須將這個結構的位址傳遞至 CryptMemFree 函式來釋放它。
CONTEXT_OID_CERTIFICATE
憑證 (certificate)
擷取一或多個憑證。

如果要擷取單一物件, ppvObject 是接收內容 之CERT_CONTEXT 結構指標的位址。 不再需要此內容時,您必須將 CERT_CONTEXT 結構指標傳遞至 CertFreeCertificateContext 函式,以釋放它。

如果要擷取多個物件, ppvObjectHCERTSTORE 變數的位址,可接收包含憑證之存放區的句柄。 不再需要此存放區時,您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。

CONTEXT_OID_CRL
CRL
擷取一或多個 證書吊銷清單 , (CRL) 。

如果要擷取單一物件, ppvObject 是接收內容之 CRL_CONTEXT 結構指標的位址。 不再需要此內容時,您必須將 CRL_CONTEXT 結構指標傳遞至 CertFreeCRLContext 函式來釋放它。

如果要擷取多個物件, ppvObjectHCERTSTORE 變數的位址,可接收包含 CRL 之存放區的句柄。 不再需要此存放區時,您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。

CONTEXT_OID_CTL
Ctl
擷取一或多個 憑證信任清單 , (CCL) 。

如果要擷取單一物件, ppvObject 是接收內容 之CTL_CONTEXT 結構指標的位址。 不再需要此內容時,您必須將 CTL_CONTEXT 結構指標傳遞至 CertFreeCTLContext 函式來釋放它。

如果要擷取多個物件, ppvObjectHCERTSTORE 變數的位址,可接收包含 CCL 之存放區的句柄。 不再需要此存放區時,您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。

CONTEXT_OID_PKCS7
PKCS7
ppvObjectHCERTSTORE 變數的位址,可接收包含訊息中物件的存放區句柄。 不再需要此存放區時,您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_CAPI2_ANY
函式會決定適當的專案
ppvObjectHCERTSTORE 變數的位址,可接收包含物件的存放區句柄。 不再需要此存放區時,您必須將此句柄傳遞至 CertCloseStore 函式來關閉它。
CONTEXT_OID_OCSP_RESP
OCSP 回應
ppvObjectCRYPT_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&Base64EncodedAdditionalDataOptionalAdditionalHTTPHeaders

下列範例顯示最後一個斜線標記 (/) 分隔的其他二進位數據,以及以問號分隔 (?) 附加至基底 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