Função CertGetCTLContextProperty (wincrypt.h)

Artigo
03/15/2023

A função CertGetCTLContextProperty recupera uma propriedade estendida de um contexto de CTL ( lista de certificados confiáveis ).

Sintaxe

BOOL CertGetCTLContextProperty(
  [in]      PCCTL_CONTEXT pCtlContext,
  [in]      DWORD         dwPropId,
  [out]     void          *pvData,
  [in, out] DWORD         *pcbData
);

Parâmetros

[in] pCtlContext

Um ponteiro para a estrutura CTL_CONTEXT .

[in] dwPropId

Identifica 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.

Valor	Significado
CERT_ACCESS_STATE_PROP_ID	Tipo de dados para pvData: ponteiro para um 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_ARCHIVED_PROP_ID	Tipo de dados para pvData: NULL 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_AUTO_ENROLL_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna uma cadeia de caracteres Unicode terminada em nulo nomeando o tipo de certificado para o qual o certificado foi registrado automaticamente.
CERT_CTL_USAGE_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna uma matriz de bytes que contém uma estrutura de CTL_USAGE codificada em ASN.1 (Abstract Syntax Notation One).
CERT_DESCRIPTION_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna a propriedade exibida pela interface do usuário do certificado. Essa propriedade permite que o usuário descreva o uso do certificado.
CERT_ENHKEY_USAGE_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna uma matriz de bytes que contém uma estrutura de CERT_ENHKEY_USAGE codificada em ASN.1.
CERT_FRIENDLY_NAME_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna uma cadeia de caracteres Unicode terminada em nulo que contém o nome de exibição da CTL.
CERT_HASH_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna o hash SHA1. Se o hash não existir, ele será calculado usando CryptHashCertificate.
CERT_KEY_CONTEXT_PROP_ID	Tipo de dados para pvData: ponteiro para um CERT_KEY_CONTEXT Retorna uma estrutura CERT_KEY_CONTEXT .
CERT_KEY_IDENTIFIER_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE 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 para pvData: ponteiro para um HCRYPTPROV Retorna o identificador do provedor obtido do CERT_KEY_CONTEXT_PROP_ID.
CERT_KEY_PROV_INFO_PROP_ID	Tipo de dados para pvData: ponteiro para uma estrutura CRYPT_KEY_PROV_INFO Retorna um ponteiro para um CRYPT_KEY_PROV_INFO.
CERT_KEY_SPEC_PROP_ID	Tipo de dados para pvData: ponteiro para um DWORD Retorna um valor DWORD especificando a chave privada obtida de CERT_KEY_CONTEXT_PROP_ID propriedade, 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 para pvData: ponteiro para uma matriz BYTE Retorna o hash MD5. Se o hash não existir, ele será calculado usando CryptHashCertificate.
CERT_NEXT_UPDATE_LOCATION_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna a estrutura de CERT_ALT_NAME_INFO codificada em ASN.1. CERT_NEXT_UPDATE_LOCATION_PROP_ID atualmente é usado apenas com CTLs.
CERT_PVK_FILE_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna um Unicode com terminação nula, cadeia de caracteres largos especificando o nome do arquivo que contém a chave privada associada à chave pública do certificado.
CERT_SHA1_HASH_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna o hash SHA1. Se o hash não existir, ele será calculado usando CryptHashCertificate.
CERT_SIGNATURE_HASH_PROP_ID	Tipo de dados para pvData: ponteiro para uma matriz BYTE Retorna o hash de assinatura. Se o hash não existir, ele será calculado com CryptHashToBeSigned. O comprimento do hash é de 20 bytes para SHA e 16 para MD5.

Para todos os outros identificadores de propriedade, pvData aponta para uma matriz de bytes e não um CRYPT_DATA_BLOB como apontado pelo parâmetro pvData em CertSetCertificateContextProperty.

Para obter mais informações sobre cada identificador de propriedade, consulte a documentação sobre o parâmetro dwPropId em CertSetCertificateContextProperty. CERT_SHA1_HASH_PROP_ID e CERT_NEXT_UPDATE_LOCATION_PROP_ID são as propriedades predefinidas de maior interesse.

[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.

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE.

Erros da função chamada , CryptHashCertificate, podem ser propagados para essa função. 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	A CTL 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.

Requisitos

Requisito	Valor
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

CertEnumCTLContextProperties

CertGetCertificateContextProperty

CertSetCTLContextProperty

CryptHashCertificate

Funções de propriedade estendidas

Compartilhar via