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) 仅检索)
文件

[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 是接收包含 CTL 的存储的句柄的 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 的问号 (？) 分隔的 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\0attribute name\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 的值确定的同类对象类型，除非CONTEXT_OID_CAPI2_ANY OID) 值 (对象标识符。
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 消息和多个同类对象。从 Windows Vista Service Pack 1 (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

通过

CryptRetrieveObjectByUrlA 函数 (wincrypt.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源