Compartir a través de


Función CryptEncodeObjectEx (wincrypt.h)

La función CryptEncodeObjectEx codifica una estructura del tipo indicado por el valor del parámetro lpszStructType . Esta función ofrece una mejora significativa del rendimiento de CryptEncodeObject al admitir la asignación de memoria con el valor de CRYPT_ENCODE_ALLOC_FLAG .

Sintaxis

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

Tipo de codificación de certificado y tipo de codificación de mensajes que se va a usar para codificar el objeto. Este parámetro puede ser una combinación de uno o varios de los valores siguientes.

Valor Significado
PKCS_7_ASN_ENCODING
65536 (0x10000)
Especifica la codificación de mensajes PKCS 7.
X509_ASN_ENCODING
1 (0x1)
Especifica la codificación de certificados X.509.

[in] lpszStructType

Puntero a un identificador de objeto (OID) que define el tipo de estructura. Si la palabra de orden superior del parámetro lpszStructType es cero, la palabra de orden bajo especifica un identificador entero para el tipo de la estructura especificada. De lo contrario, este parámetro es un puntero a una cadena terminada en null que contiene la representación de cadena del OID.

Para obtener más información sobre las cadenas de identificador de objeto, sus constantes predefinidas y las estructuras correspondientes, vea Constantes para CryptEncodeObject y CryptDecodeObject.

[in] pvStructInfo

Puntero a la estructura que se va a codificar. La estructura debe ser del tipo especificado por lpszStructType.

[in] dwFlags

Especifica las opciones para la codificación. Este parámetro puede ser cero o una combinación de uno o varios de los valores siguientes.

Valor Significado
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
La función de codificación denominada asigna memoria para los bytes codificados. Se devuelve un puntero a los bytes asignados en pvEncoded.
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
Esta marca es aplicable para habilitar la codificación Punycode de valores de cadena Unicode. Para obtener más información, vea la sección Comentarios.

Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Esta marca no se admite.

CRYPT_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG
1073741824 (0x40000000)
Esta marca es aplicable al codificar X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE o X509_UNICODE_ANY_STRING. Si se establece esta marca, los caracteres no se comprueban para determinar si son válidos para el tipo de valor especificado.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG
2147483648 (0x80000000)
Esta marca es aplicable al codificar X509_UNICODE_NAME. Si se establece esta marca y todos los caracteres Unicode son <= 0xFF, el CERT_RDN_T61_STRING se selecciona en lugar del CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG
536870912 (0x20000000)
Esta marca es aplicable al codificar un X509_UNICODE_NAME. Cuando se establece, se selecciona CERT_RDN_UTF8_STRING en lugar de CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_FORCE_UTF8_UNICODE_FLAG
268435456 (0x10000000)
Esta marca es aplicable al codificar un X509_UNICODE_NAME. Cuando se establece, se selecciona CERT_RDN_UTF8_STRING en lugar de CERT_RDN_PRINTABLE_STRING para los tipos de cadena de directorio. Además, esta marca habilita CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG.

[in] pEncodePara

Puntero a una estructura CRYPT_ENCODE_PARA que contiene información de codificación. Este parámetro puede ser NULL.

Si pEncodePara o el miembro pfnAlloc de pEncodePara es NULL, se usa LocalAlloc para la asignación y se debe llamar a LocalFree para liberar la memoria.

Si el miembro pEncodePara y pfnAlloc de pEncodePara no son NULL, se llama a la función a la que apunta el miembro pfnAlloc de la estructura CRYPT_ENCODE_PARA a la que apunta pEncodePara para la asignación. Se debe llamar a la función a la que apunta el miembro pfnFree de pEncodePara para liberar la memoria.

[out] pvEncoded

Puntero a un búfer para recibir la estructura codificada. El tamaño de este búfer se especifica en el parámetro pcbEncoded . Cuando el búfer especificado no es lo suficientemente grande como para recibir la estructura descodificada, la función establece el código ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en la variable a la que apunta pcbEncoded.

Este parámetro puede ser NULL para recuperar el tamaño del búfer con fines de asignación de memoria. Para obtener más información, vea Recuperación de datos de longitud desconocida.

Si dwFlags contiene la marca CRYPT_ENCODE_ALLOC_FLAG , pvEncoded no es un puntero a un búfer, pero es la dirección de un puntero al búfer. Dado que la memoria se asigna dentro de la función y el puntero se almacena en pvEncoded, pvEncoded no puede ser NULL.

[in, out] pcbEncoded

Puntero a una variable DWORD que contiene el tamaño, en bytes, del búfer al que apunta el parámetro pvEncoded . Cuando se devuelve la función, la variable a la que apunta el parámetro pcbEncoded contiene el número de bytes asignados codificados almacenados en el búfer.

Cuando dwFlags contiene la marca CRYPT_ENCODE_ALLOC_FLAG , pcbEncoded es la dirección de un puntero al valor DWORD que se actualiza.

