Compartilhar via


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
PKCS_7_ASN_ENCODING
65536 (0x10000)
Especifica a codificação de mensagens PKCS 7.
X509_ASN_ENCODING
1 (0x1)
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.

Valor Significado
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
A função de codificação chamada aloca memória para os bytes codificados. Um ponteiro para os bytes alocados é retornado em pvEncoded.
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
Esse sinalizador é aplicável para habilitar a codificaçã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_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG
1073741824 (0x40000000)
Esse sinalizador é aplicável ao codificar X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE ou X509_UNICODE_ANY_STRING. Se esse sinalizador for definido, os caracteres não serão verificados para determinar se são válidos para o tipo de valor especificado.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG
2147483648 (0x80000000)
Esse sinalizador é aplicável ao codificar X509_UNICODE_NAME. Se esse sinalizador estiver definido e todos os caracteres Unicode forem <= 0xFF, o CERT_RDN_T61_STRING será selecionado em vez do CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG
536870912 (0x20000000)
Esse sinalizador é aplicável ao codificar um X509_UNICODE_NAME. Quando definido, CERT_RDN_UTF8_STRING é selecionado em vez de CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_FORCE_UTF8_UNICODE_FLAG
268435456 (0x10000000)
Esse sinalizador é aplicável ao codificar um X509_UNICODE_NAME. Quando definido, CERT_RDN_UTF8_STRING é selecionado em vez de CERT_RDN_PRINTABLE_STRING para tipos de cadeia de caracteres de diretório. Além disso, esse sinalizador habilita CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG.

[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.

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.
 

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
CRYPT_E_BAD_ENCODE
Um erro foi encontrado durante a codificação.
ERROR_FILE_NOT_FOUND
Não foi possível encontrar uma função de codificação para dwCertEncodingType e lpszStructType especificados.
ERROR_MORE_DATA
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
O sinalizador CRYPT_ENCODE_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 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
Ao codificar o valor da estrutura CERT_HASHED_URL , se o nome do host do servidor do URI contiver caracteres Unicode fora do conjunto de caracteres ASCII e o CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG for definido, 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 X509_UNICODE_NAME na lista abaixo tem um tipo de estrutura associado 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 caracteres Unicode fora do conjunto de caracteres ASCII, a parte do nome do host do endereço de email será codificada em Punycode. Em seguida, o endereço de email resultante é codificado como uma cadeia de caracteres IA5String .

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

Confira também

Cryptdecodeobject

CryptDecodeObjectEx

Cryptencodeobject

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