Função CryptDecodeObjectEx (wincrypt.h)

  • Artigo

A função CryptDecodeObjectEx decodifica uma estrutura do tipo indicado pelo parâmetro lpszStructType . CryptDecodeObjectEx oferece uma melhoria significativa de desempenho em Relação a CryptDecodeObject , dando suporte à alocação de memória com o valor CRYPT_DECODE_ALLOC_FLAG.

Sintaxe

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

Parâmetros

[in] dwCertEncodingType

O tipo de codificação usado. É 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 ( identificador de objeto ) que define o tipo de estrutura. Se a palavra de alta ordem do parâmetro lpszStructType for zero, a palavra de baixa ordem 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 os dados a serem decodificados. A estrutura deve ser do tipo especificado por lpszStructType.

[in] cbEncoded

O número de bytes apontados por pbEncoded. Esse é o número de bytes a serem decodificados.

[in] dwFlags

Esse parâmetro pode ser um ou mais dos sinalizadores a seguir. Os sinalizadores podem ser combinados usando uma operação OR bit a bit.

Valor Significado
CRYPT_DECODE_ALLOC_FLAG
 A função chamada de decodificação aloca memória para a estrutura decodificada. Um ponteiro para a estrutura alocada é retornado em pvStructInfo.

Se pDecodePara ou o membro pfnAlloc do pDecodePara for NULL, LocalAlloc será chamado para a alocação e LocalFree deverá ser chamado para liberar a memória.

Se pDecodePara e o membro pfnAlloc do pDecodePara não forem NULL, a função apontada por pfnAlloc será chamada para a alocação e a função apontada pelo membro pfnFree do pDecodePara deverá ser chamada para liberar a memória.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
 Esse sinalizador é aplicável para habilitar a decodificação punycode de valores de cadeia de caracteres Unicode. Para obter mais informações, consulte Comentários.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse sinalizador.
CRYPT_DECODE_NOCOPY_FLAG
 Esse sinalizador pode ser definido para habilitar uma otimização "sem cópia". Essa otimização atualiza os membros pvStructInfo para apontar para o conteúdo que reside no pbEncoded em vez de fazer uma cópia do conteúdo e acrescentá-lo a pvStructInfo. O aplicativo de chamada precisa alocar menos memória e a execução é mais rápida porque uma cópia não é feita. Observe que, ao executar a decodificação "sem cópia", 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 estiver 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.

[in] pDecodePara

Um ponteiro para uma estrutura CRYPT_DECODE_PARA que contém informações de parágrafo de decodificação. Se pDecodePara estiver definido como NULL, LocalAlloc e LocalFree serão usados para alocar e liberar memória. Se pDecodePara apontar para uma estrutura CRYPT_DECODE_PARA , essa estrutura passará funções de retorno de chamada para alocar e liberar memória. Essas funções de retorno de chamada substituem a alocação de memória padrão de LocalAlloc e LocalFree.

[out] pvStructInfo

Se o CRYPT_ENCODE_ALLOC_FLAG dwFlags estiver definido, pvStructInfo não será um ponteiro para um buffer, mas será o endereço de um ponteiro para o buffer. Como a memória é alocada dentro da função e o ponteiro é armazenado em *pvStructInfo, pvStructInfo nunca deve ser NULL.

Se CRYPT_ENCODE_ALLOC_FLAG não estiver definido, pvStructInfo será um ponteiro para um buffer que recebe 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 uma variável DWORD que contém o tamanho, em bytes, do buffer apontado pelo parâmetro pvStructInfo . Quando a função retorna, o valor DWORD contém o número de bytes armazenados no buffer. O tamanho contido na variável apontada por pcbStructInfo pode indicar um tamanho maior que a estrutura decodificada porque a estrutura decodificada pode incluir ponteiros para dados auxiliares. Esse tamanho é a soma do tamanho necessário para a estrutura decodificada e os dados auxiliares.

Quando CRYPT_DECODE_ALLOC_FLAG é definido, o valor inicial de *pcbStructInfo não é usado pela função e, no retorno, *pcbStructInfo contém o número de bytes alocados para pvStructInfo.

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser um pouco 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 se encaixem 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, a função retornará diferente de zero (TRUE).

Se a função falhar, ela retornará zero (FALSE). Para obter informações de erro estendidas, chame GetLastError. A tabela a seguir mostra alguns códigos de erro possíveis.

Código de retorno Descrição
CRYPT_E_BAD_ENCODE
 Um erro foi encontrado durante a decodificação.
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 de ASN.1 (Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Codificação/Decodificação de Valores Retornados do 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 é retido.

Cada constante na lista abaixo tem um tipo de estrutura associado apontado pelo parâmetro pvStructInfo . A estrutura apontada, direta ou indiretamente, tem uma referência a uma estrutura CERT_ALT_NAME_ENTRY .

  • X509_ALTERNATE_NAME
  • szOID_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_KEY_ID2
  • szOID_AUTHORITY_KEY_IDENTIFIER2
  • szOID_CRL_DIST_POINTS
  • X509_CRL_DIST_POINTS
  • szOID_CROSS_CERT_DIST_POINTS
  • X509_CROSS_CERT_DIST_POINTS
  • szOID_ISSUER_ALT_NAME
  • szOID_ISSUER_ALT_NAME2
  • szOID_ISSUING_DIST_POINT
  • X509_ISSUING_DIST_POINT
  • X509_NAME_CONSTRAINTS
  • szOID_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
O sinalizador CRYPT_DECODE_ENABLE_PUNYCODE_FLAG , em conjunto com o valor do membro dwAltNameChoice da estrutura CERT_ALT_NAME_ENTRY , determina a maneira como as cadeias de caracteres são codificadas.
dwAltNameChoice Efeito
CERT_ALT_NAME_DNS_NAME Se o nome do host contiver uma cadeia de caracteres IA5String codificada por Punycode, ele será convertido no equivalente Unicode.
CERT_ALT_NAME_RFC822_NAME Se a parte do nome do host do endereço de email contiver uma cadeia de caracteres IA5String codificada por Punycode, ela será convertida em seu equivalente Unicode.
CERT_ALT_NAME_URL O URI é decodificado. Se o nome do host do servidor do URI contiver uma cadeia de caracteres IA5String codificada por Punycode, a cadeia de caracteres de nome do host será decodificada para o equivalente Unicode.
 

Cada constante na lista abaixo tem um tipo de estrutura associado que é apontado pelo parâmetro pvStructInfo . A estrutura apontada, direta ou indiretamente, tem uma referência a uma estrutura CERT_HASHED_URL .

  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
Ao decodificar o valor da estrutura CERT_HASHED_URL , o URI é decodificado. Se o nome do host contiver um nome de host codificado pelo Punycode, ele será convertido no equivalente unicode.

Cada X509_UNICODE_NAME constante na lista abaixo tem um tipo de estrutura associado que é apontado pelo parâmetro pvStructInfo .

  • X509_UNICODE_NAME
Se o membro pszObjId da estrutura CERT_RDN_ATTR estiver definido como szOID_RSA_emailAddr e o endereço de email no membro Value contiver uma cadeia de caracteres codificada por Punycode, ele será convertido no equivalente Unicode.

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

Cryptdecodeobject

Cryptencodeobject

CryptEncodeObjectEx

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