Freigeben über

EncryptMessage-Funktion (Schannel)

  • Artikel

Die Funktion EncryptMessage (Schannel) verschlüsselt eine Nachricht, um Datenschutz zu gewährleisten. EncryptMessage (Schannel) ermöglicht es einer Anwendung, zwischen kryptografischen Algorithmen zu wählen, die vom ausgewählten Mechanismus unterstützt werden. Die Funktion EncryptMessage (Schannel) verwendet den Sicherheitskontext, auf den das Kontexthandle verweist. Einige Pakete verfügen nicht über Nachrichten, die verschlüsselt oder entschlüsselt werden müssen, sondern stellen stattdessen einen Integritätshash bereit, der überprüft werden kann.

Bei Verwendung des Schannel-SSP verschlüsselt diese Funktion Nachrichten mithilfe eines Sitzungsschlüssels , der mit der Remotepartei ausgehandelt wird, die die Nachricht empfängt. Der Verschlüsselungsalgorithmus wird durch die verwendete [Cipher Suite](cipher-suites-in-schannel.md) bestimmt.

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 EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Parameter

phContext [in]

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

fQOP [in]

Paketspezifische Flags, die die Qualität des Schutzes angeben. Ein Sicherheitspaket kann diesen Parameter verwenden, um die Auswahl kryptografischer Algorithmen zu aktivieren.

Dieser Parameter kann das folgende Flag sein.

Wert Bedeutung
SECQOP_WRAP_OOB_DATA
 Senden Sie eine Schannel-Warnmeldung. In diesem Fall muss der pMessage-Parameter einen standardmäßigen SSL/TLS-Ereigniscode mit zwei Byte enthalten. Dieser Wert wird nur vom Schannel-SSP unterstützt.
Ab Windows Vista muss beispielsweise die vom Server während des Erneutauthentifizierungsprotokolls gesendete Meldung "Server hello" als TLS-Warnung verschlüsselt werden.

pMessage [in, out]

Ein Zeiger auf eine SecBufferDesc-Struktur . Bei der Eingabe verweist die -Struktur auf eine oder mehrere SecBuffer-Strukturen . Einer davon kann vom Typ SECBUFFER_DATA sein. Dieser Puffer enthält die zu verschlüsselnde Nachricht. Die Nachricht wird vor Ort verschlüsselt, wodurch der ursprüngliche Inhalt der Struktur überschrieben wird.

Die Funktion verarbeitet keine Puffer mit dem attribut SECBUFFER_READONLY.

Die Länge der SecBuffer-Struktur , die die Nachricht enthält, darf nicht größer als cbMaximumMessage sein, die von der Funktion QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES) abgerufen wird.

MessageSeqNo [in]

Die Sequenznummer, die die Transportanwendung der Nachricht zugewiesen hat. Wenn die Transportanwendung keine Sequenznummern verwaltet, muss dieser Parameter null sein.

Wenn Sie den Schannel-SSP verwenden, muss dieser Parameter auf 0 (null) festgelegt werden. Der Schannel-SSP verwendet keine Sequenznummern.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion SEC_E_OK zurück.

Wenn die Funktion fehlschlägt, gibt sie einen der folgenden Fehlercodes zurück.

Rückgabecode Beschreibung
SEC_E_BUFFER_TOO_SMALL
 Der Ausgabepuffer ist zu klein. Weitere Informationen finden Sie in den Hinweisen.
SEC_E_CONTEXT_EXPIRED
 Die Anwendung verweist auf einen Kontext, der bereits geschlossen wurde. Eine ordnungsgemäß geschriebene Anwendung sollte diesen Fehler nicht erhalten.
SEC_E_CRYPTO_SYSTEM_INVALID
 Die für den Sicherheitskontext ausgewählte Verschlüsselung wird nicht unterstützt.
SEC_E_INSUFFICIENT_MEMORY
 Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen.
SEC_E_INVALID_HANDLE
 Im parameter phContext wurde ein ungültiges Kontexthandle angegeben.
SEC_E_INVALID_TOKEN
 Es wurde kein SECBUFFER_DATA Typpuffer gefunden.
SEC_E_QOP_NOT_SUPPORTED
 Weder Vertraulichkeit noch Integrität werden vom Sicherheitskontext unterstützt.

Bemerkungen

Die EncryptMessage-Funktion (Schannel) verschlüsselt eine Nachricht basierend auf der Nachricht und dem Sitzungsschlüssel aus einem Sicherheitskontext.

Wenn die Transportanwendung den Sicherheitskontext zur Unterstützung der Sequenzerkennung erstellt hat und der Aufrufer eine Sequenznummer bereitstellt, schließt die Funktion diese Informationen in die verschlüsselte Nachricht ein. Das Einschließen dieser Informationen schützt vor Wiedergabe, Einfügung und Unterdrückung von Nachrichten. Das Sicherheitspaket enthält die Sequenznummer, die von der Transportanwendung übergeben wird.

Bei Verwendung mit dem Schannel-SSP muss der pMessage-Parameter eine SecBufferDesc-Struktur mit den folgenden Puffern enthalten.

Hinweis

Diese Puffer müssen in der angegebenen Reihenfolge bereitgestellt werden.

Puffertyp BESCHREIBUNG
SECBUFFER_STREAM_HEADER Wird intern verwendet. Keine Initialisierung erforderlich.
SECBUFFER_DATA Enthält die zu verschlüsselnde Klartextnachricht .
SECBUFFER_STREAM_TRAILER Wird intern verwendet. Keine Initialisierung erforderlich.
SECBUFFER_EMPTY Wird intern verwendet. Keine Initialisierung erforderlich. Die Größe kann 0 (null) sein.

Wenn Sie den Schannel-SSP verwenden, bestimmen Sie die maximale Größe der einzelnen Puffer, indem Sie die Funktion QueryContextAttributes (Schannel) aufrufen und das attribut SECPKG_ATTR_STREAM_SIZES angeben. Diese Funktion gibt eine SecPkgContext_StreamSizes-Struktur zurück, deren Member die maximalen Größen für den Headerpuffer (cbHeader-Element ), Nachrichten (cbMaximumMessage-Member ) und Trailerpuffer (cbTrailer-Member ) enthalten.

Für eine optimale Leistung sollten die pMessage-Strukturen aus zusammenhängendem Arbeitsspeicher zugeordnet werden.

Windows XP/2000: Diese Funktion wurde auch als SealMessage bezeichnet. Anwendungen sollten jetzt nur EncryptMessage (Schannel) verwenden.

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