Función CryptDecodeObjectEx (wincrypt.h)

  • Artículo

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
Nota Se requiere un certificado o un tipo de codificación de mensajes. X509_ASN_ENCODING es el valor predeterminado. Si se indica ese tipo, se usa. De lo contrario, si se indica el tipo PKCS7_ASN_ENCODING, se usa.
 

[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
CRYPT_DECODE_ALLOC_FLAG
 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.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
 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.
CRYPT_DECODE_NOCOPY_FLAG
 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.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 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.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 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.
CRYPT_DECODE_SHARE_OID_STRING_FLAG
 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.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG
 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.

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

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
CRYPT_E_BAD_ENCODE
 Error al descodificar.
ERROR_FILE_NOT_FOUND
 No se encontró una función de descodificación para dwCertEncodingType y lpszStructType especificados.
ERROR_MORE_DATA
 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
La marca CRYPT_DECODE_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 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
Al descodificar el valor de la estructura CERT_HASHED_URL , el URI se descodifica. Si el nombre de host contiene un nombre de host codificado punycode, se convierte en el equivalente Unicode.

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 una cadena codificada punycode, se convierte en el equivalente Unicode.

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

Consulte también

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

Funciones de codificación y descodificación de objetos