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 函式，以釋放它。

如果要擷取多個物件， 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