Функция CryptRetrieveObjectByUrlA (wincrypt.h)
Функция CryptRetrieveObjectByUrl извлекает объект инфраструктуры открытого ключа (PKI) из расположения, указанного URL-адресом.
Эти удаленные объекты находятся в кодировке и извлекаются в форме контекста.
Синтаксис
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
Адрес строки ANSI, завершаемой значением NULL, которая определяет тип объекта для извлечения. Это может быть одно из следующих значений.
Ценность | Значение |
---|---|
|
Получение одного или нескольких данных BLOB-объектов. Закодированные биты возвращаются в массив больших двоичных объектов. ppvObject — это адрес указателя структуры CRYPT_BLOB_ARRAY, который получает массив BLOB. Если эта структура больше не нужна, необходимо освободить ее, передав адрес этой структуры в функцию CryptMemFree. |
|
Получение одного или нескольких сертификатов.
Если извлекается один объект, ppvObject является адресом указателя структуры CERT_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CERT_CONTEXT на функцию CertFreeCertificateContext. Если извлекаются несколько объектов, ppvObject — это адрес переменной HCERTSTORE, которая получает дескриптор хранилища, содержащего сертификаты. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore. |
|
Получение одного или нескольких списков отзыва сертификатов (CRLS).
Если извлекается один объект, ppvObject является адресом указателя структуры CRL_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CRL_CONTEXT на функцию CertFreeCRLContext. Если извлекаются несколько объектов, ppvObject является адресом переменной HCERTSTORE HCERTSTORE, которая получает дескриптор хранилища, содержащего crLs. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore. |
|
Получение одного или нескольких списков доверия сертификатов (CTLs).
Если извлекается один объект, ppvObject является адресом указателя структуры CTL_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CTL_CONTEXT на функцию CertFreeCTLContext. Если извлекаются несколько объектов, ppvObject является адресом переменной HCERTSTORE HCERTSTORE, которая получает дескриптор хранилища, содержащего списки ctls. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore. |
|
ppvObject — это адрес переменной HCERTSTORE, которая получает дескриптор хранилища, содержащего объекты из сообщения. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore. |
|
ppvObject — это адрес переменной HCERTSTORE, которая получает дескриптор хранилища, содержащего объекты. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore. |
|
ppvObject — это адрес указателя на структуру CRYPT_BLOB_ARRAY. |
[in] dwRetrievalFlags
Определяет, следует ли использовать кэшированный URL-адрес или URL-адрес, полученный из проводного URL-адреса. Форма, в которой возвращаются объекты, определяется значением pszObjectOid.
Ценность | Значение |
---|---|
|
Проверяет содержимое, полученное url-адресом проводной передачи перед записью URL-адреса в кэш.
Поставщик по умолчанию не поддерживает протокол HTTPS для извлечения AIA. |
|
Это значение не поддерживается. |
|
Извлекает закодированные биты только из кэша URL-адресов. Не используйте провод для получения URL-адреса. |
|
Не сохраняет извлеченные биты в кэше URL-адресов. Если этот флаг не задан, полученный URL-адрес кэшируется. |
|
Использует метод POST вместо метода GET по умолчанию для извлечения HTTP.
В URL-адресе POST дополнительные двоичные данные и строки заголовков добавляются к базовому URL-адресу в следующем формате: BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders В следующем примере показаны дополнительные двоичные данные, разделенные последней меткой косой черты (/) и заголовком Content-Type, разделенным вопросительным знаком (?), добавленным к базовому URL-адресу.
При установке этого флага функция CryptRetrieveObjectByUr l анализирует URL-адрес с помощью последней метки косой черты (/) и разделителей вопросительного знака (?). Строка, разделенная меткой косой черты (/), содержит незапечатанный URL-адрес (т. е. URL-адрес обычного текста без escape-символов или escape-последовательностей) и данные Base64, декодированные в двоичную форму, прежде чем передаваться в WinHttpSendRequest функцию в качестве параметра lpOptional. Строка, разделенная вопросительным знаком (?), передается в функцию WinHttpSendReque st в качестве параметра pwszHeaders. |
|
Выполняет поиск DNS только для записи в указанной строке узла, предотвращая создание ложных ЗАПРОСОВ DNS при разрешении имен узлов. Этот флаг следует использовать при передаче имени узла в отличие от доменного имени. |
|
Извлекает индекс записи и имя атрибута для каждого объекта LDAP. Начало каждого возвращаемого BLOB-объекта содержит следующую строку ANSI: " индекс записив десятичных\0имени атрибута\0" Если этот флаг задан, pszObjectOid должен быть null, чтобы возвращался BLOB-объект. Этот флаг применяется только к схеме ldap. |
|
Завершается ошибкой, если область поиска LDAP не задана в URL-адресе. Используется только с ПРОТОКОЛОМ LDAP. |
|
Цифровой подписывает весь трафик LDAP на сервер и с сервера с помощью протокола проверки подлинности Kerberos. Эта функция обеспечивает целостность, необходимую для некоторых приложений. |
|
Предотвращает автоматическую обработку проверки подлинности. |
|
Включает получение условного URL-адреса HTTP. Если этот флаг задан, для условного извлечения, возвращающего HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl возвращает значение TRUE и ppvObject имеет значение NULL . Если pAuxInfo не NULL, dwHttpStatusCode имеет значение HTTP_STATUS_NOT_MODIFIED. В противном случае ppvObject обновляется для успешного извлечения. |
|
Следите за автономными сбоями и задержками перед нажатием провода на последующие извлечения. Это значение предназначено только для извлечения провода. |
|
Включает извлечение кэша прокси-сервера для объекта. Если кэш прокси-сервера не был явно обходить, fProxyCacheRetrieval установлено значение TRUE в pAuxInfo. Это значение применяется только к запросам URL-адреса HTTP. |
|
Извлекает несколько объектов, если они доступны. Все объекты должны быть однородным типом объекта, определяемым значением pszObjectOid, если значение идентификатора объекта (OID) CONTEXT_OID_CAPI2_ANY. |
|
Теги URL-адреса, исключенного от очистки из кэша. Дополнительные сведения см. в INTERNET_CACHE_ENTRY_INFO STICKY_CACHE_ENTRY. |
|
Получает проверку подписи в созданном контексте. В этом случае pszObjectOid должны быть неnull и pvVerify указывает на контекст сертификата подписывающей стороны. |
|
Этот флаг не реализован. Не используйте его. |
|
Извлекает закодированные биты только из провода. Не использует кэш URL-адресов. |
[in] dwTimeout
Указывает максимальное число миллисекунда, которое будет ожидать получения. Если задано значение нуля, эта функция не истекает. Этот параметр не используется, если схема URL-адреса file:///.
[out] ppvObject
Адрес указателя на возвращаемый объект. Возвращаемый тип может быть одним из поддерживаемых типов, показанных в pszObjectOid.
[in] hAsyncRetrieve
Этот параметр зарезервирован и должен иметь значение NULL.
[in, optional] pCredentials
Этот параметр не используется.
[in, optional] pvVerify
Указатель на объект проверки. Этот объект является функцией параметра dwRetrievalFlags. Можно значение NULL, чтобы указать, что вызывающий объект не заинтересован в получении контекста сертификата или индекса подписывающего объекта, если dwRetrievalFlags CRYPT_VERIFY_CONTEXT_SIGNATURE.
[in] pAuxInfo
Необязательный указатель на структуру CRYPT_RETRIEVE_AUX_INFO. Если параметр не
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ненулевое (TRUE).
Если функция завершается ошибкой, возвращаемое значение равно нулю (FALSE).
Замечания
Диспетчер извлечения удаленных объектов предоставляет две модели поставщика. Одним из них является модель поставщика схем, которая позволяет устанавливать поставщиков протоколов, определенных схемой URL-адресов, то есть ldap, http, ftp или file. Точка входа поставщика схемы совпадает с функцией
Вторая модель поставщика — это модель поставщика контекста, которая позволяет устанавливать создателей дескрипторов контекста (объектов) на основе полученных закодированных битов. Они отправляются на основе идентификатора объекта (OID), указанного в вызове CryptRetrieveObjectByUrl.
Можно получить отдельные объекты PKI, такие как сертификаты, списки доверия, списки отзыва, сообщения PKCS #7 и несколько однородных объектов. Начиная с Windows Vista с пакетом обновления 1 (SP1) и Windows Server 2008, безопасность http:и ldap:" были ужесточены. Эта функция поддерживает схемы URL-адресов http:и ldap:, а также новые определенные схемы.
Windows XP: ftp:" не поддерживается для получения сети.
Заметка
Заголовок wincrypt.h определяет CryptRetrieveObjectByUrl как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
Требование | Ценность |
---|---|
минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
минимальный поддерживаемый сервер | Windows Server 2003 [только классические приложения] |
целевая платформа | Виндоус |
заголовка | wincrypt.h |
библиотеки |
Cryptnet.lib |
DLL | Cryptnet.dll |