Freigeben über

DecryptMessage-Funktion (Schannel)

  • Artikel

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

Diese Funktion wird auch mit dem Schannel Security Support Provider (SSP) verwendet, um eine Anforderung eines Nachrichtensenders für eine Neuverhandlung (Wiederholung) der Verbindungsattribute oder für ein Herunterfahren der Verbindung zu signalisieren.

Hinweis

EncryptMessage (Schannel) und DecryptMessage (Schannel) können gleichzeitig aus zwei verschiedenen Threads in einem einzelnen SSPI-Kontext ( Security Support Provider Interface ) aufgerufen werden, wenn ein Thread verschlüsselt und der andere entschlüsselt. Wenn mehr als ein Thread verschlüsselt wird oder mehrere Threads entschlüsselt werden, sollte jeder Thread einen eindeutigen Kontext erhalten.

Syntax

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

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 eine oder mehrere SecBuffer-Strukturen . Eine davon kann vom Typ SECBUFFER_DATA sein. Dieser Puffer enthält die verschlüsselte Nachricht. Die verschlüsselte Nachricht wird an Ort und Stelle entschlüsselt, wodurch der ursprüngliche Inhalt des Puffers überschrieben wird.

Wenn Sie den Schannel-SSP mit Kontexten verwenden, die nicht verbindungsorientiert sind, muss die Struktur bei der Eingabe vier SecBuffer-Strukturen enthalten. Genau ein Puffer muss vom Typ SECBUFFER_DATA sein und eine verschlüsselte Nachricht enthalten, die bereits entschlüsselt wird. Die verbleibenden Puffer werden für die Ausgabe verwendet und müssen vom Typ SECBUFFER_EMPTY sein. Für verbindungsorientierte Kontexte muss ein SECBUFFER_DATA Typpuffer bereitgestellt werden, wie für nicht verbindungsorientierte Kontexte angegeben. Darüber hinaus muss auch ein zweiter SECBUFFER_TOKEN Typpuffer bereitgestellt werden, der ein Sicherheitstoken enthält.

MessageSeqNo [in]

Die von der Transportanwendung erwartete Sequenznummer, falls vorhanden. Wenn die Transportanwendung keine Sequenznummern verwaltet, muss dieser Parameter auf Null festgelegt werden.

Wenn Sie den Schannel-SSP verwenden, muss dieser Parameter auf 0 (null) festgelegt werden. 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.

Bei Verwendung des Schannel-SSP wird dieser Parameter nicht verwendet und sollte auf NULL festgelegt werden.

Dieser Parameter kann das folgende Flag sein.

Wert Bedeutung
SECQOP_WRAP_NO_ENCRYPT
 Die Nachricht wurde nicht verschlüsselt, aber ein Header oder Trailer wurde erstellt.
Hinweis: KERB_WRAP_NO_ENCRYPT hat den gleichen Wert und die gleiche Bedeutung.

Rückgabewert

Wenn die Funktion überprüft, ob die Nachricht in der richtigen Reihenfolge empfangen wurde, gibt die Funktion SEC_E_OK zurück.

Wenn die Funktion die Nachricht nicht entschlüsseln kann, gibt sie einen der folgenden Fehlercodes zurück.

Rückgabecode Beschreibung
SEC_E_INVALID_HANDLE Im parameter phContext wurde ein ungültiges Kontexthandle angegeben. Wird mit dem Schannel-SSP verwendet.
SEC_E_INVALID_TOKEN Die Puffer haben den falschen Typ, oder es wurde kein Puffer vom Typ SECBUFFER_DATA gefunden. Wird mit dem Schannel-SSP verwendet.
SEC_E_MESSAGE_ALTERED Die Nachricht wurde geändert. Wird mit dem Schannel-SSP verwendet.
SEC_E_OUT_OF_SEQUENCE Die Nachricht wurde nicht in der richtigen Reihenfolge empfangen.
SEC_I_CONTEXT_EXPIRED Der Absender der Nachricht hat die Verwendung der Verbindung beendet und ein Herunterfahren initiiert. Informationen zum Initiieren oder Erkennen eines Herunterfahrens finden Sie unter Herunterfahren einer Schannel-Verbindung. Wird mit dem Schannel-SSP verwendet.
SEC_I_RENEGOTIATE Die Remotepartei benötigt eine neue Handshakesequenz, oder die Anwendung hat gerade ein Herunterfahren initiiert. Kehren Sie zur Aushandlungsschleife zurück, und rufen Sie AcceptSecurityContext (Schannel) oder InitializeSecurityContext (Schannel) auf, übergeben Sie SECBUFFER_EXTRA von DecryptMessage() zurückgegeben.

Hinweise

Manchmal liest eine Anwendung Daten von der Remotepartei, versucht, sie mithilfe von DecryptMessage (Schannel) zu entschlüsseln, und ermittelt, dass DecryptMessage (Schannel) erfolgreich war, aber die Ausgabepuffer leer sind. Dies ist ein normales Verhalten, und Anwendungen müssen in der Lage sein, damit umzugehen.

Wenn Sie den Schannel-SSP verwenden, gibt die DecryptMessage-Funktion (Allgemein) SEC_I_CONTEXT_EXPIRED zurück, wenn der Nachrichtensender die Verbindung beendet hat. 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 bei jedem Aufruf anpassen, um eine ganze Nachricht zu entschlüsseln.

Die DecryptMessage-Funktion (Schannel) gibt SEC_I_RENEGOTIATE zurück, wenn eine TLS-Protokollnachricht nach dem Handshake als Anwendungsdaten empfangen wird. Sobald die DecryptMessage-Funktion (Schannel) SEC_I_RENEGOTIATE zurückgegeben hat, schlagen alle weiteren EncryptMessage() - und DecryptMessage()-Aufrufe mit SEC_E_CONTEXT_EXPIRED fehl. Eine Anwendung behandelt diese Situation, indem Sie AcceptSecurityContext (Schannel) ( serverseitig) oder InitializeSecurityContext (Schannel) (Clientseite) aufruft und SECBUFFER_EXTRA übergeben, die von DecryptMessage() zurückgegeben werden. Nachdem dieser anfängliche Aufruf einen Wert zurückgegeben hat, fahren Sie so 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

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Header Sspi.h (einschließlich Security.h)
Bibliothek Secur32.lib
DLL Secur32.dll

Siehe auch