AcceptSecurityContext (CredSSP)-Funktion
Mit der AcceptSecurityContext (CredSSP)-Funktion kann die Serverkomponente einer Transportanwendung einen Sicherheitskontext zwischen dem Server und einem Remoteclient herstellen. Der Remoteclient ruft die Funktion InitializeSecurityContext (CredSSP) auf, um den Prozess der Herstellung eines Sicherheitskontexts zu starten. Der Server kann ein oder mehrere Antworttoken vom Remoteclient benötigen, um den Sicherheitskontext abzuschließen.
Syntax
SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
_In_opt_ PCredHandle phCredential,
_In_opt_ PCtxtHandle phContext,
_In_opt_ PSecBufferDesc pInput,
_In_ unsigned long fContextReq,
_In_ unsigned long TargetDataRep,
_Inout_opt_ PCtxtHandle phNewContext,
_Inout_opt_ PSecBufferDesc pOutput,
_Out_ unsigned long *pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
);
Parameter
phCredential [in, optional]
Ein Handle für die Serveranmeldeinformationen. Zum Abrufen dieses Handles furt der Server die AcquireCredentialsHandle (CredSSP)-Funktion auf, wobei entweder die SECPKG_CRED_INBOUND- oder SECPKG_CRED_BOTH-Flag festgelegt ist.
phContext [in, optional]
Ein Zeiger auf eine CtxtHandle-Struktur. Beim ersten Aufruf von AcceptSecurityContext (CredSSP) ist dieser Zeiger NULL. Bei nachfolgenden Aufrufen gibt phContext den teilweise gebildeten Kontext an, der im phNewContext-Parameter des ersten Aufrufs zurückgegeben wird.
Warnung
Verwenden Sie nicht dasselbe Kontexthandle in gleichzeitigen Aufrufen von AcceptSecurityContext (CredSSP). Die API-Implementierung in den Sicherheitsdienstanbietern ist nicht threadsicher.
pInput [in, optional]
Ein Zeiger auf eine SecBufferDesc-Struktur, die von einem Clientaufruf an 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.
fContextReq [in]
- Bitflags, die die vom Server zum Einrichten des Kontexts erforderlichen Attribute angeben. Bitflags können mithilfe von bitwise-OR-Vorgängen kombiniert werden. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
| ASC_REQ_ALLOCATE_MEMORY | Der Credential Security Support Provider (CredSSP) weist Ausgabepuffer zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die FreeContextBuffer-Funktion aufrufen. |
| ASC_REQ_CONNECTION | Der Sicherheitskontext behandelt keine Formatierungsmeldungen. |
| ASC_REQ_DELEGATE | Der Server darf sich als Client ausgeben. Ignorieren Sie dieses Kennzeichen für die eingeschränkte Delegierung. |
| ASC_REQ_EXTENDED_ERROR | Wenn Fehler auftreten, wird die Remotepartei benachrichtigt. |
| 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ützen einer streamorientierten Verbindung. |
Mögliche Attributflags und deren Bedeutungen finden Sie unter Kontextanforderungen. Kennzeichen, die für diesen Parameter verwendet werden, wird ASC_REQ vorangestellt, z. B. ASC_REQ_DELEGATE.
Die angeforderten Attribute werden möglicherweise vom Client nicht unterstützt. Weitere Informationen finden Sie im Parameter pfContextAttr .
TargetDataRep [in]
Die Datendarstellung, z. B. Byte-Sortierung, 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 (CredSSP) 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 an den Client gesendet, um zusätzliche Aufrufe an InitializeSecurityContext (CredSSP) einzugeben. Ein Ausgabepuffer kann auch dann generiert werden, wenn die Funktion SEC_E_OK zurückgibt. Jeder generierte Puffer muss 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.
pfContextAttr [out]
Ein Zeiger auf eine Reihe von Bitflags, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Kennzeichen, die für diesen Parameter verwendet werden, wird ASC_RET vorangestellt, z. B. ASC_RET_DELEGATE.
Überprüfen Sie erst auf sicherheitsbezogene Attribute, wenn der endgültige Funktionsaufruf erfolgreich zurückgegeben wurde. Attributflags, die nichts mit der Sicherheit zu tun haben, wie z. B. das ASC_RET_ALLOCATED_MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.
ptsExpiry [out, optional]
Ein Zeiger auf eine TimeStamp-Struktur, welche 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 Verhandlung 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 steht nicht genügend Arbeitsspeicher zur Verfügung, um die angeforderte Aktion abzuschließen. |
| SEC_E_INTERNAL_ERROR 0x80090304L |
Fehler bei der Funktion. Ein Fehler ist aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde. |
| SEC_E_INVALID_HANDLE 0x80100003L |
Fehler bei der Funktion. Die dieser Funktion übergebene URL 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 könnte auf folgende Bedingungen zurückzuführen sein:
|
| SEC_E_NO_CREDENTIALS 0x8009030EL |
Fehler bei der Funktion. Das im phCredential-Parameter angegebene Anmeldeinformationshandle ist ungültig. |
| SEC_E_OK 0x00000000L |
Die Funktion wurde erfolgreich ausgeführt. Der vom Client empfangene Sicherheitskontext 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. Der Parameter fContextReq gab ein Kontextattributflag (ASC_REQ_DELEGATE oder ASC_REQ_PROMPT_FOR_CREDS) an, das ungültig war. |
| 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 ein weiterer Aufruf an AcceptSecurityContext (CredSSP) vorgenommen wird. |
| SEC_I_COMPLETE_NEEDED 0x00090313L |
Die Funktion wurde erfolgreich ausgeführt. Der Server muss die Erstellung der Nachricht vom Client abschließen, bevor er CompleteAuthToken aufruft |
| 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 anderen Aufruf von AcceptSecurityContext (CredSSP) übergeben werden. |
Hinweise
Die AcceptSecurityContext (CredSSP)-Funktion ist das Server-Gegenstück 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 erfordern, dass Clients in der Lage sind, 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 was der Client bereitstellen kann oder erfordert, wird im Parameter pfContextAttr zurückgegeben.
Bei den Parametern fContextReq und pfContextAttr handelt es sich um Bitmasken, die verschiedene Kontextattribute darstellen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.
Hinweis
Während der pfContextAttr-Parameter ist bei jeder erfolgreichen Rückgabe gültig ist, sollten Sie die Flags in Bezug auf die Sicherheitsaspekte des Kontexts aber nur bei der letzten erfolgreichen Rückgabe überprüfen. Zwischenrückzeichen können z. B. die ISC_RET_ALLOCATED_MEMORY-Kennzeichnung festlegen.
Der Aufrufer ist dafür verantwortlich, zu bestimmen, ob die endgültigen Kontextattribute ausreichen. Wenn z. B. Vertraulichkeit (Verschlüsselung) angefordert wurde, aber nicht hergestellt 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 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 ImpersonateSecurityContext-Funktion verwenden, um die Identität des Benutzers zu imitieren.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows�Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server�2008 [nur Desktop-Apps] |
| Header | Sspi.h (einschließlich Security.h) |
| Bibliothek | Secur32.lib |
| DLL | Secur32.dll |