Nota Al procesar los datos devueltos en el búfer, las aplicaciones deben usar el tamaño real de los datos devueltos. El tamaño real puede ser ligeramente menor que el tamaño del búfer especificado en la entrada. (En la entrada, los tamaños del búfer suelen especificarse lo suficientemente grandes como para asegurarse de que los datos de salida más grandes posibles se ajusten al búfer). En la salida, la variable a la que apunta este parámetro se actualiza para reflejar el tamaño real de los datos copiados en el búfer.
 

Valor devuelto

Devuelve un valor distinto de cero si es correcto o cero de lo contrario.

Para obtener información de error extendida, llame a GetLastError. En la tabla siguiente se muestran algunos códigos de error posibles que se pueden devolver desde GetLastError cuando se produce un error en CryptEncodeObjectEx .

Código devuelto Descripción
CRYPT_E_BAD_ENCODE
Error al codificar.
ERROR_FILE_NOT_FOUND
No se encontró una función de codificación para dwCertEncodingType y lpszStructType especificados.
ERROR_MORE_DATA
Si el búfer especificado por el parámetro pvEncoded no es lo suficientemente grande como para contener los datos devueltos, la función establece el código ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en la variable a la que apunta pcbEncoded.
 

Si se produce un error en la función, GetLastError puede devolver un error de codificación y descodificación de sintaxis abstracta uno (ASN.1). Para obtener información sobre estos errores, vea Valores devueltos de codificación y descodificación de ASN.1.

Comentarios

Al codificar un objeto criptográfico mediante la función CryptEncodeObjectEx preferida, se incluye el carácter NULL de terminación. Al descodificar, con la función CryptDecodeObjectEx preferida, no se conserva el carácter NULL de terminación.

CryptEncodeObjectEx busca primero una función de codificación extendida instalable. Si no se encuentra ninguna función de codificación extendida, se encuentra la función anterior, nonextended, instalable.

Cuando no es posible dirigir la codificación IA5String del objeto, puede especificar la codificación Punycode estableciendo el parámetro dwFlag en el valor CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG . Establecer la marca CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG tiene efectos diferentes en función del tipo de estructura que se codifica según lo especificado por el valor del parámetro lpszStructType .

Cada constante de la lista siguiente tiene un tipo de estructura asociado al que apunta el parámetro pvStructInfo . La estructura a la que se apunta, directa o indirectamente, tiene una referencia a una estructura de 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
La marca CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG , junto con el valor del miembro dwAltNameChoice de la estructura CERT_ALT_NAME_ENTRY , determina la manera en que se codifican las cadenas.
dwAltNameChoice Efecto
CERT_ALT_NAME_DNS_NAME Si el nombre de host contiene caracteres Unicode fuera del juego de caracteres ASCII, el nombre de host se codifica primero en Punycode y, a continuación, se codifica como una cadena IA5String .
CERT_ALT_NAME_RFC822_NAME Si la parte del nombre de host de la dirección de correo electrónico contiene caracteres Unicode fuera del juego de caracteres ASCII, la parte del nombre de host de la dirección de correo electrónico se codifica en Punycode. A continuación, la dirección de correo electrónico resultante se codifica como una cadena IA5String .
CERT_ALT_NAME_URL Si el nombre de host del servidor del URI contiene caracteres Unicode fuera del juego de caracteres ASCII, la parte del nombre de host del URI se codifica en Punycode. A continuación, el URI resultante se convierte en escape y, a continuación, la dirección URL se codifica como una cadena IA5String .
 

Cada constante de la lista siguiente tiene un tipo de estructura asociado al que apunta el parámetro pvStructInfo . La estructura a la que se apunta, directa o indirectamente, tiene una referencia a una estructura CERT_HASHED_URL .

  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
Al codificar el valor de la estructura CERT_HASHED_URL , si el nombre de host del servidor del URI contiene caracteres Unicode fuera del conjunto de caracteres ASCII y se establece el CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG , la parte del nombre de host del URI se codifica en Punycode. A continuación, el URI resultante se convierte en escape y, a continuación, la dirección URL se codifica como una cadena IA5String .

Cada X509_UNICODE_NAME constante de la lista siguiente tiene un tipo de estructura asociado al que apunta el parámetro pvStructInfo .

  • X509_UNICODE_NAME
Si el miembro pszObjId de la estructura CERT_RDN_ATTR se establece en szOID_RSA_emailAddr y la dirección de correo electrónico del miembro Value contiene caracteres Unicode fuera del juego de caracteres ASCII, la parte del nombre de host de la dirección de correo electrónico se codifica en Punycode. A continuación, la dirección de correo electrónico resultante se codifica como una cadena IA5String .

En todos los casos, la codificación punycode del nombre de host se realiza por etiqueta.

Ejemplos

En el ejemplo siguiente se muestra cómo inicializar y codificar una estructura de X509_NAME mediante CryptEncodeObjectEx. Para obtener un ejemplo que incluya el contexto completo de este ejemplo, vea Ejemplo de programa C: Codificación y descodificación de 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 Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Crypt32.lib
Archivo DLL Crypt32.dll

Consulte también

CryptDecodeObject

CryptDecodeObjectEx

CryptEncodeObject

Funciones de codificación y descodificación de objetos