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.
Observação
EncryptMessage (Geral) e DecryptMessage (Geral) 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.
Para obter informações sobre como usar essa função com um SSP específico, consulte os tópicos a seguir.
| Tópico | Descrição |
|---|---|
| EncryptMessage (Digest) | Criptografa uma mensagem para fornecer privacidade usando o Digest. |
| EncryptMessage (Kerberos) | Criptografa uma mensagem para fornecer privacidade usando Kerberos. |
| EncryptMessage (Negociar) | Criptografa uma mensagem para fornecer privacidade usando Negociar. |
| EncryptMessage (NTLM) | Criptografa uma mensagem para fornecer privacidade usando o NTLM. |
| EncryptMessage (Schannel) | Criptografa uma mensagem para fornecer privacidade usando o Schannel. |
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.
| Valor | Significado |
|---|---|
|
SECQOP_WRAP_NO_ENCRYPT |
Produza um cabeçalho ou trailer, mas não criptografe a mensagem. Nota: KERB_WRAP_NO_ENCRYPT tem o mesmo valor e o mesmo significado. |
|
Enviar uma mensagem de alerta do Schannel. Nesse caso, o parâmetro pMessage deve conter um código de evento SSL/TLS de dois bytes padrão. Esse valor é compatível apenas com o SSP do Schannel. |
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.
| Código de retorno | Descrição |
|---|---|
| SEC_E_BUFFER_TOO_SMALL | O buffer de saída é muito pequeno. Para obter mais informações, consulte Comentários. |
| 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 | Não há suporte para a criptografia escolhida para o contexto de segurança . |
| 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 | Não há suporte para confidencialidade nem integridade no contexto de segurança. |
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.
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 sem formatação 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 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
| 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 |
|
| Biblioteca |
|
| DLL |
|