Função CryptMsgOpenToDecode (wincrypt.h)

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.

[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.

[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.

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.

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 .

Requisitos

Confira também

CryptMsgClose

Cryptmsggetparam

Cryptmsgopentoencode

Cryptmsgupdate

Funções de mensagem de baixo nível

Funções de mensagem simplificadas