EncryptMessage(General)-Funktion

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

Wenn Sie den SSP (Digest Security Support Provider) verwenden, ist diese Funktion nur als SASL-Mechanismus verfügbar.

Bei Verwendung des Schannel-SSP verschlüsselt diese Funktion Nachrichten mithilfe eines Sitzungsschlüssels, der mit der Remote-Partei ausgehandelt wird, die die Nachricht erhält. Der Verschlüsselungsalgorithmus wird von der verwendeten [ Verschlüsselungssammlung](cipher-suites-in-schannel.md) bestimmt.

Hinweis

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

Informationen zur Verwendung dieser Funktion mit einem bestimmten SSP finden Sie in den folgenden Themen.

Thema Beschreibung
EncryptMessage (Digest) Verschlüsselt eine Nachricht, um Datenschutz mithilfe von Digest zu gewährleisten.
EncryptMessage (Kerberos) Verschlüsselt eine Nachricht, um Datenschutz mithilfe von Kerberos bereitzustellen.
EncryptMessage (Negotiate) Verschlüsselt eine Nachricht mit negotiate, um Datenschutz zu gewährleisten.
EncryptMessage (NTLM) Verschlüsselt eine Nachricht, um Datenschutz mit ntlm zu gewährleisten.
EncryptMessage (Schannel) Verschlüsselt eine Nachricht mit schannel, um Datenschutz zu gewährleisten.

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.

Wenn Sie den Digest-SSP verwenden, muss dieser Parameter auf 0 (null) festgelegt werden.

Dieser Parameter kann eines der folgenden Flags sein.

Wert Bedeutung
SECQOP_WRAP_NO_ENCRYPT
Erstellen Sie einen Header oder Nachspann, verschlüsseln Sie die Nachricht jedoch nicht.
[!Note]
KERB_WRAP_NO_ENCRYPT hat den gleichen Wert und dieselbe Bedeutung.

SECQOP_WRAP_OOB_DATA
Senden sie eine Schannel-Warnmeldung. In diesem Fall muss der pMessage-Parameter einen standardmäßigen SSL/TLS-Standardereigniscode mit zwei Byte enthalten. Dieser Wert wird nur vom Schannel-SSP unterstützt.

pMessage [ in, out]

Ein Zeiger auf eine SecBufferDesc-Struktur. Bei der Eingabe verweist die -Struktur auf eine oder mehrere SecBuffer-Strukturen. Eine dieser Typen kann vom Typ SECBUFFER _ DATA sein. Dieser Puffer enthält die zu verschlüsselnde Nachricht. Die Nachricht wird an Ort und Stelle verschlüsselt und überschreiben den ursprünglichen Inhalt der -Struktur.

Die Funktion verarbeiten keine Puffer mit dem SECBUFFER _ READONLY-Attribut.

Die Länge der SecBuffer-Struktur, die die Nachricht enthält, darf nicht größer als cbMaximumMessage sein, die von der Funktion QueryContextAttributes (General) (SECPKG _ ATTR _ STREAM _ SIZES) abgerufen wird.

Bei Verwendung des Digest-SSP muss ein zweiter Puffer vom Typ SECBUFFER PADDING oder SEC BUFFER DATA zum Enthalten _ _ von _ Signaturinformationen enthalten sein. Um die Größe des Ausgabepuffers zu erhalten, rufen Sie die QueryContextAttributes (General)-Funktion auf, und geben Sie SECPKG _ ATTR _ SIZES an. Die Funktion gibt eine SecPkgContext _ Sizes-Struktur zurück. Die Größe des Ausgabepuffers ist die Summe der Werte in den Membern cbMaxSignature und cbBlockSize.

Anwendungen, die kein SSL verwenden, müssen einen SecBuffer vom Typ SECBUFFER _ PADDING zur Verfügung stellen.

MessageSeqNo [ In]

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

Wenn Sie den Digest-SSP verwenden, muss dieser Parameter auf 0 (null) festgelegt werden. Der Digest-SSP verwaltet die Sequenznummerierung intern.

Bei Verwendung des Schannel-SSP 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, wird einer der folgenden Fehlercodes zurückgegeben.

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 bezieht sich 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.
_S.E _ NICHT GENÜGEND _ ARBEITSSPEICHER Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abschließen zu können.
SEC _ E _ UNGÜLTIGES _ HANDLE Im phContext-Parameter wurde ein ungültiges Kontexthand handle angegeben.
SEC _ E _ UNGÜLTIGES _ TOKEN Es wurde kein _ SECBUFFER-DATENTYPpuffer gefunden.
SEC _ E _ QOP _ NOT _ SUPPORTED Weder Vertraulichkeit noch Integrität werden vom Sicherheitskontext unterstützt.

Hinweise

Die EncryptMessage (General)-Funktion 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 enthält, schließt die Funktion diese Informationen in die verschlüsselte Nachricht ein. Das Einfügen dieser Informationen schützt vor Wiedergabe, Einfügung und Unterdrückung von Nachrichten. Das Sicherheitspaket enthält die Sequenznummer, die von der Transportanwendung übergeben wurde.

Wenn Sie den Digest-SSP verwenden, rufen Sie die Größe des Ausgabepuffers ab, indem Sie die QueryContextAttributes (General)-Funktion aufrufen und SECPKG _ ATTR _ SIZES angeben. Die Funktion gibt eine SecPkgContext _ Sizes-Struktur zurück. Die Größe des Ausgabepuffers ist die Summe der Werte in den Membern cbMaxSignature und cbBlockSize.

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 angezeigten Reihenfolge angegeben werden.

Puffertyp Beschreibung
_SECBUFFER-STREAMHEADER _ Wird intern verwendet. Es ist keine Initialisierung erforderlich.
_SECBUFFER-DATEN 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 QueryContextAttributes (General)-Funktion aufrufen und das SECPKG _ ATTR _ STREAM _ SIZES-Attribut angeben. Diese Funktion gibt eine SecPkgContext _ StreamSizes-Struktur zurück, deren Member die maximalen Größen für die Puffer header (cbHeader member), message (cbMaximumMessage member) und trailer (cbTrailer member) enthalten.

Um eine optimale Leistung zu erzielen, sollten die pMessage-Strukturen aus zusammenhängendem Speicher zugeordnet werden.

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

Anforderungen

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

Siehe auch