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 |
|---|---|
|
Especifica la codificación de mensajes PKCS 7. |
|
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.
[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.
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 |
|---|---|
|
Error al codificar. |
|
No se encontró una función de codificación para dwCertEncodingType y lpszStructType especificados. |
|
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
| 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
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
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 |