DecryptMessage -functie (Schannel)

De functie DecryptMessage (Schannel) ontsleutelt een bericht. Sommige pakketten versleutelen en ontsleutelen berichten niet, maar voeren een integriteits-hash uit en controleren.

Gebruik deze functie met de Schannel-beveiligingsondersteuningsprovider (SSP) om een aanvraag van een afzender van een bericht te signaleren voor een heronderhandeling (opnieuw) van de verbindingskenmerken of voor het afsluiten van de verbinding.

Syntaxis

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

Parameterwaarden

phContext [in]

Een ingang voor de beveiligingscontext die moet worden gebruikt voor het ontsleutelen van het bericht.

pMessage [in, uit]

Een aanwijzer naar een SecBufferDesc-structuur . Bij invoer verwijst de structuur naar een of meer SecBuffer-structuren . Een van deze buffers kan van het type SECBUFFER_DATA zijn. Deze buffer bevat het versleutelde bericht. De functie ontsleutelt het versleutelde bericht, waarbij de oorspronkelijke inhoud van de buffer wordt overschreven.

Wanneer u de Schannel-SSP gebruikt met contexten die niet zijn verbonden, moet de structuur vier SecBuffer-structuren bevatten voor invoer. Precies één buffer moet van het type SECBUFFER_DATA zijn en een versleuteld bericht bevatten, dat door de functie wordt ontsleuteld. De resterende buffers worden gebruikt voor uitvoer en moeten van het type SECBUFFER_EMPTY zijn. Voor verbindingsgerichte contexten moet u een SECBUFFER_DATA typebuffer opgeven, zoals aangegeven voor niet-verbonden contexten. Daarnaast moet u een tweede SECBUFFER_TOKEN typebuffer opgeven die een beveiligingstoken bevat.

MessageSeqNo [in]

Het volgnummer dat wordt verwacht door de transporttoepassing, indien van toepassing. Als de transporttoepassing geen volgnummers onderhoudt, stelt u deze parameter in op nul.

Wanneer u de Schannel-SSP gebruikt, stelt u deze parameter in op nul. De Schannel-SSP gebruikt geen volgnummers.

pfQOP [out]

Een aanwijzer naar een variabele van het type ULONG die pakketspecifieke vlaggen ontvangt die de kwaliteit van de beveiliging aangeven.

Gebruik deze parameter niet wanneer u de Schannel-SSP gebruikt. Stel deze in op NULL.

Deze parameter kan de volgende vlag zijn.

Retourwaarde

Als de functie controleert of het bericht in de juiste volgorde wordt ontvangen, wordt SEC_E_OK geretourneerd.

Als de functie het bericht niet kan ontsleutelen, wordt een van de volgende foutcodes geretourneerd.

Opmerkingen

Soms leest een toepassing gegevens van de externe partij, probeert deze te ontsleutelen met behulp van DecryptMessage (Schannel) en ontdekt dat DecryptMessage (Schannel) slaagt, maar de uitvoerbuffers leeg zijn. Dit gedrag is normaal en toepassingen moeten dit kunnen verwerken.

Wanneer u de Schannel-SSP gebruikt, retourneert de functie DecryptMessage (Algemeen) SEC_I_CONTEXT_EXPIRED wanneer de afzender van het bericht de verbinding afsluit. Zie Een Schannel-verbinding afsluitenvoor meer informatie over het initiëren of herkennen van een afsluiting.

Als u TLS 1.0 gebruikt, moet u deze functie mogelijk meerdere keren aanroepen, de invoerbuffer voor elke aanroep aanpassen om een heel bericht te ontsleutelen.

De functie DecryptMessage (Schannel) retourneert SEC_I_RENEGOTIATE wanneer er een bericht over het TLS-protocol na handshake wordt ontvangen, behalve toepassingsgegevens. Zodra DecryptMessage (Schannel) SEC_I_RENEGOTIATE retourneert, mislukken verdere EncryptMessage() en DecryptMessage() aanroepen met SEC_E_CONTEXT_EXPIRED. Een toepassing verwerkt deze situatie door AcceptSecurityContext (Schannel) ( serverzijde) of InitializeSecurityContext (Schannel) ( clientzijde) aan te roepen en dezelfde buffer door te geven als gewijzigd door DecryptMessage, zodat het SecBuffer type is ingesteld op SECBUFFER_TOKEN. Houd er rekening mee dat DecryptMessage niet altijd een SECBUFFER_EXTRA buffer retourneert wanneer SEC_I_RENEGOTIATE deze wordt geretourneerd. Nadat deze eerste aanroep een waarde retourneert, gaat u verder alsof uw toepassing een nieuwe verbinding maakt. Vervolgens kan de toepassing EncryptMessage() en DecryptMessage() blijven aanroepen. Zie Een Schannel-beveiligingscontext maken voor meer informatie.

Vereisten

Verwante inhoud

• SSPI-functies
• EncryptMessage (Schannel)
• SecBuffer