SaslInitializeSecurityContextW-Funktion (sspi.h)

Artikel
08/26/2023

Die SaslInitializeSecurityContext-Funktion umschließt einen Standardaufruf der Funktion Security Support Provider Interface InitializeSecurityContext (Allgemein) und verarbeitet SASL-Servercookies vom Server.

Syntax

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextW(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPWSTR         pszTargetName,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  Reserved1,
  [in]            unsigned long  TargetDataRep,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  Reserved2,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Parameter

[in] phCredential

Ein Handle für die von zurückgegebenen Anmeldeinformationen
AcquireCredentialsHandle-Funktion , die zum Erstellen des Sicherheitskontexts verwendet wird. Die Verwendung der SaslInitializeSecurityContext-Funktion erfordert mindestens OUTBOUND-Anmeldeinformationen.

[in] phContext

Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf der SaslInitializeSecurityContext-Funktion ist dieser Zeiger NULL. Beim zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilgeformten Kontext, der im phNewContext-Parameter vom ersten Aufruf zurückgegeben wird.

[in] pszTargetName

Zeiger auf eine Unicode- oder ANSI-Zeichenfolge, die das Ziel des Kontexts angibt.

[in] fContextReq

Bitflags, die die Anforderungen des Kontexts angeben. Für diesen Parameter verwendete Flags wird ISC_REQ_ vorangestellt. Beispiel: ISC_REQ_DELEGATE. Geben Sie Kombinationen der folgenden Attributflags an.

Wert	Bedeutung
ISC_REQ_REPLAY_DETECT	Erkennen von wiedergegebenen Paketen.
ISC_REQ_SEQUENCE_DETECT	Erkennen von Nachrichten, die außerhalb der Reihenfolge empfangen werden.
ISC_REQ_CONFIDENTIALITY	Verschlüsseln von Nachrichten.
ISC_REQ_STREAM	Unterstützung einer streamorientierten Verbindung.
ISC_REQ_EXTENDED_ERROR	Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ISC_REQ_CONNECTION	Der Sicherheitskontext behandelt keine Formatierungsmeldungen.
ISC_REQ_MUTUAL_AUTH	Client und Server werden authentifiziert.
ISC_REQ_INTEGRITY	Signieren von Nachrichten und Überprüfen von Signaturen.

Weitere Beschreibungen der verschiedenen Attribute finden Sie unter Kontextanforderungen.

[in] Reserved1

Reservierter Wert; muss null sein.

[in] TargetDataRep

Gibt die Datendarstellung an, z. B. die Bytereihenfolge, auf dem Ziel. Kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.

[in] pInput

Zeiger auf eine SecBufferDesc-Struktur , die Zeiger auf die Puffer enthält, die als Eingabe für das Paket bereitgestellt werden. Der Zeiger muss beim ersten Aufruf der Funktion NULL sein. Bei nachfolgenden Aufrufen der Funktion handelt es sich um einen Zeiger auf einen Puffer, der über genügend Arbeitsspeicher verfügt, um das vom Remotepeer zurückgegebene Token zu speichern.

SASL erfordert einen einzelnen Puffer vom Typ SECBUFFER_TOKEN , der die vom Server empfangene Anforderung enthält.

[in] Reserved2

Reservierter Wert; muss null sein.

[out] phNewContext

Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf der SaslInitializeSecurityContext-Funktion empfängt dieser Zeiger das neue Kontexthandle. Beim zweiten Aufruf kann phNewContext mit dem im parameter phContext angegebenen Handle identisch sein.

[in, out] pOutput

Zeiger auf eine SecBufferDesc-Struktur , die Zeiger auf die SecBuffer-Struktur enthält, die die Ausgabedaten empfängt. Wenn ein Puffer als SEC_READWRITE in der Eingabe eingegeben wurde, ist er bei der Ausgabe vorhanden. Das System ordnet einen Puffer für das Sicherheitstoken zu, wenn es angefordert wird (über ISC_REQ_ALLOCATE_MEMORY) und füllt die Adresse im Pufferdeskriptor für das Sicherheitstoken ein.

[out] pfContextAttr

Zeiger auf eine Variable, um eine Reihe von Bitflags zu empfangen, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Für diesen Parameter verwendete Flags wird ISC_RET_ vorangestellt, z. B. ISC_RET_DELEGATE.

Eine Liste der gültigen Werte finden Sie im fContextReq-Parameter .

Überprüfen Sie erst nach sicherheitsbezogenen Attributen, bis der endgültige Funktionsaufruf erfolgreich zurückgegeben wird. Attributflags, die sich nicht auf die Sicherheit beziehen, z. B. das ASC_RET_ALLOCATED_MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.

Hinweis Bestimmte Kontextattribute können sich während einer Aushandlung mit einem Remotepeer ändern.

[out, optional] ptsExpiry

Zeiger auf eine TimeStamp-Struktur , die die Ablaufzeit des Kontexts empfängt. Es wird empfohlen, dass das Sicherheitspaket diesen Wert immer in Ortszeit zurückgibt. Dieser Parameter ist optional, und NULL sollte für kurzlebige Clients übergeben werden.

Rückgabewert

Wenn der Aufruf erfolgreich abgeschlossen wurde, gibt diese Funktion SEC_E_OK zurück. In der folgenden Tabelle sind einige mögliche Fehlerrückgabewerte aufgeführt.

Rückgabecode	Beschreibung
SEC_E_ALGORITHM_MISMATCH	Eine Authentifizierungsverarbeitung ist nicht zulässig.
SEC_E_INSUFFICIENT_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um die Anforderung abzuschließen.
SEC_E_INVALID_TOKEN	Im pOutput-Parameter befindet sich kein Tokenpuffer, oder die Nachricht konnte nicht entschlüsselt werden.

Hinweise

Hinweis

Der sspi.h-Header definiert SaslInitializeSecurityContext als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Nicht unterstützt
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

Freigeben über