Partilhar via

Função EncryptMessage (Schannel)

A função EncryptMessage (Schannel) criptografa uma mensagem para fornecer privacidade. EncryptMessage (Schannel) permite que uma aplicação escolha entre algoritmos criptográficos suportados pelo mecanismo escolhido. A função EncryptMessage (Schannel) usa o contexto de segurança referenciado pelo identificador de contexto. Alguns pacotes não têm mensagens a serem criptografadas ou descriptografadas, mas fornecem um hash de integridade que pode ser verificado.

Ao usar o SSP Schannel, essa função criptografa mensagens usando uma chave de sessão negociada com a parte remota que receberá a mensagem. O algoritmo de encriptação é determinado pelo [cipher suite](cipher-suites-in-schannel.md) em uso.

Observação

EncryptMessage (Schannel) e DecryptMessage (Schannel) podem ser chamados ao mesmo tempo a partir de dois threads diferentes em um único contexto SSPI ( security support provider interface ) se um thread estiver criptografando e o outro estiver descriptografando. Se mais de um thread estiver criptografando ou mais de um thread estiver descriptografando, cada thread deverá obter um contexto exclusivo.

Sintaxe

SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Parâmetros

phContext [em]

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

fQOP [em]

Sinalizadores específicos da embalagem que indicam a qualidade da proteção. Um pacote de segurança pode usar esse parâmetro para habilitar a seleção de algoritmos criptográficos.

Este parâmetro pode ser o seguinte sinalizador.

Valor Significado
SECQOP_WRAP_OOB_DATA
 Envie uma mensagem de alerta Schannel. Nesse caso, o parâmetro pMessage deve conter um código de evento SSL/TLS padrão de dois bytes. Esse valor é suportado apenas pelo SSP Schannel.
Por exemplo, a partir do Windows Vista, a mensagem "saudação do servidor" enviada pelo servidor durante o protocolo de reautenticação deve ser criptografada como um alerta TLS.

pMessage [entrada, saída]

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

A função não processa buffers com o atributo SECBUFFER_READONLY.

O comprimento da estrutura SecBuffer que contém a mensagem não deve ser maior do que cbMaximumMessage, que é obtido a partir da função QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES).

MessageSeqNo [em]

O número de sequência que o aplicativo de transporte atribuiu à mensagem. Se o aplicativo de transporte não mantiver números de sequência, esse parâmetro deverá ser zero.

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

Valor de retorno

Se a função for bem-sucedida, a função retornará SEC_E_OK.

Se a função falhar, ela retornará um dos seguintes códigos de erro.

Código de retorno Descrição
SEC_E_BUFFER_TOO_SMALL
 O buffer de saída é muito pequeno. Para obter mais informações, consulte Observações.
SEC_E_CONTEXT_EXPIRED
 O aplicativo está fazendo referência a um contexto que já foi fechado. Um aplicativo escrito corretamente não deve receber esse erro.
SEC_E_CRYPTO_SYSTEM_INVALID
 A cifra escolhida para o contexto de segurança não é suportada.
SEC_E_INSUFFICIENT_MEMORY
 Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INVALID_HANDLE
 Um identificador de contexto que não é válido foi especificado no parâmetro phContext .
SEC_E_INVALID_TOKEN
 Nenhum buffer de tipo SECBUFFER_DATA foi encontrado.
SEC_E_QOP_NOT_SUPPORTED
 Nem a confidencialidade nem a integridade são suportadas pelo contexto de segurança.

Observações

A função EncryptMessage (Schannel) criptografa uma mensagem com base na mensagem e na chave de sessão de um contexto de segurança.

Se o aplicativo de transporte criou o contexto de segurança para dar suporte à deteção de sequência e o chamador fornece um número de sequência, a função inclui essas informações com a mensagem criptografada. A inclusão dessas informações protege contra reprodução, inserção e supressão de mensagens. O pacote de segurança incorpora o número de sequência transmitido a partir do aplicativo de transporte.

Quando usado com o SSP Schannel, o parâmetro pMessage deve conter uma estrutura SecBufferDesc com os seguintes buffers.

Observação

Esses buffers devem ser fornecidos na ordem mostrada.

Tipo de buffer Descrição
SECBUFFER_STREAM_HEADER Usado internamente. Nenhuma inicialização necessária.
SECBUFFER_DATA Contém a mensagem de texto simples a ser criptografada.
SECBUFFER_STREAM_TRAILER Usado internamente. Nenhuma inicialização necessária.
SECBUFFER_EMPTY Usado internamente. Nenhuma inicialização necessária. O tamanho pode ser zero.

Ao usar o SSP Schannel, determine o tamanho máximo de cada um dos buffers chamando a função QueryContextAttributes (Schannel) e especificando o atributo SECPKG_ATTR_STREAM_SIZES. Esta função retorna uma estrutura SecPkgContext_StreamSizes cujos membros contêm os tamanhos máximos para os buffers header (cbHeader member), message (cbMaximumMessage member) e trailer (cbTrailer member).

Para um desempenho ideal, as estruturas pMessage devem ser alocadas a partir da memória contígua.

Windows XP/2000: Esta função também era conhecida como SealMessage. Os aplicativos agora devem usar apenas EncryptMessage (Schannel ).

Requerimentos

Requisito Valor
Cliente mínimo suportado Windows XP [apenas aplicações de ambiente de trabalho]
Servidor mínimo suportado Windows Server 2003 [apenas aplicações de ambiente de trabalho]
Cabeçalho Sspi.h (inclui Security.h)
Biblioteca Secur32.lib
DLL Secur32.dll

Ver também

  • Last updated on