Função CryptDecodeObjectEx (wincrypt.h)
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
[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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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.
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 |
|---|---|
|
Um erro foi encontrado durante a decodificação. |
|
Não foi possível encontrar uma função de decodificação para dwCertEncodingType e lpszStructType especificados. |
|
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
| 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
Cada X509_UNICODE_NAME constante na lista abaixo tem um tipo de estrutura associado que é apontado pelo parâmetro pvStructInfo .
- X509_UNICODE_NAME
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de