estrutura CERT_CHAIN_FIND_ISSUER_PARA (wincrypt.h)

A estrutura CERT_CHAIN_FIND_BY_ISSUER_PARA contém informações usadas na função CertFindChainInStore para criar cadeias de certificados.

Sintaxe

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;

Membros

cbSize

Contém o tamanho dessa estrutura, em bytes. Esse tamanho não deve ser embutido em código. Ele deve ser definido em tempo de compilação usando o operador sizeof , conforme mostrado no exemplo a seguir.

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

pszUsageIdentifier

Um ponteiro para uma cadeia de caracteres ANSI terminada em nulo que contém o identificador de uso a ser correspondido. Se esse membro for NULL, um certificado com qualquer uso poderá ser uma correspondência.

dwKeySpec

Contém o valor da especificação de chave a ser correspondido. Esse pode ser um dos valores a seguir. Se esse parâmetro for zero, qualquer certificado poderá corresponder.

dwAcquirePrivateKeyFlags

Quando o parâmetro dwFindFlags da função CertFindChainInStore contém CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG, a função CryptAcquireCertificatePrivateKey é chamada para fazer a comparação de chaves públicas. Nesse caso, esse membro é passado como o parâmetro dwFlags da função CryptAcquireCertificatePrivateKey . Para obter valores possíveis para esse membro e seus significados, consulte o parâmetro dwFlags da função CryptAcquireCertificatePrivateKey .

cIssuer

Contém o número de elementos na matriz rgIssuer . Se esse membro for zero, qualquer emissor poderá ser uma correspondência.

rgIssuer

Uma matriz de BLOBs codificados em X.509, ASN.1 (Abstract Syntax Notation One) para corresponder. Se esse membro for NULL ou a função de retorno de chamada retornar TRUE, um novo elemento será adicionado à cadeia para que o certificado tenha uma chave privada com o KeySpec especificado e o uso aprimorado da chave.

pfnFindCallback

Um ponteiro para uma função de retorno de chamada CertChainFindByIssuerCallback que permite que o aplicativo filtre os certificados para os quais as cadeias são criadas. Se esse membro for NULL, uma cadeia será criada para cada certificado encontrado. Se esse membro não for NULL, uma cadeia será criada para o certificado encontrado com base no valor retornado da função de retorno de chamada.

pvFindArg

Um valor definido pelo aplicativo que será passado como o parâmetro pvFindArg da função de retorno de chamada CertChainFindByIssuerCallback apontada pelo membro pfnFindCallback dessa estrutura.

pdwIssuerChainIndex

Um ponteiro para um valor DWORD que recebe o índice baseado em zero da cadeia que corresponde ao emissor. Se esse membro for NULL, ele não será usado.

Se cIssuer for zero, esse membro não será usado.

Esse membro só será definido se a macro CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS estiver definida.

pdwIssuerElementIndex

Um ponteiro para um valor DWORD que recebe o índice baseado em zero do elemento na cadeia do certificado do emissor. Se esse membro for NULL, ele não será usado.

Se cIssuer for zero, esse membro não será usado.

Esse membro é definido como o índice do certificado encontrado mais um para fornecer o índice do certificado do emissor. Por isso, uma cadeia parcial ou um certificado autoassinado que corresponda ao nome BLOB pode fazer com que pdwIssuerElementIndex aponte para além do último certificado na cadeia. Essa situação pode ser detectada comparando o conteúdo de pdwIssuerElementIndex com o membro cElement da estrutura CERT_SIMPLE_CHAIN para garantir que o índice seja válido.

Esse membro só será definido se a macro CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS estiver definida.

Comentários

Os membros pdwIssuerChainIndex e pdwIssuerElementIndex só estarão disponíveis se a macro CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS estiver definida. Se a macro CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS for definida, o aplicativo deverá inicializar todos os campos não utilizados como zero.

Exemplos

O pseudocódigo a seguir mostra como usar os membros pdwIssuerChainIndex e pdwIssuerElementIndex dessa estrutura para acessar o certificado do emissor.

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);
}

Requisitos

Confira também

CertChainFindByIssuerCallback

CertFindChainInStore

CryptAcquireCertificatePrivateKey