AcceptSecurityContext-Funktion (Schannel)

Mit der AcceptSecurityContext-Funktion (Schannel) kann die Serverkomponente einer Transportanwendung einen Sicherheitskontext zwischen dem Server und einem Remoteclient einrichten. Der Remoteclient verwendet die InitializeSecurityContext -Funktion (Schannel), um den Prozess zum Einrichten eines Sicherheitskontextszu starten. Der Server kann mindestens ein Antworttoken vom Remoteclient anfordern, um die Einrichtung des Sicherheitskontextsabzuschließen.

Syntax

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

Parameter

phCredential [ in, optional]

Ein Handle für die Anmeldeinformationen des Servers. Der Server ruft die AcquireCredentialsHandle (Schannel)-Funktion auf, wobei entweder das SECPKG _ CRED _ INBOUND- oder SECPKG _ CRED _ BOTH-Flag festgelegt ist, um dieses Handle abzurufen.

phContext [ in, out, optional]

Ein Zeiger auf eine CTXTHandle-Struktur. Beim ersten Aufruf von AcceptSecurityContext (Schannel) ist dieser Zeiger NULL. Bei nachfolgenden Aufrufen ist phContext das Handle für den teilweise gebildeten Kontext, der im phNewContext-Parameter durch den ersten Aufruf zurückgegeben wurde.

pInput [ in, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur, die durch einen Clientaufruf von InitializeSecurityContext (Schannel) generiert wird, der den Eingabepufferdeskriptor enthält.

Bei Verwendung des SCHANNEL-Sicherheitssupportanbieters (Security Support Provider, SSP) muss der erste Puffer vom Typ SECBUFFER TOKEN sein _ und das vom Client empfangene Sicherheitstoken enthalten. Der zweite Puffer sollte vom Typ SECBUFFER _ EMPTY sein.

fContextReq [ In]

Bitflags, die die Attribute angeben, die der Server zum Einrichten des Kontexts benötigt. Bitflags können mit bitweisen OR-Vorgängen kombiniert werden. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handelt.

Wert Bedeutung
ASC _ REQ _ ALLOCATE _ MEMORY
Digest und Schannel ordnen Ausgabepuffer für Sie zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, können Sie sie freigeben, indem Sie die FreeContextBuffer-Funktion aufrufen.
ASC _ REQ _ CONFIDENTIALITY
Verschlüsseln und Entschlüsseln von Nachrichten.
Der Digest-SSP unterstützt dieses Flag nur für SASL.
ASC _ REQ _ CONNECTION
Der Sicherheitskontext verarbeitet keine Formatierungsmeldungen.
ASC _ REQ _ EXTENDED _ ERROR
Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ASC _ REQ _ MUTUAL _ AUTH
Der Client muss ein Zertifikat bereitstellen, das für die Clientauthentifizierung verwendet werden soll.
ASC _ REQ _ REPLAY _ DETECT
Erkennen wiedergegebener Pakete.
ASC _ REQ _ SEQUENCE _ DETECT
Erkennen von Nachrichten, die außerhalb der Sequenz empfangen wurden.
ASC _ REQ _ STREAM
Unterstützung einer streamorientierten Verbindung.
Dieses Flag wird nur von Schannel unterstützt.

Mögliche Attributflags und ihre Bedeutungen finden Sie unter Kontextanforderungen. Flags, die für diesen Parameter verwendet werden, haben das Präfix ASC _ REQ, z. B. ASC _ REQ _ DELEGATE.

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

TargetDataRep [ In]

Dieser Parameter wird nicht mit Schannel verwendet. Geben Sie 0 (null) für diesen Parameter an.

phNewContext [ in, out, optional]

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

pOutput [ in, out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur, die den Ausgabepufferdeskriptor enthält. Dieser Puffer wird zur Eingabe in zusätzliche Aufrufe von InitializeSecurityContext (Schannel)an den Client 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. Darüber hinaus muss der Aufrufer einen Puffer vom Typ SECBUFFER _ ALERT übergeben. Wenn bei der Ausgabe eine Warnung generiert wird, enthält dieser Puffer Informationen zu dieser Warnung, und die Funktion schlägt fehl.

pfContextAttr [ out]

Ein Zeiger auf eine Variable, die einen Satz von Bitflags empfängt, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Flags, die für diesen Parameter verwendet werden, haben das Präfix ASC _ RET, z. B. ASC _ RET _ DELEGATE.

Suchen Sie erst nach sicherheitsrelevanten Attributen, wenn der letzte Funktionsaufruf erfolgreich zurückgegeben wurde. Attributflags, die sich nicht auf die Sicherheit beziehen, wie z. B. das _ ASC RET _ ALLOCATED _ MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.

ptsTimeStamp [ out, optional]

Ein Zeiger auf eine TimeStamp-Struktur, die die Ablaufzeit des Kontexts empfängt. Es wird empfohlen, dass das Sicherheitspaket diesen Wert immer in ortslokaler Zeit zurückgibt.

Dies ist bei Verwendung des Schannel-SSP optional. Wenn die Remotepartei ein Zertifikat bereitgestellt hat, das für die Authentifizierung verwendet werden soll, erhält dieser Parameter die Ablaufzeit für dieses Zertifikat. Wenn kein Zertifikat angegeben wurde, wird ein maximaler Zeitwert zurückgegeben.

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/-wertBeschreibung
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 (Schannel)](acceptsecuritycontext--schannel.md) erneut aufrufen.
Wenn dieser Wert zurückgegeben wird, enthält der pInput-Puffer eine [SecBuffer](/windows/win32/api/sspi/ns-sspi-secbuffer)-Struktur mit einem BufferType-Member von SECBUFFER_MISSING. Der cbBuffer-Member von SecBuffer enthält einen Wert, der die Anzahl zusätzlicher Bytes angibt, die die Funktion vom Client lesen muss, bevor diese Funktion erfolgreich ausgeführt wird. Obwohl diese Zahl nicht immer genau ist, kann die Verwendung von ihr zur Leistung beitragen, indem mehrere Aufrufe dieser Funktion vermieden werden.
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. Fehler, 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. Für die Authentifizierung konnte keine Autorität kontaktiert werden. Dies kann auf die folgenden Bedingungen zurückzuführen sein:
  • Der Domänenname der authentifizierenden Seite ist falsch.
  • Die Domäne ist nicht verfügbar.
  • Fehler bei der Vertrauensstellung.
SEC_E_NO_CREDENTIALS
0x8009030EL
Fehler bei der Funktion. Das im phCredential-Parameter angegebene Handle für Anmeldeinformationen ist ungültig. Dieser Wert kann bei Verwendung des Digest- oder Schannel-SSP zurückgegeben werden.
SEC_E_OK
0x00000000L
Die Funktion wurde erfolgreich ausgeführt. Der vom Client empfangene [*Sicherheitskontext*](../secgloss/s-gly.md) wurde akzeptiert. Wenn ein Ausgabetoken von der Funktion generiert wurde, muss es an den Clientprozess gesendet werden.
SEC_E_UNSUPPORTED_FUNCTION
0x80090302L
Fehler bei der Funktion. Im fContextReq-Parameter wurde ein ungültiges Kontextattributflag (ASC_REQ_DELEGATE oder ASC_REQ_PROMPT_FOR_CREDS) angegeben.
SEC_E_APPLICATION_PROTOCOL_MISMATCH
0x80090367L
Zwischen dem Client und dem Server ist kein allgemeines Anwendungsprotokoll vorhanden.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L
Die Funktion wurde erfolgreich ausgeführt. Der Server muss [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) aufrufen und das Ausgabetoken an den Client übergeben. Der Server wartet dann auf ein Rückgabetoken vom Client und ruft dann erneut [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) auf.
SEC_I_COMPLETE_NEEDED
0x00090313L
Die Funktion wurde erfolgreich ausgeführt. Der Server muss die Erstellung der Nachricht vom Client abschließen und dann die Funktion[CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) aufrufen.
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 (Schannel)](acceptsecuritycontext--schannel.md) übergeben werden.
STATUS_LOGON_FAILURE
0xC000006DL
Fehler bei der Funktion. Die Funktion [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) wurde aufgerufen, nachdem der angegebene Kontext eingerichtet wurde. Dieser Wert kann bei Verwendung des Digest-SSP zurückgegeben werden.

