Функция 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, которая определяет тип извлекаемого объекта. Это может быть одно из следующих значений.
| Значение | Значение |
|---|---|
|
Получение одного или нескольких больших двоичных объектов данных. Закодированные биты возвращаются в массиве больших двоичных объектов. ppvObject — это адрес указателя структуры CRYPT_BLOB_ARRAY , который получает массив BLOB. Если эта структура больше не нужна, ее необходимо освободить, передав адрес этой структуры в функцию CryptMemFree . |
|
Получение одного или нескольких сертификатов.
Если извлекается один объект, ppvObject — это адрес указателя структуры CERT_CONTEXT , который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CERT_CONTEXT на функцию CertFreeCertificateContext . Если извлекается несколько объектов, ppvObject — это адрес переменной HCERTSTORE , которая получает дескриптор хранилища, содержащего сертификаты. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore . |
|
Получение одного или нескольких списков отзыва сертификатов (CRL).
Если извлекается один объект, ppvObject — это адрес указателя структуры CRL_CONTEXT , который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CRL_CONTEXT на функцию CertFreeCRLContext . Если извлекается несколько объектов, ppvObject — это адрес переменной HCERTSTORE , которая получает дескриптор хранилища, содержащего списки отзыва сертификатов. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore . |
|
Получение одного или нескольких списков доверия сертификатов (CCL).
Если извлекается один объект, ppvObject — это адрес указателя CTL_CONTEXT структуры, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CTL_CONTEXT на функцию CertFreeCTLContext . Если извлекается несколько объектов, ppvObject — это адрес переменной HCERTSTORE , которая получает дескриптор хранилища, содержащего списки CCL. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию 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-адрес кэшируется. |
|
Для получения HTTP используется метод POST вместо метода GET по умолчанию.
В URL-адресе POST дополнительные двоичные данные и строки заголовка добавляются к базовому URL-адресу в следующем формате: BaseURL/OptionalURLEscaped&Base64EncodedAddItionalData?OptionalAdditionalHTTPHeaders В следующем примере показаны дополнительные двоичные данные, разделенные последней косой чертой (/) и заголовком Content-Type, разделенным вопросительным знаком (?), добавленным к базовому URL-адресу.
Если этот флаг установлен, функция CryptRetrieveObjectByUrl анализирует URL-адрес с помощью разделителей последней косой черты (/) и вопросительного знака (?). Строка, разделенная знаком косой черты (/), содержит неэкранированный URL-адрес (то есть URL-адрес обычного текста без escape-символов или escape-последовательностей) и данные Base64, декодированные в двоичную форму перед передачей в функцию WinHttpSendRequest в качестве параметра lpOptional . Строка, разделенная вопросительным знаком (?), передается в функцию WinHttpSendRequest в качестве параметра pwszHeaders . |
|
Выполняет поиск DNS только для записи A в предоставленной строке узла, предотвращая создание ложных запросов DNS при разрешении имен узлов. Этот флаг следует использовать при передаче имени узла, а не имени домена. |
|
Извлекает начальный индекс и имя атрибута для каждого объекта LDAP. Начало каждого возвращаемого большого двоичного объекта содержит следующую строку ANSI: "entry index in decimal\0attribute name\0" Если этот флаг установлен, pszObjectOid должен иметь значение NULL , чтобы возвращался большой двоичный объект. Этот флаг применяется только к схеме ldap. |
|
Сбой, если область поиска LDAP не задано значение base в URL-адресе. Используйте только с LDAP. |
|
Цифровой подписывает весь трафик LDAP на сервер и с сервера с помощью протокола проверки подлинности Kerberos. Эта функция обеспечивает целостность, необходимую для некоторых приложений. |
|
Блокирует автоматическую проверку подлинности. |
|
Включает условное извлечение URL-адреса HTTP. Если этот флаг установлен, для условного извлечения, возвращающего HTTP_STATUS_NOT_MODIFIED, функция CryptRetrieveObjectByUrl возвращает значение TRUE , а ppvObject — значение NULL. Если значение pAuxInfo не равно NULL, параметру dwHttpStatusCode присваивается значение HTTP_STATUS_NOT_MODIFIED. В противном случае ppvObject обновляется для успешного извлечения. |
|
Отслеживает сбои и задержки в автономном режиме перед попаданием в провод при последующих извлечениях. Это значение предназначено только для извлечения провода. |
|
Включает получение кэша прокси-сервера для объекта. Если кэш прокси-сервера не был обходить явным образом, параметр fProxyCacheRetrieval в pAuxInfo имеет значение TRUE. Это значение применяется только к извлечениям URL-адресов HTTP. |
|
Извлекает несколько объектов , если доступно. Все объекты должны иметь однородный тип объекта, определяемый значением pszObjectOid, если значение идентификатора объекта (OID) не CONTEXT_OID_CAPI2_ANY. |
|
Помеет URL-адрес как исключенный из кэша. Дополнительные сведения см. в разделе STICKY_CACHE_ENTRY в INTERNET_CACHE_ENTRY_INFO. |
|
Получает проверку подписи в созданном контексте. В этом случае параметр 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 . Если значение не равно NULL и если задан элемент cbSize структуры, этот параметр возвращает время последнего успешного извлечения провода.
Возвращаемое значение
Если функция выполнена успешно, возвращается ненулевое значение (TRUE).
Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE).
Комментарии
Диспетчер удаленного получения объектов предоставляет две модели поставщика. Одним из них является модель поставщика схемы, которая позволяет устанавливать поставщики протоколов в соответствии со схемой URL-адресов, то есть ldap, http, ftp или file. Точка входа поставщика схемы совпадает с функцией CryptRetrieveObjectByUrl ; однако возвращаемый *ppvObject всегда является подсчитываемым массивом закодированных битов (по одному на извлекаемый объект).
Вторая модель поставщика — это модель поставщика контекста, которая позволяет устанавливать создателей дескрипторов контекста (объектов) на основе полученных закодированных битов. Они отправляются на основе идентификатора объекта (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 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Cryptnet.lib |
| DLL | Cryptnet.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по