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.
| Valor | Significado |
|---|---|
|
Indica que a mensagem a ser decodificada é desanexada. Se esse sinalizador não estiver definido, a mensagem não será desanexada. |
|
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.
[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 .
| Valor | Descrição |
|---|---|
|
Um ou mais argumentos não são válidos. |
|
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 |