Função CertSelectCertificateChains (wincrypt.h)

A função CertSelectCertificateChains recupera cadeias de certificados com base nos critérios de seleção especificados.

Sintaxe

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Parâmetros

[in, optional] pSelectionContext

Um ponteiro para o GUID do cenário de seleção de certificado a ser usado para essa chamada.

[in] dwFlags

Sinalizadores para controlar o processo de seleção de certificado. Esse parâmetro pode ser uma combinação de zero ou mais dos seguintes sinalizadores:

Valor	Significado
CERT_SELECT_ALLOW_EXPIRED	Selecione certificados expirados que atendam aos critérios de seleção. Por padrão, os certificados expirados são rejeitados da seleção.
CERT_SELECT_TRUSTED_ROOT	Selecione certificados nos quais o bit de erro no status de confiança da cadeia de certificados não está definido como CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN ou CERT_TRUST_IS_NOT_TIME_VALID. Além disso, os certificados que têm um dos seguintes erros de restrição inválidos não são selecionados: CERT_TRUST_INVALID_POLICY_CONSTRAINTS CERT_TRUST_INVALID_BASIC_CONSTRAINTS CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED	Selecione certificados que não são autoassinados e autoassinados.
CERT_SELECT_HAS_PRIVATE_KEY	Selecione certificados que tenham um valor definido para a propriedade CERT_KEY_PROV_INFO_PROP_ID do certificado.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE	Selecione certificados nos quais o valor do membro dwKeySpec da propriedade CERT_KEY_PROV_INFO_PROP_ID está definido como AT_SIGNATURE. Se essa função estiver sendo chamada como parte de um aplicativo habilitado para CNG e o membro dwKeySpec da propriedade CERT_KEY_PROV_INFO_PROP_ID estiver definido como -1, selecione certificados nos quais o valor da propriedade NCRYPT_KEY_USAGE_PROPERTY da chave privada associada tem a NCRYPT_ALLOW_SIGNING_FLAG definida.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE	Selecione certificados nos quais o valor do membro dwKeySpec da propriedade CERT_KEY_PROV_INFO_PROP_ID está definido como AT_KEYEXCHANGE. Se essa função estiver sendo chamada como parte de um aplicativo habilitado para CNG e o membro dwKeySpec da propriedade CERT_KEY_PROV_INFO_PROP_ID estiver definido como -1, selecione certificados nos quais NCRYPT_ALLOW_DECRYPT_FLAG ou NCRYPT_ALLOW_KEY_AGREEMENT_FLAG está definido.
CERT_SELECT_HARDWARE_ONLY	Selecione certificados nos quais o valor da propriedade PP_IMPTYPE do provedor de chaves privadas associado está definido como CRYPT_IMPL_HARDWARE ou CRYPT_IMPL_REMOVABLE. (Para provedores CNG, NCRYPT_IMPL_TYPE_PROPERTY valor da propriedade DEVE ter o NCRYPT_IMPL_HARDWARE_FLAG ou NCRYPT_IMPL_REMOVABLE_FLAG bit definido). Se essa função estiver sendo chamada como parte de um aplicativo habilitado para CNG, selecione certificados nos quais a propriedade NCRYPT_IMPL_TYPE_PROPERTY está definida como NCRYPT_IMPL_HARDWARE_FLAG ou NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES	Permita a seleção de certificados nos quais o Assunto e o Nome Alt da Entidade contêm as mesmas informações e o valor da extensão do modelo de certificado é equivalente. Por padrão, quando os certificados correspondem a esses critérios, somente o certificado mais recente é selecionado.

[in, optional] pChainParameters

Um ponteiro para uma estrutura CERT_SELECT_CHAIN_PARA para especificar parâmetros para a criação de cadeias. Se NULL, os parâmetros padrão serão usados.

O membro pChainPara da estrutura CERT_SELECT_CHAIN_PARA aponta para uma estrutura CERT_CHAIN_PARA que pode ser usada para habilitar a assinatura forte.

[in] cCriteria

O número de elementos na matriz apontada pela matriz rgpCriteria .

[in, optional] rgpCriteria

Um ponteiro para uma matriz de estruturas de CERT_SELECT_CRITERIA que definem os critérios de seleção. Se esse parâmetro for definido como NULL, o valor do parâmetro cCriteria deverá ser zero.

[in] hStore

O identificador para um repositório do qual selecionar os certificados.

[out] pcSelection

Um ponteiro para um valor DWORD para receber o número de elementos na matriz apontada pelo parâmetro pprgpSelection .

[out] pprgpSelection

Um ponteiro para um ponteiro para um local para receber uma matriz de CERT_CHAIN_CONTEXT estrutura. A função CertSelectCertificateChains retorna apenas cadeias de certificados que correspondem a todos os critérios de seleção. As entradas na matriz são ordenadas pela qualidade, ou seja, a cadeia com a mais alta qualidade é a primeira entrada.

O armazenamento para a matriz é alocado pela função CertSelectCertificateChains . Para liberar a memória alocada, primeiro você deve liberar cada contexto de cadeia individual na matriz chamando a função CertFreeCertificateChain . Em seguida, você deve liberar a memória chamando a função CertFreeCertificateChainList .

Retornar valor

Se a função for bem-sucedida, a função retornará TRUE.

Se a função falhar, ela retornará zero (FALSE). Para obter informações de erro estendidas, chame a função GetLastError .

Nota Se a seleção não produzir nenhum resultado, a função CertSelectCertificateChains retornará TRUE, mas o valor apontado pelo parâmetro pcSelection será definido como zero.

 

Comentários

Os critérios de seleção podem ser especificados por meio do parâmetro dwFlags , por meio do parâmetro rgpCriteria ou por meio de ambos os parâmetros. Se nenhum critério de seleção for especificado, a função terá êxito e retornará cadeias de certificados para todos os certificados no repositório especificados pelo parâmetro hStore .

As cadeias de certificados selecionadas são ordenadas com base na seguinte lógica de preferência:

• Prefira certificados inteligentes cartão certificados em vez de certificados que não são baseados em smart-cartão.
• Prefira certificados que tenham um período de validade mais longo (a data de validade é posterior).)
• Se vários certificados tiverem a mesma data de validade, prefira certificados que foram emitidos mais recentemente.
• Se houver uma gravata, prefira cadeias mais curtas.

Determinados critérios de seleção exigem que uma cadeia de certificados seja criada antes que você possa selecionar esses critérios para uso. Se os certificados intermediários necessários para compilar a cadeia não estiverem disponíveis localmente, uma recuperação de rede será executada para os certificados do emissor. Essa recuperação de rede será executada se o sinalizador CERT_SELECT_TRUSTED_ROOT estiver definido ou para os seguintes critérios:

• CERT_SELECT_BY_ISSUER_NAME
• CERT_SELECT_BY_ISSUER_ATTR
• CERT_SELECT_BY_POLICY_OID

Execute as seguintes ações para habilitar a verificação de assinatura forte:

• Crie uma estrutura CERT_STRONG_SIGN_PARA , especifique os parâmetros de assinatura fortes necessários e defina um ponteiro para a estrutura no membro pStrongSignPara de uma estrutura de CERT_CHAIN_PARA .
• Defina um ponteiro para a estrutura CERT_CHAIN_PARA no membro pChainPara de uma estrutura CERT_SELECT_CHAIN_PARA .
• Defina um ponteiro para a estrutura CERT_SELECT_CHAIN_PARA no parâmetro pChainParameters dessa função (CertSelectCertificateChains).

Quando você habilitar a verificação de assinatura forte, qualquer cadeia de certificados que retorna um erro CERT_TRUST_IS_NOT_SIGNATURE_VALID no campo dwErrorStatus da estrutura CERT_TRUST_STATUS será ignorada. (O parâmetro pprgpSelection aponta para uma estrutura CERT_CHAIN_CONTEXT que, por sua vez, aponta para a estrutura CERT_TRUST_STATUS .) O valor CERT_TRUST_HAS_WEAK_SIGNATURE também é definido para uma assinatura fraca.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 R2 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll

Confira também

CertGetCertificateContextProperty

CertSetCertificateContextProperty