Hinweise

Die AcceptSecurityContext (Schannel)-Funktion ist die Serverentsprechung zur InitializeSecurityContext (Schannel)-Funktion.

Wenn der Server eine Anforderung von einem Client empfängt, verwendet der Server den fContextReq-Parameter, um anzugeben, was für die Sitzung erforderlich ist. Auf diese Weise kann ein Server angeben, dass Clients eine vertrauliche oder integritätsüberprüfungsbasierte Sitzung verwenden müssen, und Clients ablehnen können, die diese Anforderung nicht erfüllen können. Alternativ kann ein Server nichts erfordern, und das, was der Client bereitstellen kann oder erfordert, wird im pfContextAttr-Parameter zurückgegeben.

Für ein Paket, das die mehrstufige Authentifizierung unterstützt, z. B. gegenseitige Authentifizierung, sieht die aufrufende Sequenz wie folgt aus:

  1. Der Client überträgt ein Token an den Server.
  2. Der Server ruft AcceptSecurityContext (Schannel) zum ersten Mal auf, wodurch ein Antworttoken generiert wird, das dann an den Client gesendet wird.
  3. Der Client empfängt das Token und übergibt es an InitializeSecurityContext (Schannel). Wenn InitializeSecurityContext (Schannel) SEC E OK zurückgibt, wurde die _ gegenseitige _ Authentifizierung abgeschlossen, und eine sichere Sitzung kann beginnen. Wenn InitializeSecurityContext (Schannel) einen Fehlercode zurückgibt, wird die gegenseitige Authentifizierungsaushandlung beendet. Andernfalls wird das von InitializeSecurityContext (Schannel) zurückgegebene Sicherheitstoken an den Client gesendet, und die Schritte 2 und 3 werden wiederholt.

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

Hinweis

Der pfContextAttr-Parameter ist bei jeder erfolgreichen Rückgabe gültig, jedoch nur bei der endgültigen erfolgreichen Rückgabe, wenn Sie die Flags in Bezug auf Sicherheitsaspekte des Kontexts untersuchen. Zwischenrücksetzungen 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 z. B. Vertraulichkeit (Verschlüsselung) angefordert wurde, aber nicht eingerichtet werden konnte, können einige Anwendungen die Verbindung sofort beenden. Wenn der Sicherheitskontext nicht eingerichtet werden kann, muss der Server den teilweise erstellten Kontext freigeben, indem er die DeleteSecurityContext-Funktion aufruft. Informationen dazu, wann die DeleteSecurityContext-Funktion aufgerufen werden soll, 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 ImpersonateSecurityContext-Funktion verwenden, um die Identität des Benutzers zu annehmen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
[Windows 8.1 Nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows Server 2012 Nur [ R2-Desktop-Apps]
Header
Sspi.h (include Security.h)
Bibliothek
Secur32.lib
DLL
Secur32.dll

Weitere Informationen

SSPI-Funktionen

DeleteSecurityContext

InitializeSecurityContext (Schannel)