CryptRetrieveObjectByUrlW 函数 (wincrypt.h)

  • 项目

CryptRetrieveObjectByUrl 函数从 URL 指定的位置检索公钥基础结构 (PKI) 对象。

这些远程对象采用编码格式，以“上下文”形式检索。

语法

BOOL CryptRetrieveObjectByUrlW(
  [in]           LPCWSTR                  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 是接收包含 CRL 的存储的句柄的 HCERTSTORE 变量的地址。 当不再需要此存储时，必须通过将此句柄传递给 CertCloseStore 函数来关闭它。
CONTEXT_OID_CTL
Ctl
 (CTL) 检索一个或多个 证书信任列表 。

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

如果要检索多个对象， ppvObject 是 HCERTSTORE 变量的地址，该变量接收包含 CTL 的存储的句柄。 当不再需要此存储时，必须通过将此句柄传递给 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 检索的内容。

默认提供程序不支持 HTTPS 协议进行 AIA 检索。
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 (？) 问号分隔的 Content-Type 标头。

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

设置此标志后， CryptRetrieveObjectByUrl 函数使用 /) (的最后一个斜杠标记和问号 ( ) 分隔符来分析 URL。 字符串由斜杠 (/) 分隔，包含一个未转义的 URL (即，一个没有转义字符的纯文本 URL 或转义序列，) 和 Base64 数据解码为二进制形式，然后作为 lpOptional 参数传递给 WinHttpSendRequest 函数。 由问号 (？) 分隔的字符串作为 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
 如果未在 URL 中将 LDAP 搜索范围设置为 base，则失败。 仅与 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。 此值仅适用于 HTTP URL 检索。
CRYPT_RETRIEVE_MULTIPLE_OBJECTS
 检索多个对象（如果可用）。 所有对象都必须是由 pszObjectOid 的值确定的同质对象类型，除非对象 标识符 (OID) 值CONTEXT_OID_CAPI2_ANY。
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

指定等待检索的最大毫秒数。 如果指定了零值，则此函数不会超时。如果 file:/// URL 方案，则不使用此参数。

[out] ppvObject

指向返回对象的指针的地址。 返回类型可以是 pszObjectOid 中显示的支持类型之一。

[in] hAsyncRetrieve

此参数是保留的，必须设置为 NULL。

[in, optional] pCredentials

未使用此参数。

[in, optional] pvVerify

指向验证对象的指针。 此对象是 dwRetrievalFlags 参数的 函数。 如果CRYPT_VERIFY_CONTEXT_SIGNATURE dwRetrievalFlags，则表示调用方对获取签名者的证书上下文或索引不感兴趣，可以为 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 的 Windows Vista (SP1) 和 Windows Server 2008 开始，“http：”和“ldap：”检索的安全性已得到强化。

此函数支持“http：”和“ldap：”URL 方案以及新定义的方案。

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

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

注意

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

要求

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

另请参阅

CryptGetObjectUrl