Função DecryptMessage (Schannel)

A função DecryptMessage (Schannel) desencripta uma mensagem. Alguns pacotes não criptografam e descriptografam mensagens, mas executam e verificam um hash de integridade.

Use essa função com o SSP (provedor de suporte de segurança ) Schannel para sinalizar uma solicitação de um remetente de mensagem para uma renegociação (redo) dos atributos de conexão ou para um desligamento da conexão.

Sintaxe

SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_    PCtxtHandle    phContext,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo,
  _Out_   PULONG         pfQOP
);

Parâmetros

phContext [em]

Um identificador para o contexto de segurança a ser usado para descriptografar a mensagem.

pMessage [entrada, saída]

Um ponteiro para uma estrutura SecBufferDesc . Na entrada, a estrutura faz referência a uma ou mais estruturas SecBuffer . Um desses buffers pode ser do tipo SECBUFFER_DATA. Esse buffer contém a mensagem criptografada. A função desencripta a mensagem encriptada no local, substituindo o conteúdo original da sua memória intermédia.

Quando você usa o SSP Schannel com contextos que não são orientados à conexão, a estrutura deve conter quatro estruturas SecBuffer na entrada. Exatamente um buffer deve ser do tipo SECBUFFER_DATA e conter uma mensagem criptografada, que a função descriptografa no local. Os buffers restantes são usados para saída e devem ser do tipo SECBUFFER_EMPTY. Para contextos orientados a conexão, você deve fornecer um buffer de tipo SECBUFFER_DATA, conforme observado para contextos não orientados à conexão. Além disso, você deve fornecer um segundo SECBUFFER_TOKEN tipo buffer que contém um token de segurança.

MessageSeqNo [em]

O número de sequência esperado pelo aplicativo de transporte, se houver. Se o aplicativo de transporte não mantiver números de sequência, defina esse parâmetro como zero.

Ao usar o SSP Schannel, defina esse parâmetro como zero. O SSP Schannel não usa números de sequência.

pfQOP [saída]

Um ponteiro para uma variável do tipo ULONG que recebe sinalizadores específicos do pacote que indicam a qualidade da proteção.

Ao usar o SSP Schannel, não use esse parâmetro. Defina-o como NULL.

Este parâmetro pode ser o seguinte sinalizador.

Valor de retorno

Se a função verificar se a mensagem foi recebida na sequência correta, ela retornará SEC_E_OK.

Se a função não conseguir desencriptar a mensagem, devolve um dos seguintes códigos de erro.

Observações

Às vezes, um aplicativo lê dados da parte remota, tenta descriptografá-los usando DecryptMessage (Schannel) e descobre que DecryptMessage (Schannel) é bem-sucedido, mas os buffers de saída estão vazios. Esse comportamento é normal e os aplicativos devem ser capazes de manipulá-lo.

Quando você usa o SSP Schannel, a função DecryptMessage (Geral) retorna SEC_I_CONTEXT_EXPIRED quando o remetente da mensagem desliga a conexão. Para obter informações sobre como iniciar ou reconhecer um desligamento, consulte Desligando uma conexão Schannel.

Se estiver a utilizar o TLS 1.0, poderá ter de chamar esta função várias vezes, ajustando a memória intermédia de entrada em cada chamada, para desencriptar uma mensagem inteira.

A função DecryptMessage (Schannel) retorna SEC_I_RENEGOTIATE quando recebe uma mensagem de protocolo TLS pós-handshake diferente dos dados do aplicativo. Uma vez que DecryptMessage (Schannel) retorna SEC_I_RENEGOTIATE, quaisquer outras chamadas EncryptMessage() e DecryptMessage() falham com SEC_E_CONTEXT_EXPIRED. Um aplicativo lida com essa situação chamando AcceptSecurityContext (Schannel) (lado do servidor) ou InitializeSecurityContext (Schannel) (lado do cliente) e passando o mesmo buffer modificado por DecryptMessage, garantindo que o SecBuffer tipo esteja definido como SECBUFFER_TOKEN. Observe que DecryptMessage nem sempre retorna um SECBUFFER_EXTRA buffer quando SEC_I_RENEGOTIATE é retornado. Depois que essa chamada inicial retornar um valor, prossiga como se seu aplicativo estivesse criando uma nova conexão. Em seguida, o aplicativo pode continuar chamando EncryptMessage() e DecryptMessage(). Para obter mais informações, consulte Criando um contexto de segurança Schannel.

Requerimentos

Conteúdo relacionado

• Funções SSPI
• EncryptMessage (Schannel)
• SecBuffer