структура CERT_CHAIN_FIND_ISSUER_PARA (wincrypt.h)

Статья
03/03/2024

Структура CERT_CHAIN_FIND_BY_ISSUER_PARA содержит сведения, используемые в функции CertFindChainInStore для создания цепочек сертификатов.

Синтаксис

typedef struct _CERT_CHAIN_FIND_BY_ISSUER_PARA {
  DWORD                                  cbSize;
  LPCSTR                                 pszUsageIdentifier;
  DWORD                                  dwKeySpec;
  DWORD                                  dwAcquirePrivateKeyFlags;
  DWORD                                  cIssuer;
  CERT_NAME_BLOB                         *rgIssuer;
  PFN_CERT_CHAIN_FIND_BY_ISSUER_CALLBACK pfnFindCallback;
  void                                   *pvFindArg;
  DWORD                                  *pdwIssuerChainIndex;
  DWORD                                  *pdwIssuerElementIndex;
} CERT_CHAIN_FIND_ISSUER_PARA, *PCERT_CHAIN_FIND_ISSUER_PARA, CERT_CHAIN_FIND_BY_ISSUER_PARA, *PCERT_CHAIN_FIND_BY_ISSUER_PARA;

Члены

cbSize

Содержит размер этой структуры в байтах. Этот размер не должен быть жестко задан. Его следует задать во время компиляции с помощью оператора sizeof , как показано в следующем примере.

CERT_CHAIN_FIND_BY_ISSUER_PARA findParams;
findParams.cbSize = sizeof(CERT_CHAIN_FIND_BY_ISSUER_PARA);

pszUsageIdentifier

Указатель на строку ANSI, завершающуюся значением NULL, которая содержит идентификатор использования для сопоставления. Если этот член имеет значение NULL, сертификат с любым использованием может быть совпадением.

dwKeySpec

Содержит значение спецификации ключа для сопоставления. Это может быть одно из следующих значений. Если этот параметр равен нулю, любой сертификат может совпадать.

Значение	Значение
AT_KEYEXCHANGE 0x01	Ключ можно использовать для шифрования или подписывания в зависимости от алгоритма.
AT_SIGNATURE 0x02	Ключ можно использовать для подписывания.

dwAcquirePrivateKeyFlags

Если параметр dwFindFlags функции CertFindChainInStore содержит CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG, вызывается функция CryptAcquireCertificatePrivateKey для сравнения открытого ключа. В этом случае этот член передается как параметр dwFlags функции CryptAcquireCertificatePrivateKey . Возможные значения этого элемента и их значения см. в параметре dwFlags функции CryptAcquireCertificatePrivateKey .

cIssuer

Содержит количество элементов в массиве rgIssuer . Если этот элемент равен нулю, совпадением может быть любой издатель.

rgIssuer

Массив из X.509, абстрактной синтаксической нотации One (ASN.1 ) с именем издателя для сопоставления. Если этот член имеет значение NULL или функция обратного вызова возвращает значение TRUE, в цепочку для сертификата добавляется новый элемент с закрытым ключом с указанным KeySpec и расширенным использованием ключа.

pfnFindCallback

Указатель на функцию обратного вызова CertChainFindByIssuerCallback , которая позволяет приложению фильтровать сертификаты, для которых создаются цепочки. Если этот член имеет значение NULL, для каждого найденного сертификата создается цепочка. Если этот член не имеет значение NULL, для найденного сертификата будет построена цепочка на основе возвращаемого значения функции обратного вызова.

pvFindArg

Определяемое приложением значение, которое будет передано в качестве параметра pvFindArg функции обратного вызова CertChainFindByIssuerCallback , на которую указывает член pfnFindCallback этой структуры.

pdwIssuerChainIndex

Указатель на значение DWORD , которое получает отсчитываемый от нуля индекс цепочки, соответствующий издателю. Если этот элемент имеет значение NULL, он не используется.

Если cIssuer равно нулю, этот элемент не используется.

Этот элемент определяется только в том случае, если определен макрос CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS .

pdwIssuerElementIndex

Указатель на значение DWORD , которое получает отсчитываемый от нуля индекс элемента в цепочке сертификата издателя. Если этот элемент имеет значение NULL, он не используется.

Если cIssuer равно нулю, этот элемент не используется.

Этому элементу присваивается индекс найденного сертификата плюс один для предоставления индекса сертификата издателя. Из-за этого частичная цепочка или самозаверяющий сертификат, соответствующий имени BLOB, может привести к тому, что pdwIssuerElementIndex будет указывать на последний сертификат в цепочке. Эту ситуацию можно обнаружить, сравнив содержимое pdwIssuerElementIndex с элементом cElementструктуры CERT_SIMPLE_CHAIN , чтобы убедиться, что индекс является допустимым.

Этот элемент определяется только в том случае, если определен макрос CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS .

Члены pdwIssuerChainIndex и pdwIssuerElementIndex доступны, только если определен макрос CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS . Если определен макрос CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS , приложение должно инициализировать все неиспользуемые поля до нуля.

Примеры

В следующем псевдокоде показано, как использовать члены pdwIssuerChainIndex и pdwIssuerElementIndex этой структуры для доступа к сертификату издателя.

CERT_CHAIN_FIND_BY_ISSUER_PARA findParams;
PCCERT_CHAIN_CONTEXT pChainContext = NULL;
DWORD dwChainIndex = 0;
DWORD dwElementIndex = 0;
findParams.pdwIssuerChainIndex = &dwChainIndex;
findParams.pdwIssuerElementIndex = &dwElementIndex;

pChainContext = CertFindChainInStore(
    hCertStore,
    X509_ASN_ENCODING,
    0,
    CERT_CHAIN_FIND_BY_ISSUER,
    (LPVOID)&findParams,
    NULL);
if(pChainContext)
{
    // Make sure the element index is valid.
    if(dwElementIndex < pChainContext->
        rgpChain[dwChainIndex]->cElement)
    {
        PCERT_CHAIN_ELEMENT pIssuerElement;
        pIssuerElement = pChainContext->
            rgpChain[dwChainIndex]->rgpElement[dwElementIndex];
       // ...
    }

    // Free the certificate chain.
    CertFreeCertificateChain(pChainContext);
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Верхняя часть	wincrypt.h

См. также раздел

CertChainFindByIssuerCallback

CertFindChainInStore

CryptAcquireCertificatePrivateKey