Compartilhar via

Função DecryptMessage (Schannel)

  • Artigo

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

Essa função também é usada com o SSP ( provedor de suporte de segurança ) do Schannel para sinalizar uma solicitação de um remetente de mensagens para uma renegociação (refazer) dos atributos de conexão ou para um desligamento da conexão.

Observação

EncryptMessage (Schannel) e DecryptMessage (Schannel) podem ser chamados ao mesmo tempo de dois threads diferentes em um único contexto de SSPI ( interface do provedor de suporte de segurança ) se um thread estiver criptografando e o outro estiver descriptografando. Se mais de um thread estiver sendo criptografado ou mais de um thread estiver descriptografando, cada thread deverá obter um contexto exclusivo.

Sintaxe

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

Parâmetros

phContext [in]

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

pMessage [in, out]

Um ponteiro para uma estrutura SecBufferDesc . Na entrada, a estrutura faz referência a uma ou mais estruturas do SecBuffer . Uma delas pode ser do tipo SECBUFFER_DATA. Esse buffer contém a mensagem criptografada. A mensagem criptografada é descriptografada no local, substituindo o conteúdo original de seu buffer.

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

MessageSeqNo [in]

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, esse parâmetro deverá ser definido como zero.

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

pfQOP [out]

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 do Schannel, esse parâmetro não é usado e deve ser definido como NULL.

Esse parâmetro pode ser o sinalizador a seguir.

Valor Significado
SECQOP_WRAP_NO_ENCRYPT
 A mensagem não foi criptografada, mas um cabeçalho ou trailer foi produzido.
Nota: KERB_WRAP_NO_ENCRYPT tem o mesmo valor e o mesmo significado.

Valor retornado

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

Se a função não conseguir descriptografar a mensagem, ela retornará um dos seguintes códigos de erro.

Código de retorno Descrição
SEC_E_INVALID_HANDLE Um identificador de contexto que não é válido foi especificado no parâmetro phContext . Usado com o SSP do Schannel.
SEC_E_INVALID_TOKEN Os buffers são do tipo errado ou nenhum buffer do tipo SECBUFFER_DATA foi encontrado. Usado com o SSP do Schannel.
SEC_E_MESSAGE_ALTERED A mensagem foi alterada. Usado com o SSP do Schannel.
SEC_E_OUT_OF_SEQUENCE A mensagem não foi recebida na sequência correta.
SEC_I_CONTEXT_EXPIRED O remetente da mensagem terminou de usar a conexão e iniciou um desligamento. Para obter informações sobre como iniciar ou reconhecer um desligamento, consulte Desligando uma Conexão Schannel. Usado com o SSP do Schannel.
SEC_I_RENEGOTIATE A parte remota requer uma nova sequência de handshake ou o aplicativo acabou de iniciar um desligamento. Retorne ao loop de negociação e chame AcceptSecurityContext (Schannel) ou InitializeSecurityContext (Schannel), passe SECBUFFER_EXTRA retornado de DecryptMessage().

Comentários

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

Quando você usa o SSP do 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 você estiver usando o TLS 1.0, talvez seja necessário chamar essa função várias vezes, ajustando o buffer de entrada em cada chamada, para descriptografar uma mensagem inteira.

A função DecryptMessage (Schannel) retorna SEC_I_RENEGOTIATE quando uma mensagem de protocolo TLS pós-handshake diferente dos dados do aplicativo é recebida. Depois que a função DecryptMessage (Schannel) retornar SEC_I_RENEGOTIATE, todas as chamadas EncryptMessage() e DecryptMessage() falharão 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 SECBUFFER_EXTRA retornados de DecryptMessage(). 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.

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]
parâmetro Sspi.h (inclua Security.h)
Biblioteca Secur32.lib
DLL Secur32.dll

Confira também