CertGetCertificateContextProperty function (wincrypt.h)
A função CertGetCertificateContextProperty recupera as informações contidas em uma propriedade estendida de um contexto de certificado.
Sintaxe
BOOL CertGetCertificateContextProperty(
[in] PCCERT_CONTEXT pCertContext,
[in] DWORD dwPropId,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Parâmetros
[in] pCertContext
Um ponteiro para a estrutura CERT_CONTEXT do certificado que contém a propriedade a ser recuperada.
[in] dwPropId
A propriedade a ser recuperada. Os identificadores definidos no momento e o tipo de dados a ser retornado no pvData estão listados na tabela a seguir.
CERT_ACCESS_STATE_PROP_ID
Tipo de dados de pvData: um ponteiro para um valor DWORD .
Retorna um valor DWORD que indica se as operações de gravação no certificado são persistentes. O valor DWORD não será definido se o certificado estiver em um repositório de memória ou em um repositório baseado em registro aberto como somente leitura.
CERT_AIA_URL_RETRIEVED_PROP_ID
Esse identificador é reservado.
CERT_ARCHIVED_KEY_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna um hash de chave criptografada salvo anteriormente para o contexto do certificado.
CERT_ARCHIVED_PROP_ID
Tipo de dados de pvData: NULL. Se a função CertGetCertificateContextProperty retornar true, a ID da propriedade especificada existirá para o CERT_CONTEXT.
Indica que o certificado é ignorado durante enumerações. Um certificado com esse conjunto de propriedades é encontrado com operações de pesquisa explícitas, como aquelas usadas para localizar um certificado com um hash específico ou um número de série. Nenhum dado em pvData está associado a essa propriedade.
CERT_AUTHORITY_INFO_ACCESS_PROP_ID
Esse identificador é reservado.
CERT_AUTO_ENROLL_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma cadeia de caracteres Unicode terminada em nulo que nomeia o tipo de certificado para o qual o certificado foi registrado automaticamente.
CERT_AUTO_ENROLL_RETRY_PROP_ID
Esse identificador é reservado.
CERT_BACKED_UP_PROP_ID
Esse identificador é reservado.
CERT_CA_DISABLE_CRL_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Desabilita a recuperação da CRL ( lista de revogação de certificados ) para certificados usados pela AC (autoridade de certificação ). Se o certificado de AUTORIDADE contiver essa propriedade, ele também deverá incluir a propriedade CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID .
CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Contém a lista de URLs de protocolo de status de certificado online (OCSP) a serem usadas para certificados emitidos pelo certificado de autoridade de certificação. O conteúdo da matriz é o bytes codificados em ASN.1 (Abstract Syntax Notation One ) de uma estrutura X509_AUTHORITY_INFO_ACCESS em que pszAccessMethod é definido como szOID_PKIX_OCSP.
CERT_CROSS_CERT_DIST_POINTS_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Local dos certificados cruzados. Atualmente, esse identificador só é aplicável a certificados e não a CRLs ou CTLs ( listas de confiança de certificado ).
A matriz BYTE contém uma estrutura de CROSS_CERT_DIST_POINTS_INFO codificada em ASN.1 decodificada usando a função CryptDecodeObject com um valor X509_CROSS_CERT_DIST_POINTS para o parâmetro lpszStuctType .
CERT_CTL_USAGE_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma matriz de bytes que contêm uma estrutura de CTL_USAGE codificada em ASN.1.
CERT_DATE_STAMP_PROP_ID
Tipo de dados de pvData: um ponteiro para uma estrutura FILETIME .
Hora em que o certificado foi adicionado ao repositório.
CERT_DESCRIPTION_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna a propriedade exibida pela interface do usuário do certificado. Essa propriedade permite que o usuário descreva o uso do certificado.
CERT_EFS_PROP_ID
Esse identificador é reservado.
CERT_ENHKEY_USAGE_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma matriz de bytes que contêm uma estrutura de CERT_ENHKEY_USAGE codificada em ASN.1. Essa estrutura contém uma matriz de OIDs ( identificadores de objeto de uso avançado de chave), cada um dos quais especifica um uso válido do certificado.
CERT_ENROLLMENT_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Informações de registro da solicitação pendente que contém RequestID, CADNSName, CAName e DisplayName. O formato de dados é definido da seguinte maneira.
| Bytes | Sumário |
|---|---|
| Primeiros 4 bytes | ID de solicitação pendente |
| Próximos 4 bytes | Tamanho de CADNSName, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres CADNSName com caractere nulo de terminação |
| Próximos 4 bytes | Tamanho do CAName, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres CAName com caractere nulo de terminação |
| Próximos 4 bytes | Tamanho de DisplayName, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres DisplayName com o caractere nulo de terminação |
CERT_EXTENDED_ERROR_INFO_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma cadeia de caracteres Unicode terminada em nulo que contém informações de erro estendidas para o contexto do certificado.
CERT_FORTEZZA_DATA_PROP_ID
Esse identificador é reservado.
CERT_FRIENDLY_NAME_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma cadeia de caracteres Unicode terminada em nulo que contém o nome de exibição do certificado.
CERT_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash SHA1. Se o hash não existir, ele será calculado usando a função CryptHashCertificate .
CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID
Tipo de dados de pvData: um ponteiro para um tipo de dados HCRYPTPROV_OR_NCRYPT_KEY_HANDLE .
Retorna a opção HCRYPTPROV ou NCRYPT_KEY_HANDLE .
CERT_HCRYPTPROV_TRANSFER_PROP_ID
Retorna o identificador de chave da API de Criptografia (CAPI) associado ao certificado. O chamador é responsável por liberar o identificador. Ele não será liberado quando o contexto for liberado. O valor da propriedade é removido depois que ele é retornado. Se você chamar essa propriedade em um contexto que tenha uma chave CNG, CRYPT_E_NOT_FOUND será retornado.
CERT_IE30_RESERVED_PROP_ID
Esse identificador é reservado.
CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Hash MD5 da chave pública associada à chave privada usada para assinar esse certificado.
CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Hash MD5 do nome do emissor e do número de série desse certificado.
CERT_KEY_CONTEXT_PROP_ID
Tipo de dados de pvData: um ponteiro para uma estrutura CERT_KEY_CONTEXT .
Retorna uma estrutura CERT_KEY_CONTEXT .
CERT_KEY_IDENTIFIER_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Se não existir, pesquisa a extensão szOID_SUBJECT_KEY_IDENTIFIER. Se isso falhar, um hash SHA1 será feito no membro SubjectPublicKeyInfo do certificado para produzir os valores do identificador.
CERT_KEY_PROV_HANDLE_PROP_ID
Tipo de dados de pvData: um ponteiro para um valor HCRYPTPROV .
Retorna o identificador do provedor obtido de CERT_KEY_CONTEXT_PROP_ID.
CERT_KEY_PROV_INFO_PROP_ID
Tipo de dados de pvData: um ponteiro para uma estrutura CRYPT_KEY_PROV_INFO .
Retorna um ponteiro para uma estrutura CRYPT_KEY_PROV_INFO .
CERT_KEY_SPEC_PROP_ID
Tipo de dados de pvData: um ponteiro para um valor DWORD .
Retorna um valor DWORD que especifica a chave privada obtida de CERT_KEY_CONTEXT_PROP_ID se ela existir. Caso contrário, se CERT_KEY_PROV_INFO_PROP_ID existir, será a origem do dwKeySpec.
CERT_MD5_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash MD5. Se o hash não existir, ele será calculado usando a função CryptHashCertificate .
CERT_NCRYPT_KEY_HANDLE_PROP_ID
Tipo de dados de pvData: um ponteiro para um tipo de dados NCRYPT_KEY_HANDLE .
Retorna uma CERT_NCRYPT_KEY_SPEC escolha quando aplicável.
CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID
Retorna o identificador de chave CNG associado ao certificado. O chamador é responsável por liberar o identificador. Ele não será liberado quando o contexto for liberado. O valor da propriedade é removido depois que ele é retornado. Se você chamar essa propriedade em um contexto que tenha uma chave CAPI (herdada), CRYPT_E_NOT_FOUND será retornado.
CERT_NEW_KEY_PROP_ID
Esse identificador é reservado.
CERT_NEXT_UPDATE_LOCATION_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna a estrutura de CERT_ALT_NAME_INFO codificada em ASN.1.
CERT_NEXT_UPDATE_LOCATION_PROP_ID é usado atualmente apenas com CTLs.
CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID
Esse identificador é reservado.
CERT_OCSP_CACHE_PREFIX_PROP_ID
Esse identificador é reservado.
CERT_OCSP_RESPONSE_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma resposta OCSP codificada para este certificado.
CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID
Tipo de dados de pvData: ponteiro para uma cadeia de caracteres Unicode terminada em nulo.
Retorna uma cadeia de caracteres L"<PUBKEY>/<BITLENGTH>" que representa o algoritmo de chave pública e o comprimento do bit do certificado. Há suporte para os seguintes <algoritmos PUBKEY> :
- L"RSA" (BCRYPT_RSA_ALGORITHM)
- L"DSA" (BCRYPT_DSA_ALGORITHM)
- L"ECDSA" (SSL_ECDSA_ALGORITHM)
CERT_PUBKEY_ALG_PARA_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Para chaves públicas que dão suporte à herança de parâmetro de algoritmo, retorna os parâmetros do Algoritmo PublicKey codificado em ASN.1. Para o DSS (Digital Signature Standard ), retorna os parâmetros codificados usando a função CryptEncodeObject . Essa propriedade será usada somente se CMS_PKCS7 for definido.
CERT_PUBKEY_HASH_RESERVED_PROP_ID
Esse identificador é reservado.
CERT_PVK_FILE_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma cadeia de caracteres largo Unicode terminada em nulo que contém o nome do arquivo que contém a chave privada associada à chave pública do certificado.
CERT_RENEWAL_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash do certificado renovado.
CERT_REQUEST_ORIGINATOR_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna uma cadeia de caracteres Unicode terminada em nulo que contém o nome do computador DNS para a origem da solicitação de contexto de certificado.
CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna um ponteiro para uma estrutura de CERT_POLICIES_INFO codificada que contém as políticas de aplicativo do certificado raiz para o contexto. Essa propriedade pode ser decodificada usando a função CryptDecodeObject com o parâmetro lpszStructType definido como X509_CERT_POLICIES e o parâmetro dwCertEncodingType definido como uma combinação de X509_ASN_ENCODINGor PKCS_7_ASN_ENCODINGbit a bit.
CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID
Esse identificador é reservado.
CERT_SHA1_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash SHA1. Se o hash não existir, ele será calculado usando a função CryptHashCertificate .
CERT_SIGN_HASH_CNG_ALG_PROP_ID
Tipo de dados de pvData: ponteiro para uma cadeia de caracteres Unicode terminada em nulo.
Retorna a cadeia de caracteres L"<SIGNATURE>/<HASH>" que representa a assinatura do certificado. O <valor SIGNATURE> identifica o algoritmo de chave pública CNG. Há suporte para os seguintes algoritmos:
- L"RSA" (BCRYPT_RSA_ALGORITHM)
- L"DSA" (BCRYPT_DSA_ALGORITHM)
- L"ECDSA" (SSL_ECDSA_ALGORITHM)
- L"MD5" (BCRYPT_MD5_ALGORITHM)
- L"SHA1" (BCRYPT_SHA1_ALGORITHM)
- L"SHA256" (BCRYPT_SHA256_ALGORITHM)
- L"SHA384" (BCRYPT_SHA384_ALGORITHM)
- L"SHA512" (BCRYPT_SHA512_ALGORITHM)
- L"RSA/SHA1"
- L"RSA/SHA256"
- L"ECDSA/SHA256"
CERT_SIGNATURE_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash de assinatura. Se o hash não existir, ele será calculado usando a função CryptHashToBeSigned . O comprimento do hash é de 20 bytes para SHA e 16 para MD5.
CERT_SMART_CARD_DATA_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna um ponteiro para dados de cartão inteligentes codificados. Antes de chamar CertGetCertificateContextProperty, você pode usar essa constante para recuperar um certificado de cartão inteligente usando a função CertFindCertificateInStore com o parâmetro pvFindPara definido como CERT_SMART_CARD_DATA_PROP_ID e o parâmetro dwFindType definido como CERT_FIND_PROPERTY.
CERT_SMART_CARD_ROOT_INFO_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna um ponteiro para uma estrutura de CRYPT_SMART_CARD_ROOT_INFO codificada.
CERT_SOURCE_LOCATION_PROP_ID
Esse identificador é reservado.
CERT_SOURCE_URL_PROP_ID
Esse identificador é reservado.
CERT_SUBJECT_DISABLE_CRL_PROP_ID
Esse identificador é reservado.
CERT_SUBJECT_INFO_ACCESS_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna a extensão de acesso de informações do assunto do contexto de certificado como uma estrutura de CERT_SUBJECT_INFO_ACCESS codificada.
CERT_SUBJECT_NAME_MD5_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna um hash MD5 do nome da entidade codificado do contexto do certificado.
CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Esse identificador é reservado.
CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID
Tipo de dados de pvData: ponteiro para um valor DWORD .
Retorna o comprimento, em bits, da chave pública no certificado.
Windows 8 e Windows Server 2012: o suporte para essa propriedade começa.
CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID
Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é especificado no parâmetro pcbData .
Retorna o hash MD5 da chave pública desse certificado.
Para todos os identificadores de propriedade definidos pelo usuário, pvData aponta para uma matriz de valores BYTE .
Para obter mais informações sobre cada identificador de propriedade, consulte a documentação sobre o parâmetro dwPropId em CertSetCertificateContextProperty.
[out] pvData
Um ponteiro para um buffer para receber os dados, conforme determinado por dwPropId. Estruturas apontadas por membros de uma estrutura retornada também são retornadas após a estrutura base. Portanto, o tamanho contido em pcbData geralmente excede o tamanho da estrutura base.
Esse parâmetro pode ser NULL para definir o tamanho das informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
[in, out] pcbData
Um ponteiro para um valor DWORD que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData . Quando a função retorna, o valor DWORD contém o número de bytes a serem armazenados no buffer.
Para obter o tamanho necessário de um buffer em tempo de execução, passe NULL para o parâmetro pvData e defina o valor apontado por esse parâmetro como zero. Se o parâmetro pvData não for NULL e o tamanho especificado em pcbData for menor que o número de bytes necessários para conter os dados, a função falhará, GetLastError retornará ERROR_MORE_DATA e o tamanho necessário será colocado na variável apontada pelo parâmetro pcbData .
Retornar valor
Se a função for bem-sucedida, a função retornará TRUE.
Se a função falhar, ela retornará FALSE. Para obter informações de erro estendidas, chame GetLastError.
Alguns códigos de erro possíveis seguem.
| Código de retorno | Descrição |
|---|---|
|
O certificado não tem a propriedade especificada. |
|
Se o buffer especificado pelo parâmetro pvData não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pcbData. |
Erros da função chamada CryptHashCertificate podem ser propagados para essa função.
Comentários
As propriedades não são armazenadas dentro de um certificado. Normalmente, eles são associados a um certificado depois que a resposta do certificado é recebida e salva com o certificado no repositório. Por motivos de segurança, recomendamos que você valide os valores de propriedade antes de salvá-los e salve apenas propriedades informativas, como o valor CERT_FRIENDLY_NAME_PROP_ID em repositórios de usuários. Todos os outros tipos de propriedade devem ser salvos em repositórios de computadores locais.
Seu código pode usar uma macro para avaliar a classe de hash para um contexto de certificado. Para obter mais informações, consulte CertSetCertificateContextProperty.
Exemplos
Para obter exemplos que usam essa função, consulte Exemplo de programa C: obtenção e definição de propriedades de certificado e exemplo de programa C: listando os certificados em um repositório.
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de