Função CertVerifyCTLUsage (wincrypt.h)
A função CertVerifyCTLUsage verifica se um assunto é confiável para um uso especificado localizando uma CTL ( lista de confiança de certificado ) assinada e válida por tempo com os identificadores de uso que contêm o assunto. A entidade de um certificado pode ser identificada por seu contexto de certificado ou por qualquer identificador exclusivo, como o hash SHA1 do certificado da entidade.
Sintaxe
BOOL CertVerifyCTLUsage(
[in] DWORD dwEncodingType,
[in] DWORD dwSubjectType,
[in] void *pvSubject,
[in] PCTL_USAGE pSubjectUsage,
[in] DWORD dwFlags,
[in, optional] PCTL_VERIFY_USAGE_PARA pVerifyUsagePara,
[in, out] PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus
);
Parâmetros
[in] dwEncodingType
Especifica o tipo de codificação usado. Atualmente, apenas X509_ASN_ENCODING e PKCS_7_ASN_ENCODING estão sendo usados; no entanto, tipos de codificação adicionais podem ser adicionados no futuro. Para qualquer tipo de codificação atual, use
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.
[in] dwSubjectType
Se o parâmetro dwSubjectType estiver definido como CTL_CERT_SUBJECT_TYPE, pvSubject apontará para uma estrutura CERT_CONTEXT . O membro SubjectAlgorithm da estrutura é examinado para determinar a representação da identidade da entidade. Inicialmente, somente hashes SHA1 e MD5 têm suporte como valores para SubjectAlgorithm. A propriedade de hash apropriada é obtida da estrutura CERT_CONTEXT .
Se o parâmetro dwSubjectType estiver definido como CTL_ANY_SUBJECT_TYPE, pvSubject apontará para a estrutura CTL_ANY_SUBJECT_INFO . O membro SubjectAlgorithm dessa estrutura deve corresponder ao tipo de algoritmo da CTL e o membro SubjectIdentifier deve corresponder a uma das entradas CTL.
Se dwSubjectType estiver definido como um dos valores anteriores, dwEncodingType não será usado.
[in] pvSubject
Valor usado em conjunto com o parâmetro dwSubjectType .
[in] pSubjectUsage
Um ponteiro para uma estrutura de CTL_USAGE usada para especificar o uso pretendido do assunto.
[in] dwFlags
Se o CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG não estiver definido, uma CTL cujo tempo não é mais válido em um dos repositórios especificados por rghCtlStore no CTL_VERIFY_USAGE_PARA poderá ser substituído. Quando substituído, o CERT_VERIFY_UPDATED_CTL_FLAG é definido no membro dwFlags de pVerifyUsageStatus. Se esse sinalizador for definido, uma atualização não será feita, mesmo se uma CTL atualizada válida por tempo for recebida para uma CTL que está no repositório e cujo tempo não é mais válido.
Se o CERT_VERIFY_TRUSTED_SIGNERS_FLAG estiver definido, somente os repositórios de signatários especificados por rghSignerStore no CTL_VERIFY_USAGE_PARA serão pesquisados para localizar o signatário. Caso contrário, os repositórios de signatários fornecem fontes adicionais para localizar o certificado do signatário. Para obter mais informações, consulte Comentários.
Se CERT_VERIFY_NO_TIME_CHECK_FLAG estiver definido, as CTLs não serão verificadas quanto à validade do tempo. Caso contrário, eles serão.
Se CERT_VERIFY_ALLOW_MORE_USAGE_FLAG estiver definido, a CTL poderá conter identificadores de uso além daqueles especificados por pSubjectUsage. Caso contrário, a CTL encontrada não conterá nenhum identificador de uso adicional.
[in, optional] pVerifyUsagePara
Um ponteiro para uma estrutura CTL_VERIFY_USAGE_PARA que especifica os repositórios a serem pesquisados para localizar a CTL e os repositórios que contêm signatários CTL aceitáveis. Definir o membro ListIdentifier limita ainda mais a pesquisa.
[in, out] pVerifyUsageStatus
Um ponteiro para uma estrutura CTL_VERIFY_USAGE_STATUS . O membro cbSize da estrutura deve ser definido como o tamanho, em bytes, da estrutura e todos os outros campos devem ser definidos como zero antes que CertVerifyCTLUsage seja chamado. Para obter mais informações, consulte CTL_VERIFY_USAGE_STATUS.
Valor retornado
Se o assunto for confiável para o uso especificado, TRUE será retornado. Caso contrário, FALSE será retornado. GetLastError pode retornar um dos seguintes códigos de erro.
| Valor | Descrição |
|---|---|
|
Nenhuma DLL ou função exportada foi encontrada para verificar o uso do assunto. |
|
A função chamada não pôde fazer um marcar de uso sobre o assunto. |
|
O servidor estava offline; portanto, a função chamada não pôde concluir o marcar de uso. |
|
O assunto não foi encontrado em uma CTL. |
|
Nenhum signatário confiável foi encontrado para verificar a assinatura da mensagem ou da lista de confiança. |
O membro dwError do CTL_VERIFY_USAGE_PARA apontado por pVerifyUsageStatus é definido como o mesmo código de erro.
Comentários
CertVerifyCTLUsage é um dispatcher para funções que podem ser instaladas usando um OID ( identificador de objeto ). Primeiro, ele tenta encontrar uma função OID que corresponda ao primeiro identificador de objeto de uso na estrutura CLT_USAGE apontada por pSubjectUsage. Se isso falhar, ele usará as funções padrão CertDllVerifyCTLUsage .
A função CertDllVerifyCTLUsage no Cryptnet.dll pode ser instalada usando um OID; ele tem as seguintes propriedades:
- Se os repositórios CTL forem especificados por rghCtlStore em pVerifyUsagePara, somente esses repositórios serão pesquisados para localizar uma CTL. Caso contrário, o repositório do sistema de confiança será pesquisado para localizar uma CTL.
- Se CERT_VERIFY_TRUSTED_SIGNERS_FLAG estiver definido, somente os repositórios de signatários especificados por rghSignerStore no pVerifyUsagePara serão pesquisados para localizar o certificado que corresponde ao emissor do signatário e ao número de série. Caso contrário, o repositório da mensagem CTL, os repositórios de signatários especificados por rghSignerStore em pVerifyUsagePara, o repositório do sistema de confiança, o repositório do sistema de AC, o ROOT e os repositórios do sistema SPC ( Software Publisher Certificate ) são pesquisados para localizar o certificado do signatário. Em ambos os casos, a chave pública no certificado encontrado é usada para verificar a assinatura da CTL.
- Se a CTL tiver um membro NextUpdate definido e CERT_VERIFY_NO_TIME_CHECK não estiver definida, ela será verificada quanto à validade do tempo.
- Se a CTL obtida do repositório tiver uma hora que não seja válida, será feita uma tentativa de obter uma versão válida por tempo. A função CertDllVerifyCTLUsage usa a propriedade NextUpdateLocation ou a extensão NextUpdateLocation da CTL ou pesquisa as informações do signatário para obter um atributo NextUpdateLocation .
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |