Função EncryptMessage (Geral)

A função EncryptMessage (Geral) criptografa uma mensagem para fornecer privacidade. EncryptMessage (Geral) permite que um aplicativo escolha entre algoritmos criptográficos compatíveis com o mecanismo escolhido. A função EncryptMessage (Geral) 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 ( provedor de suporte de segurança ) Digest, essa função está disponível apenas como um mecanismo SASL.

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

Para obter informações sobre como usar essa função com um SSP específico, consulte os tópicos a seguir.

Sintaxe

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

Parâmetros

phContext [in]

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

fQOP [in]

Sinalizadores específicos do pacote 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.

Ao usar o SSP do Digest, esse parâmetro deve ser definido como zero.

Esse parâmetro pode ser um dos sinalizadores a seguir.

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 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 que cbMaximumMessage, que é obtido da função QueryContextAttributes (Geral) (SECPKG_ATTR_STREAM_SIZES).

Ao usar o SSP digest, deve haver um segundo buffer do tipo SECBUFFER_PADDING ou SEC_BUFFER_DATA para armazenar informações de assinatura . Para obter o tamanho do buffer de saída, chame a função QueryContextAttributes (Geral) e especifique SECPKG_ATTR_SIZES. A função retornará uma estrutura SecPkgContext_Sizes . O tamanho do buffer de saída é a soma dos valores nos membros cbMaxSignature e cbBlockSize .

Os aplicativos que não usam SSL devem fornecer um SecBuffer do tipo SECBUFFER_PADDING.

MessageSeqNo [in]

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 do Digest, esse parâmetro deve ser definido como zero. O SSP do Digest gerencia a numeração de sequência internamente.

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.

Valor retornado

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.

Comentários

A função EncryptMessage (Geral) 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 à detecção de sequência e o chamador fornecer um número de sequência, a função incluirá 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 passado para baixo do aplicativo de transporte.

Ao usar o SSP digest, obtenha o tamanho do buffer de saída chamando a função QueryContextAttributes (Geral) e especificando SECPKG_ATTR_SIZES. A função retornará uma estrutura SecPkgContext_Sizes . O tamanho do buffer de saída é a soma dos valores nos membros cbMaxSignature e cbBlockSize .

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

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

Para obter o desempenho ideal, as estruturas pMessage devem ser alocadas da memória contígua.

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

Requisitos

Confira também

• Funções SSPI
• AcceptSecurityContext (Geral)
• DecryptMessage (Geral)
• InitializeSecurityContext (Geral)
• QueryContextAttributes (Geral)
• Secbuffer
• Secbufferdesc