Função CryptMsgGetParam (wincrypt.h)

Artigo
08/27/2023

A função CryptMsgGetParam adquire um parâmetro de mensagem depois que uma mensagem criptográfica é codificada ou decodificada. Essa função é chamada após a chamada cryptMsgUpdate final.

Sintaxe

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

Parâmetros

[in] hCryptMsg

Identificador de uma mensagem criptográfica.

[in] dwParamType

Indica os tipos de parâmetro de dados a serem recuperados. O tipo de dados a ser recuperado determina o tipo de estrutura a ser usada para pvData.

Para uma mensagem codificada, somente os CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM e CMSG_COMPUTED_HASH_PARAM dwParamTypesão válidos.

Valor	Significado
CMSG_ATTR_CERT_COUNT_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna a contagem dos certificados de atributo em uma mensagem SIGNED ou ENVELOPED.
CMSG_ATTR_CERT_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Recupera um certificado de atributo. Para obter todos os certificados de atributo, chame CryptMsgGetParamvariando dwIndex definido como 0 o número de atributos menos um.
CMSG_BARE_CONTENT_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Recupera o conteúdo codificado de uma mensagem criptográfica codificada, sem a camada externa da estrutura CONTENT_INFO. Ou seja, somente a codificação do campo ContentInfo.content definido por PKCS nº 7 é retornada.
CMSG_CERT_COUNT_PARAM	Tipo de dados pvData: ponteiro para DWORD Retorna o número de certificados em uma mensagem SIGNED ou ENVELOPED recebida.
CMSG_CERT_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o certificado de um signatário. Para obter todos os certificados do signatário, chame CryptMsgGetParam, variando dwIndex de 0 para o número de certificados disponíveis menos um.
CMSG_COMPUTED_HASH_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o hash calculado dos dados na mensagem. Esse tipo é aplicável à codificação e à decodificação.
CMSG_CONTENT_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna toda a mensagem PKCS nº 7 de uma mensagem aberta para codificar. Recupera o conteúdo interno de uma mensagem aberta para decodificar. Se a mensagem estiver envolvida, o tipo interno será data e CryptMsgControl tiver sido chamado para descriptografar a mensagem, o conteúdo descriptografado será retornado. Se o tipo interno não for dados, o BLOB codificado que requer mais decodificação será retornado. Se a mensagem não estiver envolvida e o conteúdo interno for DATA, os dados retornados serão os octetos do conteúdo interno. Esse tipo é aplicável à codificação e à decodificação. Para decodificação, se o tipo for CMSG_DATA, os octetos do conteúdo serão retornados; else, o conteúdo interno codificado é retornado.
CMSG_CRL_COUNT_PARAM	Tipo de dados pvData: ponteiro para DWORD Retorna a contagem de CRLs em uma mensagem recebida, ASSINADA ou ENVELOPED.
CMSG_CRL_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna uma CRL. Para obter todas as CRLs, chame CryptMsgGetParam, variando dwIndex de 0 para o número de CRLs disponíveis menos uma.
CMSG_ENCODED_MESSAGE	Tipo de dados pvData: ponteiro para uma matriz BYTE Altera o conteúdo de uma mensagem já codificada. A mensagem deve primeiro ser decodificada com uma chamada para CryptMsgOpenToDecode. Em seguida, a alteração na mensagem é feita por meio de uma chamada para CryptMsgControl, CryptMsgCountersign ou CryptMsgCountersignEncoded. Em seguida, a mensagem é codificada novamente com uma chamada para CryptMsgGetParam, especificando CMSG_ENCODED_MESSAGE para obter uma nova codificação que reflita as alterações feitas. Isso pode ser usado, por exemplo, para adicionar um atributo de carimbo de data/hora a uma mensagem.
CMSG_ENCODED_SIGNER	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna as informações codificadas CMSG_SIGNER_INFO signatário para um signatário de mensagem.
CMSG_ENCRYPTED_DIGEST	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o hash criptografado de uma assinatura. Normalmente usado para executar carimbo de data/hora.
CMSG_ENCRYPT_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER. Retorna o algoritmo de criptografia usado para criptografar a mensagem.
CMSG_ENVELOPE_ALGORITHM_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER. Retorna o algoritmo de criptografia usado para criptografar uma mensagem ENVELOPED.
CMSG_HASH_ALGORITHM_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para uma estrutura de CRYPT_ALGORITHM_IDENTIFIER. Retorna o algoritmo de hash usado para hash da mensagem quando ela foi criada.
CMSG_HASH_DATA_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE Retorna o valor de hash armazenado na mensagem quando ele foi criado.
CMSG_INNER_CONTENT_TYPE_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma cadeia de caracteres OID (identificador de objeto terminada em nulo). Retorna o tipo de conteúdo interno de uma mensagem recebida. Esse tipo não é aplicável a mensagens do tipo DATA.
CMSG_RECIPIENT_COUNT_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o número de destinatários de transporte de chave de uma mensagem ENVELOPED recebida.
CMSG_CMS_RECIPIENT_COUNT_PARAM	Tipo de dados pvData: ponteiro para DWORD Retorna a contagem total de todos os destinatários de mensagens, incluindo os destinatários do contrato de chave e da lista de emails.
CMSG_RECIPIENT_INDEX_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o índice do destinatário de transporte de chave usado para descriptografar uma mensagem ENVELOPED. Esse valor só estará disponível depois que uma mensagem tiver sido descriptografada.
CMSG_CMS_RECIPIENT_INDEX_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o índice do transporte de chaves, do contrato de chave ou do destinatário da lista de emails usado para descriptografar uma mensagem ENVELOPED.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o índice da chave criptografada de um destinatário de contrato de chave usado para descriptografar uma mensagem ENVELOPED.
CMSG_RECIPIENT_INFO_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CERT_INFO. Retorna informações de certificado sobre o destinatário de uma mensagem de transporte de chave. Para obter informações de certificado sobre todos os destinatários da mensagem de transporte de chave, chame repetidamente CryptMsgGetParam, variando dwIndex de 0 para o número de destinatários menos um. Somente os membros Issuer, SerialNumber e PublicKeyAlgorithm da estrutura CERT_INFO retornada estão disponíveis e são válidos.
CMSG_CMS_RECIPIENT_INFO_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_CMS_RECIPIENT_INFO. Retorna informações sobre um transporte de chave, contrato de chave ou destinatário da lista de emails. Ele não se limita aos destinatários de mensagens de transporte de chave. Para obter informações sobre todos os destinatários de uma mensagem, chame repetidamente CryptMsgGetParam, variando dwIndex de 0 para o número de destinatários menos um.
CMSG_SIGNER_AUTH_ATTR_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CRYPT_ATTRIBUTES. Retorna os atributos autenticados de um signatário de mensagem. Para recuperar os atributos autenticados para um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário.
CMSG_SIGNER_CERT_INFO_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber a estrutura CERT_INFO. Retorna informações sobre um signatário de mensagem necessário para identificar o certificado do signatário. O Emissor e o SerialNumber de um certificado podem ser usados para identificar exclusivamente um certificado para recuperação. Para recuperar informações para todos os signatários, chame repetidamente CryptMsgGetParamvariando dwIndex de 0 para o número de signatários menos um. Somente os campos Emissor e SerialNumber na estrutura CERT_INFO retornada contêm dados disponíveis e válidos.
CMSG_SIGNER_CERT_ID_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CERT_ID. Retorna informações sobre um signatário de mensagem necessário para identificar a chave pública do signatário. Isso pode ser um Emissor e SerialNumber de um certificado, um KeyID ou um HashId. Para recuperar informações para todos os signatários, chame CryptMsgGetParamvariando dwIndex de 0 para o número de signatários menos um.
CMSG_SIGNER_COUNT_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o número de signatários de uma mensagem SIGNED recebida.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber a estrutura CRYPT_ALGORITHM_IDENTIFIER. Retorna o algoritmo de hash usado por um signatário da mensagem. Para obter o algoritmo de hash para um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário.
CMSG_SIGNER_INFO_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_SIGNER_INFO. Retorna informações sobre um signatário de mensagem. Isso inclui o emissor e o número de série do certificado do signatário e atributos autenticados e não autenticados do certificado do signatário. Para recuperar informações do signatário em todos os signatários de uma mensagem, chame CryptMsgGetParam variando dwIndex de 0 para o número de signatários menos um.
CMSG_CMS_SIGNER_INFO_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura de CMSG_CMS_SIGNER_INFO. Retorna informações sobre um signatário de mensagem. Isso inclui um signerId e atributos autenticados e não autenticados. Para recuperar informações do signatário em todos os signatários de uma mensagem, chame CryptMsgGetParam variando dwIndex de 0 para o número de signatários menos um.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CRYPT_ATTRIBUTES. Retorna os atributos não autenticados de um signatário de mensagem. Para recuperar os atributos não autenticados de um signatário especificado, chame CryptMsgGetParam com dwIndex igual ao índice desse signatário.
CMSG_TYPE_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna o tipo de mensagem de uma mensagem decodificada de tipo desconhecido. O tipo de mensagem recuperado pode ser comparado aos tipos com suporte para determinar se o processamento pode continuar. Para tipos de mensagem com suporte, consulte o parâmetro dwMessageType de CryptMsgOpenToDecode.
CMSG_UNPROTECTED_ATTR_PARAM	Tipo de dados pvData: ponteiro para uma matriz BYTE para receber uma estrutura CMSG_ATTR. Retorna os atributos desprotegidos em uma mensagem em envelope.
CMSG_VERSION_PARAM	Tipo de dados pvData: ponteiro para um DWORD Retorna a versão da mensagem decodificada. Para obter mais informações, consulte a tabela na seção Comentários.

