AcceptSecurityContext-Funktion (NTLM)
Mit der Funktion AcceptSecurityContext (NTLM) kann die Serverkomponente einer Transportanwendung einen Sicherheitskontext zwischen dem Server und einem Remoteclient einrichten. Der Remoteclient verwendet die Funktion InitializeSecurityContext (NTLM), 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
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-Funktion (NTLM) auf, wobei entweder das flag SECPKG_CRED_INBOUND oder SECPKG_CRED_BOTH festgelegt ist, um dieses Handle abzurufen.
phContext[in, out, optional]
Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von AcceptSecurityContext (NTLM) lautet NULLdieser Zeiger . Bei nachfolgenden Aufrufen ist phContext das Handle für den teilgeformten Kontext, der im phNewContext-Parameter vom ersten Aufruf zurückgegeben wurde.
Warnung
Verwenden Sie nicht dasselbe Kontexthandle bei gleichzeitigen Aufrufen von AcceptSecurityContext (NTLM). Die API-Implementierung in den Sicherheitsdienstanbietern ist nicht threadsicher.
pInput[in, optional]
Ein Zeiger auf eine SecBufferDesc-Struktur , die von einem Clientaufruf von InitializeSecurityContext (NTLM) generiert wird und den Eingabepufferdeskriptor enthält.
Kanalbindungsinformationen können angegeben werden, indem eine SecBuffer-Struktur vom Typ SECBUFFER_CHANNEL_BINDINGS zusätzlich zu den Puffern übergeben wird, die durch den Aufruf der Funktion InitializeSecurityContext (General) generiert werden. Die Kanalbindungsinformationen für den Kanalbindungspuffer können durch Aufrufen der Funktion QueryContextAttributes (Schannel) im Schannel-Kontext abgerufen werden, den der Client für die Authentifizierung verwendet hat.
fContextReq[in]
Bitflags, die die Attribute angeben, die der Server zum Einrichten des Kontexts benötigt. Bitflags können mithilfe bitweiser OR-Vorgänge kombiniert werden. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln.
| Wert | Bedeutung |
|---|---|
| ASC_REQ_CONFIDENTIALITY | Ver- und entschlüsseln Sie Nachrichten. |
| ASC_REQ_CONNECTION | Der Sicherheitskontext behandelt keine Formatierungsmeldungen. |
| ASC_REQ_EXTENDED_ERROR | Wenn Fehler auftreten, wird die Remotepartei benachrichtigt. |
| ASC_REQ_INTEGRITY | Signieren von Nachrichten und Überprüfen von Signaturen. |
| ASC_REQ_REPLAY_DETECT | Erkennen von wiedergegebenen Paketen. |
| ASC_REQ_SEQUENCE_DETECT | Erkennen von Nachrichten, die außerhalb der Reihenfolge empfangen werden. |
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 .
TargetDataRep[in]
Die Datendarstellung, z. B. bytereihenfolge, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.
phNewContext[in, out, optional]
Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von AcceptSecurityContext (NTLM) empfängt dieser Zeiger das neue Kontexthandle. Bei nachfolgenden Aufrufen kann phNewContext mit dem im parameter phContext angegebenen Handle identisch sein.
phNewContext sollte niemals sein NULL.
pOutput[in, out, optional]
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 (NTLM) 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.
pfContextAttr[out]
Ein Zeiger auf eine Variable, die eine Reihe von Bitflags empfängt, 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.
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 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 sein NULL .
Rückgabewert
Diese Funktion gibt einen der folgenden Werte zurück.
| Rückgabecode/-wert | Beschreibung |
|---|---|
| Fehler bei der Funktion. Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen. |
| Fehler bei der Funktion. Es ist ein Fehler aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde. |
| Fehler bei der Funktion. Das an die Funktion übergebene Handle ist ungültig. |
| Fehler bei der Funktion. Das an die Funktion übergebene Token ist ungültig. |
| Fehler bei der Anmeldung. |
| 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:
|
| Die Funktion wurde erfolgreich ausgeführt. Der [*Sicherheitskontext*](.. Vom Client empfangene /secgloss/s-gly.md) wurde akzeptiert. Wenn von der Funktion ein Ausgabetoken generiert wurde, muss es an den Clientprozess gesendet werden. |
| 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 [AcceptSecurityContext (NTLM)](acceptsecuritycontext--ntlm.md) auf. |
| 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. |
| 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 (NTLM)](acceptsecuritycontext--ntlm.md) übergeben werden. |
Bemerkungen
Die Funktion AcceptSecurityContext (NTLM) ist das Server-Pendant zur Funktion InitializeSecurityContext (NTLM).
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 in der Lage sein müssen, eine vertrauliche oder integritätsgeprüfte Sitzung zu verwenden, und er kann Clients ablehnen, die diese Anforderung nicht erfüllen können. Alternativ kann ein Server nichts erfordern, und alles, was der Client bereitstellen kann oder benötigt, wird im pfContextAttr-Parameter zurückgegeben.
Für ein Paket, das die Authentifizierung mit mehreren Beinen unterstützt, z. B. die gegenseitige Authentifizierung, lautet die Aufrufsequenz wie folgt:
- Der Client überträgt ein Token an den Server.
- Der Server ruft AcceptSecurityContext (NTLM) zum ersten Mal auf, wodurch ein Antworttoken generiert wird, das dann an den Client gesendet wird.
- Der Client empfängt das Token und übergibt es an InitializeSecurityContext (NTLM). Wenn InitializeSecurityContext (NTLM) SEC_E_OK zurückgibt, wurde die gegenseitige Authentifizierung abgeschlossen, und eine sichere Sitzung kann beginnen. Wenn InitializeSecurityContext (NTLM) einen Fehlercode zurückgibt, endet die Aushandlung der gegenseitigen Authentifizierung. Andernfalls wird das von InitializeSecurityContext (NTLM) zurückgegebene Sicherheitstoken an den Client gesendet, und die Schritte 2 und 3 werden wiederholt.
- Verwenden Sie den wert phContext nicht in gleichzeitigen Aufrufen von AcceptSecurityContext (NTLM). Die Implementierung in den Sicherheitsanbietern ist nicht threadsicher.
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, aber nur bei der endgültigen erfolgreichen Rückgabe, wenn Sie die Flags im Zusammenhang mit Sicherheitsaspekten des Kontexts untersuchen. Zwischenzeitliche Rückgaben können z. B. das flag ISC_RET_ALLOCATED_MEMORY 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 herunterfahren. Wenn der Sicherheitskontext nicht eingerichtet werden kann, muss der Server den teilweise erstellten Kontext durch Aufrufen der DeleteSecurityContext-Funktion freigeben. 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 XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Header | Sspi.h (einschließlich Security.h) |
| Bibliothek | Secur32.lib |
| DLL | Secur32.dll |