Delen via

De functie EncryptMessage (Schannel)

De functie EncryptMessage (Schannel) versleutelt een bericht om privacy te bieden. Met EncryptMessage (Schannel) kan een toepassing kiezen uit cryptografische algoritmen die worden ondersteund door het gekozen mechanisme. De functie EncryptMessage (Schannel) maakt gebruik van de beveiligingscontext waarnaar wordt verwezen door de contextgreep. Sommige pakketten hebben geen berichten die moeten worden versleuteld of ontsleuteld, maar bieden eerder een integriteitshash die kan worden gecontroleerd.

Wanneer u de Schannel-SSP gebruikt, worden met deze functie berichten versleuteld met behulp van een sessiesleutel die is onderhandeld met de externe partij die het bericht ontvangt. Het versleutelingsalgoritmen worden bepaald door de [coderingssuite ](cipher-suites-in-schannel.md) die wordt gebruikt.

Opmerking

EncryptMessage (Schannel) en DecryptMessage (Schannel) kunnen tegelijkertijd worden aangeroepen vanuit twee verschillende threads in één SSPI-context ( Security Support Provider Interface ) als één thread wordt versleuteld en de andere wordt ontsleuteld. Als meer dan één thread wordt versleuteld of meer dan één thread ontsleutelt, moet elke thread een unieke context verkrijgen.

Syntaxis

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

Parameterwaarden

phContext [in]

Een ingang voor de beveiligingscontext die moet worden gebruikt om het bericht te versleutelen.

fQOP [in]

Pakketspecifieke vlaggen die de kwaliteit van de beveiliging aangeven. Een beveiligingspakket kan deze parameter gebruiken om de selectie van cryptografische algoritmen in te schakelen.

Deze parameter kan de volgende vlag zijn.

Waarde Betekenis
SECQOP_WRAP_OOB_DATA
 Een Schannel-waarschuwingsbericht verzenden. In dit geval moet de parameter pMessage een standaard twee-byte SSL/TLS-gebeurteniscode bevatten. Deze waarde wordt alleen ondersteund door de Schannel-SSP.
Vanaf Windows Vista moet bijvoorbeeld het bericht 'server hello' dat tijdens het re-authentication-protocol door de server wordt verzonden, worden versleuteld als een TLS-waarschuwing.

pMessage [in, uit]

Een aanwijzer naar een SecBufferDesc-structuur . Bij invoer verwijst de structuur naar een of meer SecBuffer-structuren . Een van deze kan van het type SECBUFFER_DATA zijn. Deze buffer bevat het bericht dat moet worden versleuteld. Het bericht is versleuteld, waarbij de oorspronkelijke inhoud van de structuur wordt overschreven.

De functie verwerkt geen buffers met het kenmerk SECBUFFER_READONLY.

De lengte van de SecBuffer-structuur die het bericht bevat, mag niet groter zijn dan cbMaximumMessage, die wordt verkregen met de functie QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES).

MessageSeqNo [in]

Het volgnummer dat de transporttoepassing aan het bericht heeft toegewezen. Als de transporttoepassing geen volgnummers onderhoudt, moet deze parameter nul zijn.

Wanneer u de Schannel-SSP gebruikt, moet deze parameter worden ingesteld op nul. De Schannel-SSP gebruikt geen volgnummers.

Retourwaarde

Als de functie slaagt, retourneert de functie SEC_E_OK.

Als de functie mislukt, wordt een van de volgende foutcodes geretourneerd.

Retourcode Beschrijving
SEC_E_BUFFER_TOO_SMALL
 De uitvoerbuffer is te klein. Zie Opmerkingen voor meer informatie.
SEC_E_CONTEXT_EXPIRED
 De toepassing verwijst naar een context die al is gesloten. Een correct geschreven toepassing mag deze fout niet ontvangen.
SEC_E_CRYPTO_SYSTEM_INVALID
 De gekozen codering voor de beveiligingscontext wordt niet ondersteund.
SEC_E_INSUFFICIENT_MEMORY
 Er is onvoldoende geheugen beschikbaar om de aangevraagde actie te voltooien.
SEC_E_INVALID_HANDLE
 Er is een contextgreep opgegeven die niet geldig is in de parameter phContext .
SEC_E_INVALID_TOKEN
 Er is geen SECBUFFER_DATA typebuffer gevonden.
SEC_E_QOP_NOT_SUPPORTED
 Vertrouwelijkheid en integriteit worden niet ondersteund door de beveiligingscontext.

Opmerkingen

De functie EncryptMessage (Schannel) versleutelt een bericht op basis van het bericht en de sessiesleutel vanuit een beveiligingscontext.

Als de transporttoepassing de beveiligingscontext heeft gemaakt ter ondersteuning van reeksdetectie en de aanroeper een volgnummer biedt, bevat de functie deze informatie met het versleutelde bericht. Het opnemen van deze informatie beschermt tegen opnieuw afspelen, invoegen en onderdrukken van berichten. Het beveiligingspakket bevat het volgnummer dat is doorgegeven vanuit de transporttoepassing.

Bij gebruik met de Schannel-SSP moet de parameter pMessage een SecBufferDesc-structuur bevatten met de volgende buffers.

Opmerking

Deze buffers moeten worden opgegeven in de weergegeven volgorde.

Buffertype Beschrijving
SECBUFFER_STREAM_HEADER Intern gebruikt. Er is geen initialisatie vereist.
SECBUFFER_DATA Bevat het bericht zonder opmaak dat moet worden versleuteld.
SECBUFFER_STREAM_TRAILER Intern gebruikt. Er is geen initialisatie vereist.
SECBUFFER_EMPTY Intern gebruikt. Er is geen initialisatie vereist. Grootte kan nul zijn.

Wanneer u de Schannel-SSP gebruikt, bepaalt u de maximale grootte van elk van de buffers door de functie QueryContextAttributes (Schannel) aan te roepen en het kenmerk SECPKG_ATTR_STREAM_SIZES op te geven. Deze functie retourneert een SecPkgContext_StreamSizes structuur waarvan de leden de maximale grootten voor de koptekst (cbHeader-lid ), bericht (cbMaximumMessage-lid ) en trailerbuffers (cbTrailer member) bevatten.

Voor optimale prestaties moeten de pMessage-structuren worden toegewezen vanuit aaneengesloten geheugen.

Windows XP/2000: Deze functie werd ook wel SealMessage genoemd. Toepassingen mogen nu alleen EncryptMessage (Schannel) gebruiken.

Vereisten

Voorwaarde Waarde
Minimaal ondersteunde client Windows XP [alleen desktop-apps]
Minimaal ondersteunde server Windows Server 2003 [alleen desktop-apps]
Koptekst Sspi.h (inclusief Security.h)
Bibliotheek Secur32.lib
DLL Secur32.dll

Zie ook

  • Last updated on