Función CryptMsgGetParam (wincrypt.h)

Artículo
08/27/2023

La función CryptMsgGetParam adquiere un parámetro de mensaje después de codificar o descodificar un mensaje criptográfico. Se llama a esta función después de la llamada final a CryptMsgUpdate .

Sintaxis

BOOL CryptMsgGetParam(
  [in]      HCRYPTMSG hCryptMsg,
  [in]      DWORD     dwParamType,
  [in]      DWORD     dwIndex,
  [out]     void      *pvData,
  [in, out] DWORD     *pcbData
);

Parámetros

[in] hCryptMsg

Identificador de un mensaje criptográfico.

[in] dwParamType

Indica los tipos de parámetros de datos que se van a recuperar. El tipo de datos que se va a recuperar determina el tipo de estructura que se va a usar para pvData.

Para un mensaje codificado, solo los CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM y CMSG_COMPUTED_HASH_PARAM dwParamTypes son válidos.

Value	Significado
CMSG_ATTR_CERT_COUNT_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el recuento de los certificados de atributo en un mensaje SIGNED o ENVELOPED.
CMSG_ATTR_CERT_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Recupera un certificado de atributo. Para obtener todos los certificados de atributo, llame a CryptMsgGetParam variable dwIndex establecido en 0 el número de atributos menos uno.
CMSG_BARE_CONTENT_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Recupera el contenido codificado de un mensaje criptográfico codificado, sin la capa externa de la estructura CONTENT_INFO. Es decir, solo se devuelve la codificación del campo ContentInfo.content definido de PKCS #7.
CMSG_CERT_COUNT_PARAM	Tipo de datos pvData : puntero a DWORD Devuelve el número de certificados de un mensaje SIGNED o ENVELOPED recibido.
CMSG_CERT_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Devuelve el certificado de un firmante. Para obtener todos los certificados del firmante, llame a CryptMsgGetParam, variando dwIndex de 0 al número de certificados disponibles menos uno.
CMSG_COMPUTED_HASH_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Devuelve el hash calculado de los datos del mensaje. Este tipo es aplicable tanto a la codificación como a la descodificación.
CMSG_CONTENT_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Devuelve todo el mensaje PKCS #7 de un mensaje abierto para codificar. Recupera el contenido interno de un mensaje abierto para descodificar. Si el mensaje está sobres, el tipo interno es data y se ha llamado a CryptMsgControl para descifrar el mensaje, se devuelve el contenido descifrado. Si el tipo interno no es datos, se devuelve el BLOB codificado que requiere una descodificación adicional. Si el mensaje no está sobre y el contenido interno es DATA, los datos devueltos son los octetos del contenido interno. Este tipo es aplicable tanto a la codificación como a la descodificación. Para la descodificación, si el tipo es CMSG_DATA, se devuelven los octetos del contenido; de lo contrario, se devuelve el contenido interno codificado.
CMSG_CRL_COUNT_PARAM	Tipo de datos pvData : puntero a DWORD Devuelve el recuento de CRL en un mensaje recibido, FIRMADO o SOBRED.
CMSG_CRL_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Devuelve una CRL. Para obtener todas las CRL, llame a CryptMsgGetParam, variable dwIndex de 0 al número de CRL disponibles menos uno.
CMSG_ENCODED_MESSAGE	Tipo de datos pvData: puntero a una matriz BYTE Cambia el contenido de un mensaje ya codificado. El mensaje debe descodificarse primero con una llamada a CryptMsgOpenToDecode. A continuación, el cambio en el mensaje se realiza a través de una llamada a CryptMsgControl, CryptMsgCountersign o CryptMsgCountersignEncoded. A continuación, el mensaje se codifica de nuevo con una llamada a CryptMsgGetParam, especificando CMSG_ENCODED_MESSAGE para obtener una nueva codificación que refleje los cambios realizados. Esto se puede usar, por ejemplo, para agregar un atributo de marca de tiempo a un mensaje.
CMSG_ENCODED_SIGNER	Tipo de datos pvData: puntero a una matriz BYTE Devuelve la información del firmante de CMSG_SIGNER_INFO codificada para un firmante de mensajes.
CMSG_ENCRYPTED_DIGEST	Tipo de datos pvData: puntero a una matriz BYTE Devuelve el hash cifrado de una firma. Normalmente se usa para realizar la marca de tiempo.
CMSG_ENCRYPT_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para una estructura de CRYPT_ALGORITHM_IDENTIFIER . Devuelve el algoritmo de cifrado utilizado para cifrar el mensaje.
CMSG_ENVELOPE_ALGORITHM_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para una estructura de CRYPT_ALGORITHM_IDENTIFIER . Devuelve el algoritmo de cifrado utilizado para cifrar un mensaje ENVELOPED.
CMSG_HASH_ALGORITHM_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para una estructura de CRYPT_ALGORITHM_IDENTIFIER . Devuelve el algoritmo hash utilizado para aplicar un algoritmo hash al mensaje cuando se creó.
CMSG_HASH_DATA_PARAM	Tipo de datos pvData: puntero a una matriz BYTE Devuelve el valor hash almacenado en el mensaje cuando se creó.
CMSG_INNER_CONTENT_TYPE_PARAM	Tipo de datos pvData: puntero a una matriz BYTE para recibir una cadena de identificador de objeto terminada en NULL (OID). Devuelve el tipo de contenido interno de un mensaje recibido. Este tipo no es aplicable a los mensajes de tipo DATA.
CMSG_RECIPIENT_COUNT_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el número de destinatarios de transporte de claves de un mensaje recibido ENVELOPED.
CMSG_CMS_RECIPIENT_COUNT_PARAM	Tipo de datos pvData : puntero a DWORD Devuelve el recuento total de todos los destinatarios del mensaje, incluidos el contrato de clave y los destinatarios de la lista de correo.
CMSG_RECIPIENT_INDEX_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el índice del destinatario de transporte de claves utilizado para descifrar un mensaje ENVELOPED. Este valor solo está disponible después de que se haya descifrado un mensaje.
CMSG_CMS_RECIPIENT_INDEX_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el índice del transporte de claves, el acuerdo de clave o el destinatario de la lista de correo que se usa para descifrar un mensaje ENVELOPED.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el índice de la clave cifrada de un destinatario del contrato de clave utilizado para descifrar un mensaje ENVELOPED.
CMSG_RECIPIENT_INFO_PARAM	Tipo de datos pvData: puntero a una matriz BYTE para recibir una estructura CERT_INFO. Devuelve información de certificado sobre el destinatario de un mensaje de transporte de claves. Para obtener información de certificado en todos los destinatarios del mensaje de transporte de claves, llame repetidamente a CryptMsgGetParam, variando dwIndex de 0 al número de destinatarios menos uno. Solo los miembros Issuer, SerialNumber y PublicKeyAlgorithm de la estructura CERT_INFO devueltos están disponibles y válidos.
CMSG_CMS_RECIPIENT_INFO_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CMSG_CMS_RECIPIENT_INFO . Devuelve información sobre un transporte de claves, un contrato de clave o un destinatario de la lista de correo. No se limita a los destinatarios del mensaje de transporte de claves. Para obtener información sobre todos los destinatarios de un mensaje, llame repetidamente a CryptMsgGetParam, variando dwIndex de 0 al número de destinatarios menos uno.
CMSG_SIGNER_AUTH_ATTR_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CRYPT_ATTRIBUTES . Devuelve los atributos autenticados de un firmante de mensajes. Para recuperar los atributos autenticados de un firmante especificado, llame a CryptMsgGetParam con dwIndex igual a ese índice del firmante.
CMSG_SIGNER_CERT_INFO_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir la estructura de CERT_INFO . Devuelve información sobre un firmante de mensajes necesario para identificar el certificado del firmante. El emisor y serialNumber de un certificado se pueden usar para identificar de forma única un certificado para su recuperación. Para recuperar información para todos los firmantes, llame repetidamente a CryptMsgGetParam variable dwIndex de 0 al número de firmantes menos uno. Solo los campos Issuer y SerialNumber de la estructura CERT_INFO devuelto contienen datos válidos disponibles y válidos.
CMSG_SIGNER_CERT_ID_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CERT_ID . Devuelve información sobre un firmante de mensajes necesario para identificar la clave pública del firmante. Podría tratarse del emisor y el valor de SerialNumber de un certificado, un KeyID o un HashId. Para recuperar información para todos los firmantes, llame a CryptMsgGetParam variable dwIndex de 0 al número de firmantes menos uno.
CMSG_SIGNER_COUNT_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el número de firmantes de un mensaje SIGNED recibido.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir la estructura de CRYPT_ALGORITHM_IDENTIFIER . Devuelve el algoritmo hash utilizado por un firmante del mensaje. Para obtener el algoritmo hash de un firmante especificado, llame a CryptMsgGetParam con dwIndex igual a ese índice del firmante.
CMSG_SIGNER_INFO_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CMSG_SIGNER_INFO . Devuelve información sobre un firmante de mensajes. Esto incluye el emisor y el número de serie del certificado del firmante y los atributos autenticados y no autenticados del certificado del firmante. Para recuperar información del firmante de todos los firmantes de un mensaje, llame a CryptMsgGetParam variable dwIndex de 0 al número de firmantes menos uno.
CMSG_CMS_SIGNER_INFO_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CMSG_CMS_SIGNER_INFO . Devuelve información sobre un firmante de mensajes. Esto incluye un signerId y atributos autenticados y no autenticados. Para recuperar información del firmante de todos los firmantes de un mensaje, llame a CryptMsgGetParam variable dwIndex de 0 al número de firmantes menos uno.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CRYPT_ATTRIBUTES . Devuelve los atributos no autenticados de un firmante de mensajes. Para recuperar los atributos no autenticados de un firmante especificado, llame a CryptMsgGetParam con dwIndex igual al índice del firmante.
CMSG_TYPE_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve el tipo de mensaje de un mensaje descodificado de tipo desconocido. El tipo de mensaje recuperado se puede comparar con los tipos admitidos para determinar si el procesamiento puede continuar. Para ver los tipos de mensajes admitidos, consulte el parámetro dwMessageType de CryptMsgOpenToDecode.
CMSG_UNPROTECTED_ATTR_PARAM	Tipo de datos pvData : puntero a una matriz BYTE para recibir una estructura de CMSG_ATTR . Devuelve los atributos no protegidos en un mensaje sobre.
CMSG_VERSION_PARAM	Tipo de datos pvData : puntero a un DWORD Devuelve la versión del mensaje descodificado. Para más información, consulte la tabla de la sección de Comentario.

