DecryptMessage (Schannel)-Funktion

Die Funktion DecryptMessage (Schannel) entschlüsselt eine Nachricht. Einige Pakete verschlüsseln und entschlüsseln keine Nachrichten, sondern führen einen Integritätshash aus und überprüfen sie.

Verwenden Sie diese Funktion mit dem Schannel Security Support Provider (SSP), um eine Anforderung eines Nachrichtenabsenders für eine Neuverhandlung (Wiederholen) der Verbindungsattribute oder für ein Herunterfahren der Verbindung zu signalisieren.

Syntax

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

Die Parameter

phContext [in]

Ein Handle für den Sicherheitskontext , der zum Entschlüsseln der Nachricht verwendet werden soll.

pMessage [in, out]

Ein Zeiger auf eine SecBufferDesc-Struktur . Bei der Eingabe verweist die Struktur auf mindestens eine SecBuffer-Struktur . Einer dieser Puffer kann vom Typ SECBUFFER_DATA sein. Dieser Puffer enthält die verschlüsselte Nachricht. Die Funktion entschlüsselt die verschlüsselte Nachricht an Ort und Stelle, wobei der ursprüngliche Inhalt des Puffers überschrieben wird.

Wenn Sie den Schannel-SSP mit Kontexten verwenden, die nicht verbindungsorientiert sind, muss die Struktur vier SecBuffer-Strukturen für eingaben enthalten. Genau ein Puffer muss vom Typ SECBUFFER_DATA sein und eine verschlüsselte Nachricht enthalten, die die Funktion an Ort und Stelle entschlüsselt. Die verbleibenden Puffer werden für die Ausgabe verwendet und müssen vom Typ SECBUFFER_EMPTY sein. Für verbindungsorientierte Kontexte müssen Sie einen SECBUFFER_DATA Typpuffer angeben, wie für nicht verbindungsorientierte Kontexte angegeben. Darüber hinaus müssen Sie einen zweiten SECBUFFER_TOKEN Typpuffer bereitstellen, der ein Sicherheitstoken enthält.

MessageSeqNo [in]

Die Sequenznummer, die von der Transportanwendung erwartet wird, falls vorhanden. Wenn die Transportanwendung keine Sequenznummern verwaltet, legen Sie diesen Parameter auf Null fest.

Wenn Sie den Schannel-SSP verwenden, legen Sie diesen Parameter auf Null fest. Der Schannel-SSP verwendet keine Sequenznummern.

pfQOP [out]

Ein Zeiger auf eine Variable vom Typ ULONG , die paketspezifische Flags empfängt, die die Qualität des Schutzes angeben.

Wenn Sie den Schannel-SSP verwenden, verwenden Sie diesen Parameter nicht. Legen Sie ihn auf NULL fest.

Dieser Parameter kann die folgende Kennzeichnung sein.

Rückgabewert

Wenn die Funktion überprüft, ob die Nachricht in der richtigen Reihenfolge empfangen wird, wird SEC_E_OK zurückgegeben.

Wenn die Funktion die Nachricht nicht entschlüsseln kann, wird eine der folgenden Fehlercodes zurückgegeben.

Bemerkungen

Manchmal liest eine Anwendung Daten von der Remotepartei, versucht, sie mithilfe von DecryptMessage (Schannel) zu entschlüsseln, und ermittelt, dass DecryptMessage (Schannel) erfolgreich ist, aber die Ausgabepuffer sind leer. Dieses Verhalten ist normal, und Anwendungen müssen sie verarbeiten können.

Wenn Sie den Schannel-SSP verwenden, gibt die Funktion DecryptMessage (General) SEC_I_CONTEXT_EXPIRED zurück, wenn der Absender der Nachricht die Verbindung heruntergefahren. Informationen zum Initiieren oder Erkennen eines Herunterfahrens finden Sie unter Herunterfahren einer Schannel-Verbindung.

Wenn Sie TLS 1.0 verwenden, müssen Sie diese Funktion möglicherweise mehrmals aufrufen und den Eingabepuffer für jeden Aufruf anpassen, um eine ganze Nachricht zu entschlüsseln.

Die DecryptMessage (Schannel) -Funktion gibt SEC_I_RENEGOTIATE zurück, wenn sie eine andere TLS-Protokollnachricht nach handshake als Anwendungsdaten empfängt. Sobald DecryptMessage (Schannel) SEC_I_RENEGOTIATE zurückgibt, schlagen alle weiteren EncryptMessage() und DecryptMessage()-Aufrufe mit SEC_E_CONTEXT_EXPIRED fehl. Eine Anwendung behandelt diese Situation durch Aufrufen von AcceptSecurityContext (Schannel) ( Serverseite) oder InitializeSecurityContext (Schannel) ( Clientseite) und Übergeben desselben Puffers wie von DecryptMessage geändert, um sicherzustellen, dass der SecBuffer Typ auf SECBUFFER_TOKEN". Beachten Sie, dass DecryptMessage beim Zurückgeben nicht immer einen SECBUFFER_EXTRA Puffer SEC_I_RENEGOTIATE zurückgibt. Nachdem dieser anfängliche Aufruf einen Wert zurückgegeben hat, fahren Sie fort, als ob ihre Anwendung eine neue Verbindung erstellt. Anschließend kann die Anwendung weiterhin EncryptMessage() und DecryptMessage() aufrufen. Weitere Informationen finden Sie unter Erstellen eines Schannel-Sicherheitskontexts.

Anforderungen

Verwandte Inhalte

• SSPI-Funktionen
• EncryptMessage (Schannel)
• SecBuffer