SaslInitializeSecurityContextA-Funktion (sspi.h)

Artikel
08/26/2023

Die SaslInitializeSecurityContext-Funktion umschließt einen Standardaufruf der Funktion "Security Support Provider Interface InitializeSecurityContext (General)" 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 für die von der zurückgegebenen Anmeldeinformationen
AcquireCredentialsHandle-Funktion , die zum Erstellen des Sicherheitskontexts verwendet wird. Die Verwendung der SaslInitializeSecurityContext-Funktion erfordert mindestens AUSGEHENDe 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 teilweise gebildeten Kontext, der vom ersten Aufruf im parameter phNewContext 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. Flags, die für diesen Parameter verwendet werden, haben das Präfix ISC_REQ_; 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 Sie Nachrichten, die außerhalb der Sequenz empfangen werden.
ISC_REQ_CONFIDENTIALITY	Verschlüsseln sie 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 verarbeitet keine Formatierungsnachrichten.
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. 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 Challenge 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 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 der Eingabe eingegeben wurde, ist er bei der Ausgabe vorhanden. Das System weist bei Anforderung (über ISC_REQ_ALLOCATE_MEMORY) einen Puffer für das Sicherheitstoken zu und gibt 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 .

Suchen Sie erst nach sicherheitsbezogenen Attributen, bis der endgültige Funktionsaufruf erfolgreich zurückgegeben wird. Attributflags, die nicht mit der Sicherheit zusammenhängen, 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 zur 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	Für die Anforderung steht nicht genügend Arbeitsspeicher zur Verfügung.
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 automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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