[in] dwIndex

Índice del parámetro que se va a recuperar, si procede. Cuando no se recupera un parámetro, este parámetro se omite y se establece en cero.

[out] pvData

Puntero a un búfer que recibe los datos recuperados. El formato de estos datos variará en función del valor del parámetro dwParamType .

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

Al procesar los datos devueltos en este 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 caben en el 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.

[in, out] pcbData

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

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

En la tabla siguiente se enumeran los códigos de error devueltos normalmente por la función GetLastError .

Código devuelto	Descripción
CRYPT_E_ATTRIBUTES_MISSING	El mensaje no contiene los atributos solicitados.
CRYPT_E_INVALID_INDEX	El valor del índice no es válido.
CRYPT_E_INVALID_MSG_TYPE	Tipo de mensaje no válido.
CRYPT_E_NOT_DECRYPTED	El contenido del mensaje aún no se ha descifrado.
CRYPT_E_OID_FORMAT	El identificador de objeto tiene un formato incorrecto.
CRYPT_E_UNEXPECTED_ENCODING	El mensaje no está codificado según lo previsto.
E_INVALIDARG	Uno o varios argumentos no son válidos.
ERROR_MORE_DATA	El búfer especificado no es lo suficientemente grande como para contener los datos devueltos.

Para dwParamType CMSG_COMPUTED_HASH_PARAM, se puede propagar un error desde CryptGetHashParam.

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

