EncryptMessage (Allgemein)

Die EncryptMessage -Funktion (Allgemein) verschlüsselt eine Nachricht, um Datenschutz bereitzustellen. EncryptMessage (Allgemein) ermöglicht es einer Anwendung, zwischen kryptografischen Algorithmen auszuwählen, die vom ausgewählten Mechanismus unterstützt werden. Die EncryptMessage -Funktion (Allgemein) verwendet den Sicherheitskontext , auf den vom Kontexthandle verwiesen wird. Einige Pakete verfügen nicht über Nachrichten, die verschlüsselt oder entschlüsselt werden sollen, sondern stellen einen Integritätshash bereit, der überprüft werden kann.

Wenn Sie den Digest-Sicherheitsunterstützungsanbieter (Digest Security Support Provider , SSP) 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 Remotepartei ausgehandelt wird, die die Nachricht empfängt. Der Verschlüsselungsalgorithmus wird durch die verwendete [Cipher-Suite ](cipher-suites-in-schannel.md) bestimmt.

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

Syntax

SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Die 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 ermöglichen.

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

Dieser Parameter kann eine der folgenden Flags sein.

pMessage [in, out]

Ein Zeiger auf eine SecBufferDesc-Struktur . Bei der Eingabe verweist die Struktur auf mindestens eine SecBuffer-Struktur . Eine dieser Typen kann SECBUFFER_DATA sein. Dieser Puffer enthält die zu verschlüsselnde Nachricht. Die Nachricht ist verschlüsselt und überschreibt den ursprünglichen Inhalt der Struktur.

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 QueryContextAttributes (General) (SECPKG_ATTR_STREAM_SIZES)-Funktion 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. Rufen Sie zum Abrufen der Größe des Ausgabepuffers die QueryContextAttributes -Funktion (General) 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 SSL nicht verwenden, müssen einen SecBuffer vom Typ SECBUFFER_PADDING bereitstellen.

MessageSeqNo [in]

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

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

Bei Verwendung des Schannel-SSP muss dieser Parameter auf 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 eine der folgenden Fehlercodes zurückgegeben.

Bemerkungen

Die EncryptMessage -Funktion (Allgemein) 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, enthält die Funktion diese Informationen mit der verschlüsselten Nachricht. 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 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.

Wenn Sie den Schannel-SSP verwenden, bestimmen Sie die maximale Größe der einzelnen Puffer, indem Sie die QueryContextAttributes (General)- Funktion 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 die Headerpuffer (cbHeader Member), Nachrichten (cbMaximumMessage-Member ) und Trailerpuffer (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

Siehe auch

• SSPI-Funktionen
• AcceptSecurityContext (Allgemein)
• DecryptMessage (Allgemein)
• InitializeSecurityContext (Allgemein)
• QueryContextAttributes (General)
• SecBuffer-
• SecBufferDesc-