Função CryptDecodeMessage (wincrypt.h)
A função CryptDecodeMessage decodifica, descriptografa e verifica uma mensagem criptográfica.
Essa função pode ser usada quando o tipo de mensagem criptográfica é desconhecido. As constantes dwMsgTypeFlags podem ser combinadas com uma operação OR bit a bit para que a função tente localizar um dos tipos. Quando um dos tipos é encontrado, a função relata o tipo encontrado e retorna os dados apropriados para esse tipo.
Em cada passagem, a função decifra apenas um único nível de criptografia ou codificação. Para quebras adicionais, essa função ou uma das outras Funções de Mensagem Simplificadas deve ser chamada novamente.
Sintaxe
BOOL CryptDecodeMessage(
[in] DWORD dwMsgTypeFlags,
[in] PCRYPT_DECRYPT_MESSAGE_PARA pDecryptPara,
[in] PCRYPT_VERIFY_MESSAGE_PARA pVerifyPara,
[in] DWORD dwSignerIndex,
[in] const BYTE *pbEncodedBlob,
[in] DWORD cbEncodedBlob,
[in] DWORD dwPrevInnerContentType,
[out, optional] DWORD *pdwMsgType,
[out, optional] DWORD *pdwInnerContentType,
[out, optional] BYTE *pbDecoded,
[in, out, optional] DWORD *pcbDecoded,
[out, optional] PCCERT_CONTEXT *ppXchgCert,
[out, optional] PCCERT_CONTEXT *ppSignerCert
);
Parâmetros
[in] dwMsgTypeFlags
Indica o tipo de mensagem. Os tipos de mensagem podem ser combinados com o operador OR bit a bit. Esse parâmetro pode ser um dos seguintes tipos de mensagem:
- CMSG_DATA_FLAG
- CMSG_SIGNED_FLAG
- CMSG_ENVELOPED_FLAG
- CMSG_SIGNED_AND_ENVELOPED_FLAG
- CMSG_HASHED_FLAG
[in] pDecryptPara
Um ponteiro para uma estrutura CRYPT_DECRYPT_MESSAGE_PARA que contém parâmetros de descriptografia.
[in] pVerifyPara
Um ponteiro para uma estrutura CRYPT_VERIFY_MESSAGE_PARA que contém parâmetros de verificação.
[in] dwSignerIndex
Indica qual signatário, entre os possíveis muitos signatários de uma mensagem, deve ser verificado. Esse índice pode ser alterado em várias chamadas para a função para verificar os signatários adicionais.
dwSignerIndex é definido como zero para o primeiro signatário. Se a função retornar FALSE e GetLastError retornar CRYPT_E_NO_SIGNER, a chamada anterior retornará o último signatário da mensagem. Esse parâmetro é usado apenas com mensagens de tipos CMSG_SIGNED_AND_ENVELOPED ou CMSG_SIGNED. Para todos os outros tipos de mensagem, ele deve ser definido como zero.
[in] pbEncodedBlob
Um ponteiro para o BLOB codificado que deve ser decodificado.
[in] cbEncodedBlob
O tamanho, em bytes, do BLOB codificado.
[in] dwPrevInnerContentType
Aplicável somente ao processar mensagens criptográficas aninhadas. Ao processar uma mensagem criptográfica externa, ela deve ser definida como zero. Ao decodificar uma mensagem criptográfica aninhada, ela é definida como o valor retornado em pdwInnerContentType por uma chamada anterior de CryptDecodeMessage para a mensagem externa. Pode ser qualquer um dos tipos CMSG listados em pdwMsgType. Para compatibilidade com versões anteriores, defina dwPrevInnerContentType como zero.
[out, optional] pdwMsgType
Um ponteiro para um DWORD que especifica o tipo de mensagem retornado. Esse parâmetro pode ser um dos seguintes tipos de mensagem:
- CMSG_DATA
- CMSG_SIGNED
- CMSG_ENVELOPED
- CMSG_SIGNED_AND_ENVELOPED
- CMSG_HASHED
[out, optional] pdwInnerContentType
Um ponteiro para um DWORD que especifica o tipo de uma mensagem interna. Os códigos de tipo de mensagem usados para pdwMsgType também são usados aqui.
Se não houver aninhamento criptográfico, CMSG_DATA será retornado.
[out, optional] pbDecoded
Um ponteiro para um buffer para receber a mensagem decodificada.
Esse parâmetro poderá ser NULL se a mensagem decodificada não for necessária ou para definir o tamanho da mensagem decodificada para fins de alocação de memória. Uma mensagem decodificada não será retornada se esse parâmetro for NULL. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
[in, out, optional] pcbDecoded
Um ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pbDecoded . Quando a função retorna, essa variável contém o tamanho da mensagem decodificada.
[out, optional] ppXchgCert
Um ponteiro para um ponteiro para uma estrutura CERT_CONTEXT com um certificado que corresponde à chave de troca privada necessária para decodificar a mensagem. Esse parâmetro só é definido para tipos de mensagem CMSG_ENVELOPED e CMSG_SIGNED_AND_ENVELOPED.
[out, optional] ppSignerCert
Um ponteiro para um ponteiro para uma estrutura CERT_CONTEXT do contexto de certificado do signatário. Esse parâmetro só é definido para tipos de mensagem CMSG_SIGNED e CMSG_SIGNED_AND_ENVELOPED.
Retornar valor
Se a função for bem-sucedida, a função retornará diferente de zero (TRUE).
Se a função falhar, ela retornará zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.
As funções CryptDecryptMessage, CryptVerifyMessageSignature ou CryptVerifyMessageHash podem ser propagadas para essa função.
O código de erro a seguir é mais comumente retornado pela função GetLastError .
| Código de retorno | Descrição |
|---|---|
|
Se o buffer especificado pelo parâmetro pbDecoded não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pcbDecoded. |
Comentários
O parâmetro dwMsgTypeFlags especifica o conjunto de mensagens permitidas. Por exemplo, para decodificar mensagens SIGNED ou ENVELOPED, defina dwMsgTypeFlags como CMSG_SIGNED_FLAG | CMSG_ENVELOPED_FLAG. Ou ambos os parâmetros pDecryptPara ou pVerifyPara devem ser especificados.
Para uma mensagem decodificada ou verificada com êxito, os ponteiros de contexto de certificado apontados por ppXchgCert e ppSignerCert são atualizados. Eles devem ser liberados chamando CertFreeCertificateContext. Se a função falhar, elas serão definidas como NULL.
Os parâmetros ppXchgCert ou ppSignerCert podem ser definidos como NULL antes da função ser chamada, o que indica que o chamador não está interessado em obter o certificado de troca ou o contexto do certificado do signatário.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |