SaslInitializeSecurityContextA-Funktion (sspi.h)

Artikel
07/16/2024

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

Syntax

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextA(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPSTR          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 zu den Anmeldeinformationen von der
AcquireCredentialsHandle--Funktion, die zum Erstellen des Sicherheitskontextsverwendet wird. Die Verwendung der SaslInitializeSecurityContext Funktion erfordert mindestens AUSGEHENDe Anmeldeinformationen.

[in] phContext

Zeiger auf eine CtxtHandle- Struktur. Beim ersten Aufruf der funktion SaslInitializeSecurityContext ist dieser Zeiger NULL. Bei dem zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilweise gebildeten Kontext, der im phNewContext Parameter durch den ersten Aufruf zurückgegeben wird.

[in] pszTargetName

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

[in] fContextReq

Bitkennzeichnungen, die die Anforderungen des Kontexts angeben. Für diesen Parameter verwendete Flags werden ISC_REQ_ vorangestellt; Beispiel: ISC_REQ_DELEGATE. Geben Sie Kombinationen der folgenden Attributkennzeichnungen an.

Wert	Bedeutung
ISC_REQ_REPLAY_DETECT	Erkennen sie wiedergegebene Pakete.
ISC_REQ_SEQUENCE_DETECT	Erkennen von Nachrichten, die außerhalb der Sequenz empfangen wurden.
ISC_REQ_CONFIDENTIALITY	Nachrichten verschlüsseln.
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 sie Nachrichten, und überprüfen Sie 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 Byte-Sortierung, 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 NULL- für den ersten Aufruf der Funktion sein. Bei nachfolgenden Aufrufen der Funktion handelt es sich um einen Zeiger auf einen Puffer, der genügend Arbeitsspeicher zugeordnet ist, um das vom Remote-Peer zurückgegebene Token zu speichern.

SASL erfordert einen einzelnen Puffer vom Typ SECBUFFER_TOKEN, der die vom Server empfangene Abfrage 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. Im zweiten Aufruf kann phNewContext- mit dem im phContext Parameter 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 die Eingabe eingegeben wurde, wird er in der Ausgabe angezeigt. Das System weist einen Puffer für das Sicherheitstoken zu, falls angefordert (über ISC_REQ_ALLOCATE_MEMORY) und füllt die Adresse im Pufferdeskriptor für das Sicherheitstoken aus.

[out] pfContextAttr

Zeigen Sie auf eine Variable, um eine Reihe von Bitkennzeichnungen zu empfangen, die die Attribute des etablierten Kontext-angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Für diesen Parameter verwendete Flags werden 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. Attributkennzeichnungen, 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 während einer Aushandlung mit einem Remote-Peer geändert werden.

[out, optional] ptsExpiry

Zeigen Sie auf eine TimeStamp- Struktur, die die Ablaufzeit des Kontexts empfängt. Es wird empfohlen, dass das Sicherheitspaket diesen Wert immer in der lokalen Zeit zurückgeben. Dieser Parameter ist optional, und NULL- für kurzlebige Clients übergeben werden sollen.

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	Die Authz-Verarbeitung ist nicht zulässig.
SEC_E_INSUFFICIENT_MEMORY	Nicht genügend Arbeitsspeicher ist verfügbar, um die Anforderung abzuschließen.
SEC_E_INVALID_TOKEN	Kein Tokenpuffer befindet sich im pOutput Parameter, oder die Nachricht konnte nicht entschlüsselt werden.

Bemerkungen

Anmerkung

Der Header "sspi.h" 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
mindestens unterstützte Client-	Keine unterstützt
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	sspi.h (include Security.h)
Library	Secur32.lib
DLL-	Secur32.dll

Freigeben über