Função CryptDecodeObject (wincrypt.h)

  • Artigo

A função CryptDecodeObject decodifica uma estrutura do tipo indicado pelo parâmetro lpszStructType . O uso de CryptDecodeObjectEx é recomendado como uma API que executa a mesma função com melhorias significativas de desempenho.

Sintaxe

BOOL CryptDecodeObject(
  [in]      DWORD      dwCertEncodingType,
  [in]      LPCSTR     lpszStructType,
  [in]      const BYTE *pbEncoded,
  [in]      DWORD      cbEncoded,
  [in]      DWORD      dwFlags,
  [out]     void       *pvStructInfo,
  [in, out] DWORD      *pcbStructInfo
);

Parâmetros

[in] dwCertEncodingType

Tipo de codificação usada. É sempre aceitável especificar os tipos de codificação de certificado e mensagem combinando-os com uma operação OR bit a bit, conforme mostrado no exemplo a seguir:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Os tipos de codificação definidos no momento são:

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING
Nota Um tipo de codificação de certificado ou mensagem é necessário. X509_ASN_ENCODING é o padrão. Se esse tipo for indicado, ele será usado. Caso contrário, se o tipo PKCS7_ASN_ENCODING for indicado, ele será usado.
 

[in] lpszStructType

Um ponteiro para um OID que define o tipo de estrutura. Se a palavra de alta ordem do parâmetro lpszStructType for zero, a palavra de ordem baixa especificará o identificador inteiro para o tipo da estrutura especificada. Caso contrário, esse parâmetro é um ponteiro longo para uma cadeia de caracteres terminada em nulo.

Para obter mais informações sobre cadeias de caracteres de identificador de objeto, suas constantes predefinidas e estruturas correspondentes, consulte Constantes para CryptEncodeObject e CryptDecodeObject.

[in] pbEncoded

Um ponteiro para a estrutura codificada a ser decodificada.

[in] cbEncoded

Número de bytes apontados por pbEncoded.

[in] dwFlags

Os sinalizadores a seguir são definidos. Eles podem ser combinados com uma operação OR bit a bit.

Valor Significado
CRYPT_DECODE_NOCOPY_FLAG
 Esse sinalizador pode ser definido para indicar que a otimização "sem cópia" está habilitada. Essa otimização, quando aplicável, atualiza o parâmetro pvStructInfo para apontar para o conteúdo que reside em pbEncoded em vez de fazer uma cópia do conteúdo e acrescentá-lo a pvStructInfo. Para casos aplicáveis, menos memória precisa ser alocada pelo aplicativo de chamada e a execução é mais rápida porque uma cópia não está sendo feita. Observe que a compensação ao executar uma decodificação "sem cópia" é que pbEncoded não pode ser liberado até que pvStructInfo seja liberado.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 Esse sinalizador é aplicável ao decodificar X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE ou X509_UNICODE_ANY_STRING. Por padrão, CERT_RDN_T61_STRING valores codificados são inicialmente decodificados como UTF8. Se a decodificação UTF8 falhar, o valor será decodificado como caracteres de oito bits. Se esse sinalizador for definido, ele ignorará a tentativa inicial de decodificar o valor como UTF8 e decodificará o valor como caracteres de oito bits.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 Por padrão, o conteúdo do buffer apontado por pbEncoded incluía o conteúdo assinado e a assinatura. Se esse sinalizador estiver definido, o buffer incluirá apenas o conteúdo "a ser assinado". Esse sinalizador é aplicável a objetos X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED e X509_KEYGEN_REQUEST_TO_BE_SIGNED.
CRYPT_DECODE_SHARE_OID_STRING_FLAG
 Quando esse sinalizador é definido, as cadeias de caracteres OID são alocadas em Crypt32.dll e compartilhadas em vez de serem copiadas para a estrutura de dados retornada. Esse sinalizador poderá ser definido se Crypt32.dll não for descarregado antes que o chamador seja descarregado.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG
 Por padrão, os bytes de assinatura são invertidos. Se esse sinalizador for definido, essa reversão de bytes será inibida.

[out] pvStructInfo

Um ponteiro para um buffer para receber a estrutura decodificada. Quando o buffer especificado não é grande o suficiente para receber a estrutura decodificada, a função define o código ERROR_MORE_DATA e armazena o tamanho do buffer necessário, em bytes, na variável apontada por pcbStructInfo.

Esse parâmetro pode ser NULL para recuperar o tamanho dessas informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

[in, out] pcbStructInfo

Um ponteiro para um valor DWORD que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvStructInfo . Quando a função retorna, esse valor DWORD contém o tamanho dos dados decodificados copiados para pvStructInfo. O tamanho contido na variável apontada por pcbStructInfo pode indicar um tamanho maior que a estrutura decodificada, pois a estrutura decodificada pode incluir ponteiros para outras estruturas. Esse tamanho é a soma do tamanho necessário para a estrutura decodificada e outras estruturas apontadas.

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.
 

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError. Alguns códigos de erro possíveis estão listados na tabela a seguir.

Código de retorno Descrição
CRYPT_E_BAD_ENCODE
 Erro ao decodificar.
ERROR_FILE_NOT_FOUND
 Não foi possível encontrar uma função de decodificação para dwCertEncodingType e lpszStructType especificados
ERROR_MORE_DATA
 Se o buffer especificado pelo parâmetro pvStructInfo 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 pcbStructInfo.
 

Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.

Comentários

Ao codificar um objeto criptográfico usando a função CryptEncodeObjectEx preferencial, o caractere NULL de terminação é incluído. Ao decodificar, usando a função CryptDecodeObjectEx preferencial, o caractere NULL de terminação não é mantido.

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de programa C: codificação e decodificação ASN.1.

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

CryptDecodeObjectEx

Cryptencodeobject

Funções de codificação e decodificação de objeto