[in] dwIndex

Índice para o parâmetro que está sendo recuperado, quando aplicável. Quando um parâmetro não está sendo recuperado, esse parâmetro é ignorado e é definido como zero.

[out] pvData

Um ponteiro para um buffer que recebe os dados recuperados. A forma desses dados variará dependendo do valor do parâmetro dwParamType .

Esse parâmetro pode ser NULL para definir o tamanho dessas informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

Ao processar os dados retornados nesse buffer, os aplicativos precisam usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

[in, out] pcbData

Um ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData . Quando a função retorna, a variável apontada pelo parâmetro pcbData contém o número de bytes armazenados no buffer.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.

A tabela a seguir lista os códigos de erro mais comumente retornados pela função GetLastError .

Código de retorno	Descrição
CRYPT_E_ATTRIBUTES_MISSING	A mensagem não contém os atributos solicitados.
CRYPT_E_INVALID_INDEX	O valor do índice não é válido.
CRYPT_E_INVALID_MSG_TYPE	O tipo de mensagem não é válido.
CRYPT_E_NOT_DECRYPTED	O conteúdo da mensagem ainda não foi descriptografado.
CRYPT_E_OID_FORMAT	O identificador de objeto está mal formatado.
CRYPT_E_UNEXPECTED_ENCODING	A mensagem não está codificada conforme o esperado.
E_INVALIDARG	Um ou mais argumentos não são válidos.
ERROR_MORE_DATA	O buffer especificado não é grande o suficiente para manter os dados retornados.

Para CMSG_COMPUTED_HASH_PARAM dwParamType , um erro pode ser propagado de CryptGetHashParam.

Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.

Comentários

Os seguintes números de versão são retornados por chamadas para CryptMsgGetParam com dwParamType definido como CMSG_VERSION_PARAM são definidos:

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

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de programa C: assinatura, codificação, decodificação e verificação de uma mensagem, código alternativo para codificar uma mensagem encolhida, exemplo de programa C: codificação de um envelope, mensagem assinada e exemplo de programa C: codificação e decodificação de uma mensagem com hash.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll