Función CryptDecodeObjectEx (wincrypt.h)
La función CryptDecodeObjectEx descodifica una estructura del tipo indicado por el parámetro lpszStructType . CryptDecodeObjectEx ofrece una mejora significativa del rendimiento de CryptDecodeObject al admitir la asignación de memoria con el valor de CRYPT_DECODE_ALLOC_FLAG.
Sintaxis
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
Tipo de codificación usada. Siempre es aceptable especificar los tipos de codificación de certificados y mensajes al combinarlos con una operación OR bit a bit, como se muestra en el ejemplo siguiente:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
Los tipos de codificación definidos actualmente son:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] lpszStructType
Puntero a un identificador de objeto (OID) que define el tipo de estructura. Si la palabra de orden alto del parámetro lpszStructType es cero, la palabra de orden bajo especifica el identificador entero para el tipo de la estructura especificada. De lo contrario, este parámetro es un puntero largo a una cadena terminada en null.
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] pbEncoded
Puntero a los datos que se van a descodificar. La estructura debe ser del tipo especificado por lpszStructType.
[in] cbEncoded
Número de bytes a los que apunta pbEncoded. Este es el número de bytes que se van a descodificar.
[in] dwFlags
Este parámetro puede ser una o varias de las marcas siguientes. Las marcas se pueden combinar mediante una operación OR bit a bit.
| Valor | Significado |
|---|---|
|
La función de descodificación denominada asigna memoria para la estructura descodificada. Se devuelve un puntero a la estructura asignada en pvStructInfo.
Si pDecodePara o el miembro pfnAlloc de pDecodePara es NULL, se llama a LocalAlloc para la asignación y se debe llamar a LocalFree para liberar la memoria. Si pDecodePara y el miembro pfnAlloc de pDecodePara no son NULL, se llama a la función a la que apunta pfnAlloc para la asignación y se debe llamar a la función a la que apunta el miembro pfnFree de pDecodePara para liberar la memoria. |
|
Esta marca es aplicable para habilitar la descodificació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. |
|
Esta marca se puede establecer para habilitar una optimización "sin copia". Esta optimización actualiza los miembros pvStructInfo para que apunten al contenido que reside en pbEncoded en lugar de realizar una copia del contenido y anexarlo a pvStructInfo. La aplicación que realiza la llamada debe asignar menos memoria y la ejecución es más rápida porque no se realiza una copia. Tenga en cuenta que al realizar la descodificación "sin copia", pbEncoded no se puede liberar hasta que pvStructInfo se libere. |
|
Esta marca es aplicable al descodificar X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE o X509_UNICODE_ANY_STRING. De forma predeterminada, CERT_RDN_T61_STRING valores codificados se descodifican inicialmente como UTF8. Si se produce un error en la descodificación UTF8, el valor se descodifica como caracteres de ocho bits. Si se establece esta marca, omite el intento inicial de descodificar el valor como UTF8 y descodifica el valor como caracteres de ocho bits. |
|
De forma predeterminada, el contenido del búfer al que apunta pbEncoded incluyó el contenido firmado y la firma. Si se establece esta marca, el búfer solo incluye el contenido "que se va a firmar". Esta marca se aplica a objetos X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED y X509_KEYGEN_REQUEST_TO_BE_SIGNED. |
|
Cuando se establece esta marca, las cadenas OID se asignan en Crypt32.dll y se comparten en lugar de copiarse en la estructura de datos devuelta. Esta marca se puede establecer si Crypt32.dll no se descarga antes de que se descargue el autor de la llamada. |
|
De forma predeterminada, los bytes de firma se invierten. Si se establece esta marca, esta inversión de bytes se impide. |
[in] pDecodePara
Puntero a una estructura de CRYPT_DECODE_PARA que contiene información de párrafo de descodificación. Si pDecodePara se establece en NULL, se usa LocalAlloc y LocalFree para asignar y liberar memoria. Si pDecodePara apunta a una estructura de CRYPT_DECODE_PARA , esa estructura pasa funciones de devolución de llamada para asignar y liberar memoria. Estas funciones de devolución de llamada invalidan la asignación de memoria predeterminada de LocalAlloc y LocalFree.
[out] pvStructInfo
Si se establece el CRYPT_ENCODE_ALLOC_FLAG dwFlags , pvStructInfo 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 *pvStructInfo, pvStructInfo nunca debe ser NULL.
Si no se establece CRYPT_ENCODE_ALLOC_FLAG, pvStructInfo es un puntero a un búfer que recibe la estructura descodificada. 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 pcbStructInfo.
Este parámetro puede ser NULL para recuperar el tamaño de esta información con fines de asignación de memoria. Para obtener más información, vea Recuperar datos de longitud desconocida.
[in, out] pcbStructInfo
Puntero a una variable DWORD que contiene el tamaño, en bytes, del búfer al que apunta el parámetro pvStructInfo . Cuando la función devuelve, el valor DWORD contiene el número de bytes almacenados en el búfer. El tamaño contenido en la variable a la que apunta pcbStructInfo puede indicar un tamaño mayor que la estructura descodificada porque la estructura descodificada puede incluir punteros a datos auxiliares. Este tamaño es la suma del tamaño necesario para la estructura descodificada y los datos auxiliares.
Cuando se establece CRYPT_DECODE_ALLOC_FLAG, la función no utiliza el valor inicial de *pcbStructInfo y, de vuelta, *pcbStructInfo contiene el número de bytes asignados para pvStructInfo.
Valor devuelto
Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero (TRUE).
Si se produce un error en la función, devuelve cero (FALSE). Para obtener información de error extendida, llame a GetLastError. En la tabla siguiente se muestran algunos códigos de error posibles.
| Código devuelto | Descripción |
|---|---|
|
Error al descodificar. |
|
No se encontró una función de descodificación para dwCertEncodingType y lpszStructType especificados. |
|
Si el búfer especificado por el parámetro pvStructInfo no es lo suficientemente grande como para contener los datos devueltos, la función establece el código de ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en la variable a la que apunta pcbStructInfo. |
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/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.
Cada constante de la lista siguiente tiene un tipo de estructura asociado al que apunta el parámetro pvStructInfo . La estructura a la que 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
- X509_NAME_CONSTRAINTS
- szOID_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 una cadena IA5String codificada en Punycode, se convierte en el equivalente Unicode. |
| CERT_ALT_NAME_RFC822_NAME | Si la parte del nombre de host de la dirección de correo electrónico contiene una cadena IA5String codificada en Punycode, se convierte en su equivalente Unicode. |
| CERT_ALT_NAME_URL | El URI se descodifica. Si el nombre de host del servidor del URI contiene una cadena IA5String codificada en Punycode, la cadena de nombre de host se descodifica en el equivalente Unicode. |
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_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_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
Ejemplos
Para obtener un ejemplo que usa esta función, vea Ejemplo de programa C: Codificación y descodificación de ASN.1.
Requisitos
| 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 |