Função CryptMsgOpenToDecode (wincrypt.h)

Artigo
08/27/2023

A função CryptMsgOpenToDecode abre uma mensagem criptográfica para decodificação e retorna um identificador da mensagem aberta. A mensagem permanece aberta até que a função CryptMsgClose seja chamada.

Alterações importantes que afetam o tratamento de mensagens envelopedas foram feitas no CryptoAPI para dar suporte à interoperabilidade de email S/MIME ( Extensões de Email de Internet Segura/Multiuso ). Para obter detalhes, consulte a seção Comentários de CryptMsgOpenToEncode.

Sintaxe

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Parâmetros

[in] dwMsgEncodingType

Especifica o tipo de codificação usado. É sempre aceitável especificar os tipos de codificação de certificado e mensagem combinando-os com uma operação OR bit a bit, conforme mostrado no exemplo a seguir:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Os tipos de codificação definidos no momento são:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Esse parâmetro pode ser um dos sinalizadores a seguir.

Valor	Significado
CMSG_DETACHED_FLAG	Indica que a mensagem a ser decodificada é desanexada. Se esse sinalizador não estiver definido, a mensagem não será desanexada.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Se definido, o hCryptProv passado para essa função será liberado no CryptMsgUpdate final. O identificador não será liberado se a função falhar.

[in] dwMsgType

Especifica o tipo de mensagem a ser decodificada. Na maioria dos casos, o tipo de mensagem é determinado do cabeçalho da mensagem e zero é passado para esse parâmetro. Em alguns casos, notadamente com a Internet Explorer 3.0, as mensagens não têm cabeçalhos e o tipo de mensagem a ser decodificada deve ser fornecido nesta chamada de função. Se o cabeçalho estiver ausente e zero for passado para esse parâmetro, a função falhará.

Esse parâmetro pode ser um dos seguintes tipos de mensagem predefinidos.

Valor	Significado
CMSG_DATA	A mensagem são dados codificados.
CMSG_ENVELOPED	A mensagem é uma mensagem em envelope.
CMSG_HASHED	A mensagem é uma mensagem hash.
CMSG_SIGNED	A mensagem é uma mensagem assinada.
CMSG_SIGNED_AND_ENVELOPED	A mensagem é uma mensagem assinada e em envelope.

[in] hCryptProv

Esse parâmetro não é usado e deve ser definido como NULL.

Windows Server 2003 e Windows XP: Especifica um identificador para o provedor criptográfico usar para hash da mensagem. Para mensagens assinadas, hCryptProv é usado para verificação de assinatura. O tipo de dados desse parâmetro é HCRYPTPROV.

A menos que haja um motivo forte para passar um provedor criptográfico específico no hCryptProv, defina esse parâmetro como NULL. A passagem de NULL faz com que o provedor RSA ou DSS padrão seja adquirido antes de executar operações de hash, verificação de assinatura ou criptografia de destinatário.

[in] pRecipientInfo

Esse parâmetro é reservado para uso futuro e deve ser NULL.

[in, optional] pStreamInfo

Quando o streaming não está sendo usado, esse parâmetro deve ser definido como NULL.

Nota O streaming não é usado com mensagens CMSG_HASHED. Ao lidar com dados com hash, esse parâmetro deve ser definido como NULL.

Quando o streaming está sendo usado, o parâmetro pStreamInfo é um ponteiro para uma estrutura CMSG_STREAM_INFO que contém um ponteiro para um retorno de chamada a ser chamado quando CryptMsgUpdate é executado ou quando CryptMsgControl é executado ao decodificar uma mensagem em envelope transmitida.

Para uma mensagem assinada, o retorno de chamada é passado um bloco dos bytes decodificados do conteúdo interno da mensagem.

Para uma mensagem em envelope, após cada chamada para CryptMsgUpdate, você deve marcar para determinar se a propriedade CMSG_ENVELOPE_ALGORITHM_PARAM está disponível chamando a função CryptMsgGetParam. CryptMsgGetParam falhará e GetLastError retornará CRYPT_E_STREAM_MSG_NOT_READY até que CryptMsgUpdate tenha processado o suficiente da mensagem para disponibilizar a propriedade CMSG_ENVELOPE_ALGORITHM_PARAM. Quando a propriedade CMSG_ENVELOPE_ALGORITHM_PARAM estiver disponível, você poderá iterar por meio dos destinatários, recuperando uma estrutura CERT_INFO para cada destinatário usando a função CryptMsgGetParam para recuperar a propriedade CMSG_RECIPIENT_INFO_PARAM. Para evitar um ataque de negação de serviço de uma mensagem em envelope que tenha um bloco de cabeçalho artificialmente grande, você deve acompanhar a quantidade de memória que foi passada para a função CryptMsgUpdate durante esse processo. Se a quantidade de dados exceder um limite definido pelo aplicativo antes que a propriedade CMSG_ENVELOPE_ALGORITHM_PARAM esteja disponível, você deverá parar de processar a mensagem e chamar a função CryptMsgClose para fazer com que o sistema operacional libere qualquer memória alocada para a mensagem. Um limite sugerido é o tamanho máximo permitido de uma mensagem. Por exemplo, se o tamanho máximo da mensagem for de 10 MB, o limite para esse teste deverá ser de 10 MB.

A estrutura CERT_INFO é usada para localizar um certificado correspondente em um repositório de certificados aberto anteriormente usando a função CertGetSubjectCertificateFromStore . Quando o certificado correto é encontrado, a função CertGetCertificateContextProperty com um parâmetro CERT_KEY_PROV_INFO_PROP_ID é chamada para recuperar uma estrutura de CRYPT_KEY_PROV_INFO . A estrutura contém as informações necessárias para adquirir a chave privada do destinatário chamando CryptAcquireContext, usando os membros pwszContainerName, pwszProvName, dwProvType e dwFlags da estrutura CRYPT_KEY_PROV_INFO . O hCryptProv adquirido e o membro dwKeySpec da estrutura CRYPT_KEY_PROV_INFO são passados para a estrutura CryptMsgControl como membro da estrutura CMSG_CTRL_DECRYPT_PARA para permitir o início da descriptografia do conteúdo interno. Em seguida, o código de streaming executará a descriptografia à medida que os dados forem inseridos. Os blocos resultantes de texto sem formatação são passados para a função de retorno de chamada especificada pelo membro pfnStreamOutput da estrutura CMSG_STREAM_INFO para lidar com a saída da mensagem descriptografada.

Nota A decodificação transmitida de uma mensagem enveloped enfileira o texto cifrado na memória até que CryptMsgControl seja chamado para iniciar a descriptografia. O aplicativo deve iniciar a descriptografia em tempo hábil para que os dados possam ser salvos em disco ou roteados para outro lugar antes que o texto cifrado acumulado se torne muito grande e o sistema fique sem memória.

No caso de uma mensagem assinada entre uma mensagem em envelope, a saída de texto sem formatação da decodificação de streaming da mensagem envelopeada pode ser alimentada em outro decodificador de streaming para processar a mensagem assinada.

Retornar valor

Se a função for bem-sucedida, a função retornará o identificador da mensagem aberta.

Se a função falhar, ela retornará NULL. 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 .

Valor	Descrição
E_INVALIDARG	Um ou mais argumentos não são válidos.
E_OUTOFMEMORY	Ocorreu uma falha de alocação de memória.

Requisitos

Requisito	Valor
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

Confira também

Funções de mensagem de baixo nível

Funções de mensagem simplificadas