Поделиться через


Функция 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. Поддерживаются следующие схемы:

[in] pszObjectOid

Адрес строки ANSI, завершаемой значением NULL, которая определяет тип объекта для извлечения. Это может быть одно из следующих значений.

Ценность Значение
NULL
КАПЛЯ
Получение одного или нескольких данных BLOB-объектов. Закодированные биты возвращаются в массив больших двоичных объектов. ppvObject — это адрес указателя структуры CRYPT_BLOB_ARRAY, который получает массив BLOB. Если эта структура больше не нужна, необходимо освободить ее, передав адрес этой структуры в функцию CryptMemFree.
CONTEXT_OID_CERTIFICATE
сертификат
Получение одного или нескольких сертификатов.

Если извлекается один объект, ppvObject является адресом указателя структуры CERT_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CERT_CONTEXT на функцию CertFreeCertificateContext.

Если извлекаются несколько объектов, ppvObject — это адрес переменной HCERTSTORE, которая получает дескриптор хранилища, содержащего сертификаты. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore.

CONTEXT_OID_CRL
Список отзыва сертификатов
Получение одного или нескольких списков отзыва сертификатов (CRLS).

Если извлекается один объект, ppvObject является адресом указателя структуры CRL_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CRL_CONTEXT на функцию CertFreeCRLContext.

Если извлекаются несколько объектов, ppvObject является адресом переменной HCERTSTORE HCERTSTORE, которая получает дескриптор хранилища, содержащего crLs. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию CertCloseStore.

CONTEXT_OID_CTL
CTL
Получение одного или нескольких списков доверия сертификатов (CTLs).

Если извлекается один объект, ppvObject является адресом указателя структуры CTL_CONTEXT, который получает контекст. Если этот контекст больше не нужен, его необходимо освободить, передав указатель структуры CTL_CONTEXT на функцию CertFreeCTLContext.

Если извлекаются несколько объектов, ppvObject является адресом переменной HCERTSTORE HCERTSTORE, которая получает дескриптор хранилища, содержащего списки ctls. Если это хранилище больше не требуется, необходимо закрыть его, передав этот дескриптор в функцию 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.

В URL-адресе POST дополнительные двоичные данные и строки заголовков добавляются к базовому URL-адресу в следующем формате:

BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders

В следующем примере показаны дополнительные двоичные данные, разделенные последней меткой косой черты (/) и заголовком Content-Type, разделенным вопросительным знаком (?), добавленным к базовому URL-адресу.

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

При установке этого флага функция CryptRetrieveObjectByUr l анализирует URL-адрес с помощью последней метки косой черты (/) и разделителей вопросительного знака (?). Строка, разделенная меткой косой черты (/), содержит незапечатанный URL-адрес (т. е. URL-адрес обычного текста без escape-символов или escape-последовательностей) и данные Base64, декодированные в двоичную форму, прежде чем передаваться в WinHttpSendRequest функцию в качестве параметра lpOptional. Строка, разделенная вопросительным знаком (?), передается в функцию WinHttpSendReque st в качестве параметра pwszHeaders.

CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL
Выполняет поиск DNS только для записи в указанной строке узла, предотвращая создание ложных ЗАПРОСОВ DNS при разрешении имен узлов. Этот флаг следует использовать при передаче имени узла в отличие от доменного имени.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE
Извлекает индекс записи и имя атрибута для каждого объекта LDAP. Начало каждого возвращаемого BLOB-объекта содержит следующую строку ANSI:

" индекс записив десятичных\0имени атрибута\0"

Если этот флаг задан, pszObjectOid должен быть null, чтобы возвращался BLOB-объект. Этот флаг применяется только к схеме ldap.

CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL
Завершается ошибкой, если область поиска LDAP не задана в URL-адресе. Используется только с ПРОТОКОЛОМ LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL
Цифровой подписывает весь трафик LDAP на сервер и с сервера с помощью протокола проверки подлинности Kerberos. Эта функция обеспечивает целостность, необходимую для некоторых приложений.
CRYPT_NO_AUTH_RETRIEVAL
Предотвращает автоматическую обработку проверки подлинности.
CRYPT_NOT_MODIFIED_RETRIEVAL
Включает получение условного URL-адреса HTTP. Если этот флаг задан, для условного извлечения, возвращающего 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 установлено значение TRUE в pAuxInfo. Это значение применяется только к запросам URL-адреса HTTP.
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

Указывает максимальное число миллисекунда, которое будет ожидать получения. Если задано значение нуля, эта функция не истекает. Этот параметр не используется, если схема 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:" не поддерживается для получения сети.

Примечание По умолчанию "file:" не поддерживается для извлечения сети.
 

Заметка

Заголовок wincrypt.h определяет CryptRetrieveObjectByUrl как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2003 [только классические приложения]
целевая платформа Виндоус
заголовка wincrypt.h
библиотеки Cryptnet.lib
DLL Cryptnet.dll

См. также

CryptGetObjectUrl