AcceptSecurityContext-Funktion (sspi.h)

Artikel
08/26/2023

Mit der Funktion AcceptSecurityContext (CredSSP) kann die Serverkomponente einer Transportanwendung einen Sicherheitskontext zwischen dem Server und einem Remoteclient einrichten. Der Remoteclient ruft die CredSSP-Funktion (InitializeSecurityContext) auf, um den Prozess zum Einrichten eines Sicherheitskontexts zu starten. Der Server kann ein oder mehrere Antworttoken vom Remoteclient anfordern, um die Einrichtung des Sicherheitskontexts abzuschließen.

Syntax

KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
  [in, optional]      PCredHandle    phCredential,
  [in, optional]      PCtxtHandle    phContext,
  [in, optional]      PSecBufferDesc pInput,
  [in]                unsigned long  fContextReq,
  [in]                unsigned long  TargetDataRep,
  [in, out, optional] PCtxtHandle    phNewContext,
  [in, out, optional] PSecBufferDesc pOutput,
  [out]               unsigned long  *pfContextAttr,
  [out, optional]     PTimeStamp     ptsExpiry
);

Parameter

[in, optional] phCredential

Ein Handle für die Serveranmeldeinformationen. Um dieses Handle abzurufen, ruft der Server die AcquireCredentialsHandle-Funktion (CredSSP) auf, wobei entweder das flag SECPKG_CRED_INBOUND oder SECPKG_CRED_BOTH festgelegt ist.

[in, optional] phContext

Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von AcceptSecurityContext (CredSSP) ist dieser Zeiger NULL. Bei nachfolgenden Aufrufen gibt phContext den teilgeformten Kontext an, der im phNewContext-Parameter vom ersten Aufruf zurückgegeben wird.

[in, optional] pInput

Ein Zeiger auf eine SecBufferDesc-Struktur , die von einem Clientaufruf von InitializeSecurityContext (CredSSP) generiert wird. Die -Struktur enthält den Eingabepufferdeskriptor.

Der erste Puffer muss vom Typ SECBUFFER_TOKEN sein und das vom Client empfangene Sicherheitstoken enthalten. Der zweite Puffer sollte vom Typ SECBUFFER_EMPTY sein.

[in] fContextReq

-Bitflags, die die Attribute angeben, die vom Server zum Einrichten des Kontexts erforderlich sind. Bitflags können mithilfe bitweiser OR-Vorgänge kombiniert werden. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
ASC_REQ_ALLOCATE_MEMORY	Der Credential Security Support Provider (CredSSP) ordnet Ausgabepuffer zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die Funktion FreeContextBuffer aufrufen.
ASC_REQ_CONNECTION	Der Sicherheitskontext behandelt keine Formatierungsmeldungen.
ASC_REQ_DELEGATE	Der Server darf die Identität des Clients annehmen. Ignorieren Sie dieses Flag für die eingeschränkte Delegierung.
ASC_REQ_EXTENDED_ERROR	Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ASC_REQ_REPLAY_DETECT	Erkennen von wiedergegebenen Paketen.
ASC_REQ_SEQUENCE_DETECT	Erkennen von Nachrichten, die außerhalb der Reihenfolge empfangen werden.
ASC_REQ_STREAM	Unterstützung einer streamorientierten Verbindung.

Informationen zu möglichen Attributflags und deren Bedeutung finden Sie unter Kontextanforderungen. Für diesen Parameter verwendete Flags wird ASC_REQ vorangestellt, z. B. ASC_REQ_DELEGATE.

Die angeforderten Attribute werden vom Client möglicherweise nicht unterstützt. Weitere Informationen finden Sie im PfContextAttr-Parameter .

[in] TargetDataRep

Die Datendarstellung, z. B. bytereihenfolge, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.

[in, out, optional] phNewContext

Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von AcceptSecurityContext (CredSSP) empfängt dieser Zeiger das neue Kontexthandle. Bei nachfolgenden Aufrufen kann phNewContext mit dem im parameter phContext angegebenen Handle identisch sein.

[in, out, optional] pOutput

Ein Zeiger auf eine SecBufferDesc-Struktur , die den Ausgabepufferdeskriptor enthält. Dieser Puffer wird an den Client zur Eingabe in zusätzliche Aufrufe von InitializeSecurityContext (CredSSP) gesendet. Ein Ausgabepuffer kann auch dann generiert werden, wenn die Funktion SEC_E_OK zurückgibt. Alle generierten Puffer müssen an die Clientanwendung zurückgesendet werden.

Bei der Ausgabe empfängt dieser Puffer ein Token für den Sicherheitskontext. Das Token muss an den Client gesendet werden. Die Funktion kann auch einen Puffer vom Typ SECBUFFER_EXTRA zurückgeben.

[out] pfContextAttr

Ein Zeiger auf eine Reihe von Bitflags, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Für diesen Parameter verwendete Flags wird ASC_RET vorangestellt, z. B. ASC_RET_DELEGATE.

Ü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.

[out, optional] ptsExpiry

Ein 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.

Hinweis Bis zum letzten Aufruf des Authentifizierungsprozesses kann die Ablaufzeit für den Kontext falsch sein, da in späteren Phasen der Aushandlung weitere Informationen bereitgestellt werden. Daher muss ptsTimeStamp bis zum letzten Aufruf der Funktion NULL sein.

Rückgabewert

Diese Funktion gibt einen der folgenden Werte zurück.

Rückgabecode/-wert	BESCHREIBUNG
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Die Funktion wurde erfolgreich ausgeführt. Die Daten im Eingabepuffer sind unvollständig. Die Anwendung muss zusätzliche Daten vom Client lesen und AcceptSecurityContext (CredSSP) erneut aufrufen.
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	Fehler bei der Funktion. Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen.
SEC_E_INTERNAL_ERROR 0x80090304L	Fehler bei der Funktion. Es ist ein Fehler aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde.
SEC_E_INVALID_HANDLE 0x80100003L	Fehler bei der Funktion. Das an die Funktion übergebene Handle ist ungültig.
SEC_E_INVALID_TOKEN 0x80090308L	Fehler bei der Funktion. Das an die Funktion übergebene Token ist ungültig.
SEC_E_LOGON_DENIED 0x8009030CL	Fehler bei der Anmeldung.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	Fehler bei der Funktion. Es konnte keine Autorität für die Authentifizierung kontaktiert werden. Dies kann auf die folgenden Bedingungen zurückzuführen sein: Der Domänenname der Authentifizierungspartei ist falsch. Die Domäne ist nicht verfügbar. Die Vertrauensstellung ist fehlgeschlagen.
SEC_E_NO_CREDENTIALS 0x8009030EL	Fehler bei der Funktion. Das im parameter phCredential angegebene Anmeldeinformationshandle ist ungültig.
SEC_E_OK 0x00000000L	Die Funktion wurde erfolgreich ausgeführt. Der vom Client empfangene Sicherheitskontext wurde akzeptiert. Wenn die Funktion ein Ausgabetoken generiert hat, muss das Token an den Clientprozess gesendet werden.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Fehler bei der Funktion. Der fContextReq-Parameter hat ein ungültiges Kontextattributeflag (ASC_REQ_DELEGATE oder ASC_REQ_PROMPT_FOR_CREDS) angegeben.
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	Die Funktion wurde erfolgreich ausgeführt. Der Server muss CompleteAuthToken aufrufen und das Ausgabetoken an den Client übergeben. Der Server muss dann auf ein Rückgabetoken vom Client warten, bevor er einen weiteren Aufruf von AcceptSecurityContext (CredSSP) ausgibt.
SEC_I_COMPLETE_NEEDED 0x00090313L	Die Funktion wurde erfolgreich ausgeführt. Der Server muss die Erstellung der Nachricht vom Client abschließen, bevor CompleteAuthToken aufgerufen wird.
SEC_I_CONTINUE_NEEDED 0x00090312L	Die Funktion wurde erfolgreich ausgeführt. Der Server muss das Ausgabetoken an den Client senden und auf ein zurückgegebenes Token warten. Das zurückgegebene Token sollte in pInput für einen weiteren Aufruf von AcceptSecurityContext (CredSSP) übergeben werden.

Hinweise

Die AcceptSecurityContext-Funktion (CredSSP) ist das Server-Pendant zur Funktion InitializeSecurityContext (CredSSP).

Wenn der Server eine Anforderung von einem Client empfängt, verwendet er den fContextReq-Parameter , um anzugeben, was er für die Sitzung benötigt. Auf diese Weise kann ein Server verlangen, dass Clients in der Lage sind, eine vertrauliche oder integritätsgeprüfte Sitzung zu verwenden. Es kann Clients ablehnen, die diese Anforderung nicht erfüllen können. Alternativ kann ein Server nichts erfordern. Was der Client benötigt oder bereitstellen kann, wird im pfContextAttr-Parameter zurückgegeben.

Die Parameter fContextReq und pfContextAttr sind Bitmasken, die verschiedene Kontextattribute darstellen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Hinweis Obwohl der pfContextAttr-Parameter bei jeder erfolgreichen Rückgabe gültig ist, sollten Sie die Flags für Sicherheitsaspekte des Kontexts nur bei der endgültigen erfolgreichen Rückgabe untersuchen. Zwischenrücken können z. B. das ISC_RET_ALLOCATED_MEMORY-Flag festlegen.

Der Aufrufer ist dafür verantwortlich, zu bestimmen, ob die endgültigen Kontextattribute ausreichend sind. Wenn beispielsweise Vertraulichkeit (Verschlüsselung) angefordert wurde, aber nicht eingerichtet werden konnte, können einige Anwendungen die Verbindung sofort herunterfahren. Wenn der Sicherheitskontext nicht eingerichtet werden kann, muss der Server den teilweise erstellten Kontext durch Aufrufen der DeleteSecurityContext-Funktion freigeben. Informationen zum Aufrufen der DeleteSecurityContext-Funktion finden Sie unter DeleteSecurityContext.\

Nachdem der Sicherheitskontext eingerichtet wurde, kann die Serveranwendung die QuerySecurityContextToken-Funktion verwenden, um ein Handle für das Benutzerkonto abzurufen, dem das Clientzertifikat zugeordnet wurde. Außerdem kann der Server die Funktion ImpersonateSecurityContext verwenden, um die Identität des Benutzers zu imitieren.

Anforderungen


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

Weitere Informationen

DeleteSecurityContext

InitializeSecurityContext (CredSSP)

SSPI-Funktionen

Freigeben über