EncryptMessage-Funktion (sspi.h)

Artikel
08/26/2023

Die Funktion EncryptMessage (Digest) verschlüsselt eine Nachricht, um Datenschutz zu gewährleisten. EncryptMessage (Digest) ermöglicht der Anwendung die Auswahl zwischen kryptografischen Algorithmen , die vom ausgewählten Mechanismus unterstützt werden. Die Funktion EncryptMessage (Digest) 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.

Diese Funktion ist nur als SASL-Mechanismus verfügbar.

HinweisEncryptMessage (Digest) und DecryptMessage (Digest) 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]      unsigned long  fQOP,
  [in, out] PSecBufferDesc pMessage,
  [in]      unsigned long  MessageSeqNo
);

Parameter

[in] phContext

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

[in] fQOP

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

Bei Verwendung des Digest-SSP muss dieser Parameter auf 0 festgelegt werden.

[in, out] pMessage

Ein Zeiger auf eine SecBufferDesc-Struktur . Bei der Eingabe verweist die Struktur auf eine oder mehrere SecBuffer-Strukturen , die vom Typ SECBUFFER_DATA sein können. 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, das von der Funktion QueryContextAttributes (Digest) (SECPKG_ATTR_STREAM_SIZES) abgerufen wird.

Bei Verwendung des Digest-SSP muss ein zweiter Puffer vom Typ SECBUFFER_PADDING oder SEC_BUFFER_DATA vorhanden sein, um Signaturinformationen zu enthalten. Um die Größe des Ausgabepuffers abzurufen, rufen Sie die Funktion QueryContextAttributes (Digest) 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 Elementen cbMaxSignature und cbBlockSize .

Anwendungen, die ssl nicht verwenden, müssen einen SecBuffer vom Typ SECBUFFER_PADDING bereitstellen.

[in] MessageSeqNo

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

Bei Verwendung des Digest-SSP muss dieser Parameter auf 0 festgelegt werden. Der Digest-SSP verwaltet die Sequenznummerierung intern.

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.

Hinweise

Die Funktion EncryptMessage (Digest) 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.

Wenn Sie den Digest-SSP verwenden, rufen Sie die Größe des Ausgabepuffers ab, indem Sie die Funktion QueryContextAttributes (Digest) 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 Elementen cbMaxSignature und cbBlockSize .

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.

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

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

Anforderungen


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