Função CertGetCertificateContextProperty (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 de CERT_CONTEXT do certificado que contém a propriedade a ser recuperada.

[in] dwPropId

A propriedade a ser recuperada. 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 de DWORD .

Retorna um valor DWORD que indica se as operações de gravação no certificado são mantidas. 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 uma chave criptografada salva anteriormente de hash 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 recuperação de de lista de certificados revogados (CRL) para certificados usados pela autoridade de certificação (AC). Se o certificado de autoridade de certificação 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 de Sintaxe Abstrata One (ASN.1) de uma estrutura X509_AUTHORITY_INFO_ACCESS em que pszAccessMethod está 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 listas de confiança de certificado (CTLs).

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 de 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 identificadores de objeto de uso de chave avançado (OIDs), 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	Conteúdo
Primeiros 4 bytes	ID de solicitação pendente
Próximos 4 bytes	Tamanho do CADNSName, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres CADNSName com terminação de caractere nulo
Próximos 4 bytes	Tamanho caname, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres CAName com terminação de caractere nulo
Próximos 4 bytes	Tamanho displayName, em caracteres, incluindo o caractere nulo de terminação, seguido pela cadeia de caracteres DisplayName com terminação de caractere nulo

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á computado 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 de 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, pesquise 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 de 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 de CRYPT_KEY_PROV_INFO.

CERT_KEY_SPEC_PROP_ID

Tipo de dados de pvData: um ponteiro para um valor de DWORD .

Retorna um valor DWORD que especifica a chave privada obtida de CERT_KEY_CONTEXT_PROP_ID se 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á computado 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 opção CERT_NCRYPT_KEY_SPEC 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 atualmente é usado 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 de <PUBKEY>:

• L"RSA" (BCRYPT_RSA_ALGORITHM)
• L"DSA" (BCRYPT_DSA_ALGORITHM)
• L"ECDSA" (SSL_ECDSA_ALGORITHM)

Windows 8 e Windows Server 2012: o suporte para essa propriedade começa.

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 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_ENCODING bit a bit ORPKCS_7_ASN_ENCODING.

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á computado usando a função CryptHashCertificate.

CERT_SHA1_SHA256_HASH_PROP_ID

Tipo de dados de pvData: um ponteiro para uma matriz de valores BYTE . O tamanho dessa matriz é de 52 bytes, 20 bytes para o hash SHA1 e 32 bytes para o hash SHA256.

Retorna uma combinação do hash SHA1 e do hash SHA256. Se o hash não existir, ele será computado usando a função CryptHashCertificate.

CERT_SHA256_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 SHA256. Se o hash não existir, ele será computado 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)

O valor <HASH> identifica o algoritmo de hash CNG. Há suporte para os seguintes algoritmos:

• 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)

Veja a seguir exemplos comuns:

• L"RSA/SHA1"
• L"RSA/SHA256"
• L"ECDSA/SHA256"

Windows 7 e Windows Server 2008 R2: o suporte para essa propriedade começa.

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 inteligente 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 do 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 codificada 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 de 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 no 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 dede comprimento desconhecido.

[in, out] pcbData

Um ponteiro para um DWORD valor que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData. Quando a função retorna, o DWORD valor 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 do que o número de bytes necessários para conter os dados, a função falha, GetLastError retorna ERROR_MORE_DATAe o tamanho necessário é colocado na variável apontada pelo parâmetro pcbData.

Valor de retorno

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

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
CRYPT_E_NOT_FOUND	O certificado não tem a propriedade especificada.
ERROR_MORE_DATA	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.

Observações

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: Obtendo e definindo propriedades de certificado e exemplo de programa C: listando os certificados em um repositório.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Crypt32.lib
de DLL	Crypt32.dll

Consulte também

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

Funções de propriedade estendida