通过

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
证书
 检索一个或多个证书。

如果要检索单个对象，ppvObject 是接收上下文的 CERT_CONTEXT 结构指针的地址。 不再需要此上下文时，必须通过将 CERT_CONTEXT 结构指针传递给 CertFreeCertificateContext 函数来释放它。

如果要检索多个对象，ppvObject 是接收包含证书的存储句柄的 HCERTSTORE 变量的地址。 不再需要此存储时，必须将此句柄传递给 CertCloseStore 函数来关闭它。
CONTEXT_OID_CRL
CRL
 检索一个或多个 证书吊销列表（CRL）。

如果要检索单个对象，ppvObject 是接收上下文的 CRL_CONTEXT 结构指针的地址。 不再需要此上下文时，必须通过将 CRL_CONTEXT 结构指针传递给 CertFreeCRLContext 函数来释放它。

如果要检索多个对象，ppvObject 是接收包含 CRL 的存储句柄的 HCERTSTORE 变量的地址。 不再需要此存储时，必须将此句柄传递给 CertCloseStore 函数来关闭它。
CONTEXT_OID_CTL
CTL
 检索一个或多个 证书信任列表（CCL）。

如果要检索单个对象，ppvObject 是接收上下文的 CTL_CONTEXT 结构指针的地址。 不再需要此上下文时，必须通过将 CTL_CONTEXT 结构指针传递给 CertFreeCTLContext 函数来释放它。

如果要检索多个对象，ppvObject 是接收包含 CCL 的存储句柄的 HCERTSTORE 变量的地址。 不再需要此存储时，必须将此句柄传递给 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 方法而不是默认 GET 方法进行 HTTP 检索。

在 POST URL 中，其他二进制数据和标头字符串将追加到基 URL 中，格式如下：

BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData？OptionalAdditionalHTTPHeaders

以下示例演示了由最后一个斜杠标记（/）和一个由问号（？）追加到基 URL 的内容类型标头分隔的其他二进制数据。

http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request

设置此标志时，CryptRetrieveObjectByUrl 函数使用最后一个斜杠标记（/）和问号（？）分隔符分析 URL。 字符串由斜杠标记（/）分隔，包含一个未转义的 URL（即，不带转义字符或转义序列的纯文本 URL）和 Base64 数据在传递给 WinHttpSendRequest 函数作为 lpOptional 参数之前解码为二进制形式。 用问号（？）分隔的字符串作为 pwszHeaders 参数传递给 WinHttpSendRequest 函数。
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL
 对提供的主机字符串执行仅限 A 记录的 DNS 查找，防止解析主机名时生成虚假 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
 启用对象的代理缓存检索。 如果未显式绕过代理缓存，fProxyCacheRetrieval 设置为 pAuxInfo中的 true TRUE。 此值仅适用于 HTTP URL 检索。
CRYPT_RETRIEVE_MULTIPLE_OBJECTS
 检索多个对象（如果可用）。 除非 CONTEXT_OID_CAPI2_ANY 对象标识符（OID）值，否则所有对象都必须是由 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 消息和多个同质对象。 从 Service Pack 1（SP1）和 Windows Server 2008 的 Windows Vista 开始，已强化“http：”和“ldap：”检索的安全性。 此函数支持“http：”和“ldap：”URL 方案以及新定义的方案。

Windows XP：不支持 “ftp：”进行网络检索。

注意 默认情况下，网络检索不支持“file：”。
 

注意

wincrypt.h 标头将 CryptRetrieveObjectByUrl 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
目标平台 窗户
标头 wincrypt.h
库 Cryptnet.lib
DLL Cryptnet.dll

另请参阅

CryptGetObjectUrl