Compartilhar via


Função CertGetCTLContextProperty (wincrypt.h)

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