Função CryptEncodeObjectEx (wincrypt.h)
A função CryptEncodeObjectEx codifica uma estrutura do tipo indicado pelo valor do parâmetro lpszStructType . Essa função oferece uma melhoria significativa de desempenho em relação a CryptEncodeObject , dando suporte à alocação de memória com o valor CRYPT_ENCODE_ALLOC_FLAG .
Sintaxe
BOOL CryptEncodeObjectEx(
[in] DWORD dwCertEncodingType,
[in] LPCSTR lpszStructType,
[in] const void *pvStructInfo,
[in] DWORD dwFlags,
[in] PCRYPT_ENCODE_PARA pEncodePara,
[out] void *pvEncoded,
[in, out] DWORD *pcbEncoded
);
Parâmetros
[in] dwCertEncodingType
O tipo de codificação de certificado e o tipo de codificação de mensagem a serem usados para codificar o objeto. Esse parâmetro pode ser uma combinação de um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Especifica a codificação de mensagens PKCS 7. |
|
Especifica a codificação de certificado X.509. |
[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á um identificador inteiro para o tipo da estrutura especificada. Caso contrário, esse parâmetro é um ponteiro para uma cadeia de caracteres terminada em nulo que contém a representação de cadeia de caracteres do OID.
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] pvStructInfo
Um ponteiro para a estrutura a ser codificada. A estrutura deve ser do tipo especificado por lpszStructType.
[in] dwFlags
Especifica opções para a codificação. Esse parâmetro pode ser zero ou uma combinação de um ou mais dos valores a seguir.
[in] pEncodePara
Um ponteiro para uma estrutura CRYPT_ENCODE_PARA que contém informações de codificação. Este parâmetro pode ser NULL.
Se pEncodePara ou o membro pfnAlloc do pEncodePara for NULL, LocalAlloc será usado para a alocação e LocalFree deverá ser chamado para liberar a memória.
Se pEncodePara e o membro pfnAlloc do pEncodePara não forem NULL, a função apontada pelo membro pfnAlloc da estrutura de CRYPT_ENCODE_PARA apontada por pEncodePara será chamada para a alocação. A função apontada pelo membro pfnFree do pEncodePara deve ser chamada para liberar a memória.
[out] pvEncoded
Um ponteiro para um buffer para receber a estrutura codificada. O tamanho desse buffer é especificado no parâmetro pcbEncoded . 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 pcbEncoded.
Esse parâmetro pode ser NULL para recuperar o tamanho do buffer para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
Se dwFlags contiver o sinalizador CRYPT_ENCODE_ALLOC_FLAG , pvEncoded 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 pvEncoded, pvEncoded não pode ser NULL.
[in, out] pcbEncoded
Um ponteiro para uma variável DWORD que contém o tamanho, em bytes, do buffer apontado pelo parâmetro pvEncoded . Quando a função retorna, a variável apontada pelo parâmetro pcbEncoded contém o número de bytes alocados e codificados armazenados no buffer.
Quando dwFlags contém o sinalizador CRYPT_ENCODE_ALLOC_FLAG , pcbEncoded é o endereço de um ponteiro para o valor DWORD atualizado.
Retornar valor
Retornará diferente de zero se tiver êxito ou zero caso contrário.
Para obter informações de erro estendidas, chame GetLastError. A tabela a seguir mostra alguns códigos de erro possíveis que podem ser retornados de GetLastError quando CryptEncodeObjectEx falha.
| Código de retorno | Descrição |
|---|---|
|
Um erro foi encontrado durante a codificação. |
|
Não foi possível encontrar uma função de codificação para dwCertEncodingType e lpszStructType especificados. |
|
Se o buffer especificado pelo parâmetro pvEncoded 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 pcbEncoded. |
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.
CryptEncodeObjectEx primeiro procura uma função de codificação estendida instalável. Se nenhuma função de codificação estendida for encontrada, a função antiga, inexistente e instalável estará localizada.
Quando a codificação direta de IA5String do objeto não for possível, você poderá especificar a codificação punycode definindo o parâmetro dwFlag como o valor CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG . Definir o sinalizador CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG tem efeitos diferentes com base no tipo de estrutura que está sendo codificado conforme especificado pelo valor do parâmetro lpszStructType .
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
- szOID_NAME_CONSTRAINTS
- X509_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 caracteres Unicode fora do conjunto de caracteres ASCII, o nome do host será codificado primeiro em Punycode e, em seguida, codificado como uma cadeia de caracteres IA5String . |
| CERT_ALT_NAME_RFC822_NAME | Se a parte do nome do host do endereço de email contiver caracteres Unicode fora do conjunto de caracteres ASCII, a parte do nome do host do endereço de email será codificada em Punycode. O endereço de email resultante é codificado como uma cadeia de caracteres IA5String . |
| CERT_ALT_NAME_URL | Se o nome do host do servidor do URI contiver caracteres Unicode fora do conjunto de caracteres ASCII, a parte do nome do host do URI será codificada em Punycode. Em seguida, o URI resultante é escapado e a URL é codificada como uma cadeia de caracteres IA5String . |
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_HASHED_URL .
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
- szOID_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
Cada constante X509_UNICODE_NAME na lista abaixo tem um tipo de estrutura associado apontado pelo parâmetro pvStructInfo .
- X509_UNICODE_NAME
Em todos os casos, a codificação punycode do nome do host é executada em uma base de rótulo por rótulo.
Exemplos
O exemplo a seguir mostra a inicialização e a codificação de uma estrutura de X509_NAME usando CryptEncodeObjectEx. Para obter um exemplo que inclui o contexto completo para este exemplo, consulte Exemplo de Programa C: Codificação e Decodificação do ASN.1.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")
#define MY_TYPE (X509_ASN_ENCODING)
void main()
{
//#define moved
//--------------------------------------------------------------------
// Declare and initialize local variables.
char *Cert_Sub_Name ="Test User Name";
//--------------------------------------------------------------------
// Initialize a single RDN structure.
CERT_RDN_ATTR rgNameAttr =
{
"2.5.4.3", // The OID
CERT_RDN_PRINTABLE_STRING, // Type of string
(DWORD)strlen(Cert_Sub_Name)+1, // String length including
// the terminating null character
(BYTE *)Cert_Sub_Name // Pointer to the string
};
//--------------------------------------------------------------------
// Declare and initialize a structure to include
// the array of RDN structures.
CERT_RDN rgRDN[] =
{
1, // The number of elements in the array
&rgNameAttr // Pointer to the array
};
//--------------------------------------------------------------------
// Declare and initialize a CERT_NAME_INFO
// structure that includes a CERT_RND.
CERT_NAME_INFO CertName =
{
1, // The number of elements in the CERT_RND's array
rgRDN
};
//--------------------------------------------------------------------
// Declare additional variables.
DWORD cbEncoded; // Variable to hold the
// length of the encoded string
BYTE *pbEncoded; // Variable to hold a pointer to the
// encoded buffer
//--------------------------------------------------------------------
// Call CrypteEncodeObjectEx to get
// length to allocate for pbEncoded.
if( CryptEncodeObjectEx(
MY_TYPE, // The encoding/decoding type
X509_NAME,
&CertName,
0,
NULL,
NULL,
&cbEncoded)) // Fill in the length needed for
// the encoded buffer.
{
printf("The number of bytes needed is %d \n",cbEncoded);
}
else
{
printf("The first call to the function failed.\n");
exit(1);
}
if( pbEncoded = (BYTE*)malloc(cbEncoded))
{
printf("Memory for pvEncoded has been allocated.\n");
}
else
{
printf("Memory allocation failed.\n");
exit(1);
}
if(CryptEncodeObjectEx(
MY_TYPE,
X509_NAME,
&CertName,
0,
NULL,
pbEncoded,
&cbEncoded))
{
printf("The structure has been encoded.\n");
}
else
{
printf("Encoding failed.");
exit(1);
}
// Free allocated memory when done.
// ...
if(pbEncoded)
{
free(pbEncoded);
}
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 |