Se devuelven los números de versión siguientes mediante llamadas a CryptMsgGetParam con dwParamType establecido en CMSG_VERSION_PARAM se definen:

CMSG_SIGNED_DATA_V1
CMSG_SIGNED_DATA_V3
CMSG_SIGNED_DATA_PKCS_1_5_VERSION
CMSG_SIGNED_DATA_CMS_VERSION
CMSG_SIGNER_INFO_V1
CMSG_SIGNER_INFO_V3
CMSG_SIGNER_INFO_PKCS_1_5_VERSION
CMSG_SIGNER_INFO_CMS_VERSION
CMSG_HASHED_DATA_V0
CMSG_HASHED_DATA_V2
CMSG_HASHED_DATA_PKCS_1_5_VERSION
CMSG_HASHED_DATA_CMS_VERSION
CMSG_ENVELOPED_DATA_V0
CMSG_ENVELOPED_DATA_V2
CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
CMSG_ENVELOPED_DATA_CMS_VERSION

Ejemplos

Para obtener un ejemplo que usa esta función, vea Programa C de ejemplo: Firma, Codificación, Descodificación y Comprobación de un mensaje, Código alternativo para codificar un mensaje sobre, Ejemplo C Programa: Codificación de un sobre, Mensaje firmado y Programa C de ejemplo: Codificación y Descodificación de un mensaje hash.

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