SspiInitializeSecurityContextAsyncW-Funktion (sspi.h)
Die SspiInitializeSecurityContextAsyncW--Funktion initiiert den clientseitigen, ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle. Die Funktion wird verwendet, um einen Sicherheitskontext zwischen der Clientanwendung und einem Remotepeer zu erstellen. SspiInitializeSecurityContextAsyncW ein Token zurück, das der Client an den Remotepeer übergeben muss, den der Peer wiederum über den SspiAcceptSecurityContextAsync Aufruf an die lokale Sicherheitsimplementierung sendet.
Anmerkung
Diese Funktion dient als asynchrones Gegenstück zur InitializeSecurityContext-Funktion.
Syntax
SECURITY_STATUS SspiInitializeSecurityContextAsyncW(
SspiAsyncContext *AsyncContext,
PCredHandle phCredential,
PCtxtHandle phContext,
PSECURITY_STRING pszTargetName,
unsigned long fContextReq,
unsigned long Reserved1,
unsigned long TargetDataRep,
PSecBufferDesc pInput,
unsigned long Reserved2,
PCtxtHandle phNewContext,
PSecBufferDesc pOutput,
unsigned long *pfContextAttr,
PTimeStamp ptsExpiry
);
Parameter
AsyncContext
Der asynchrone Aufrufkontext.
phCredential
Ein Handle für die von AcquireCredentialsHandlezurückgegebenen Anmeldeinformationen. Dieses Handle wird verwendet, um den Sicherheitskontextzu erstellen.
phContext
Ein Zeiger auf eine vorhandene CtxtHandle- Struktur.
pszTargetName
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die das Ziel des Kontexts angibt. Die Zeichenfolgeninhalte sind Sicherheitspaket spezifisch, wie in der folgenden Tabelle beschrieben. Diese Liste ist nicht vollständig. Zusätzliche System-SSPs und SSPs von Drittanbietern können einem System hinzugefügt werden.
| SSP wird verwendet | Bedeutung |
|---|---|
| Digest- | Null-beendete Zeichenfolge, die den URI der angeforderten Ressource eindeutig identifiziert. Die Zeichenfolge muss aus Zeichen bestehen, die in einem URI zulässig sind und durch den US-ASCII-Codesatz dargestellt werden können. Die Prozentcodierung kann verwendet werden, um Zeichen außerhalb des US ASCII-Codesatzes darzustellen. |
| Kerberos oder aushandeln | Dienstprinzipalname (SERVICE Principal Name, SPN) oder der Sicherheitskontext des Zielservers. |
| NTLM- | Dienstprinzipalname (SERVICE Principal Name, SPN) oder der Sicherheitskontext des Zielservers. |
| Schannel/SSL | Null-beendete Zeichenfolge, die den Zielserver eindeutig identifiziert. Schannel verwendet diesen Wert, um das Serverzertifikat zu überprüfen. Schannel verwendet diesen Wert auch, um die Sitzung im Sitzungscache zu suchen, wenn eine Verbindung wiederhergestellt wird. Die zwischengespeicherte Sitzung wird nur verwendet, wenn alle folgenden Bedingungen erfüllt sind:
|
fContextReq
Bitkennzeichnungen, die Anforderungen für den Kontext angeben.
Eine Liste der Flagwerte und deren Bedeutungen finden Sie unter InitializeSecurityContext: fContextReq.
Reserved1
Dieser Parameter ist reserviert und muss auf Null festgelegt werden.
TargetDataRep
Die Datendarstellung, z. B. byte-Sortierung, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.
pInput
Ein Zeiger auf eine SecBufferDesc--Struktur, die Zeiger auf die Puffer enthält, die als Eingabe für das Paket bereitgestellt werden.
Reserved2
Dieser Parameter ist reserviert und muss auf Null festgelegt werden.
phNewContext
Ein Zeiger auf eine CtxtHandle- Struktur.
pOutput
Ein Zeiger auf eine SecBufferDesc- Struktur, die Zeiger auf die SecBuffer-Struktur enthält, die die Ausgabedaten empfängt.
pfContextAttr
Ein Zeiger auf eine Variable, um eine Reihe von Bitkennzeichnungen zu empfangen, die die Attribute des etablierten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.
ptsExpiry
Optional. Ein Zeiger auf eine TimeStamp- Struktur, die die Ablaufzeit des Kontexts empfängt.
Rückgabewert
Gibt SEC_E_OK zurück, wenn die asynchrone Anforderung zum Einrichten eines Sicherheitskontexts für die Ausführung erfolgreich in die Warteschlange gestellt wurde, andernfalls den generierten Fehler zurück, der versucht, ihn in die Warteschlange zu stellen. Um den Status des Vorgangs abzurufen, verwenden Sie SspiGetAsyncCallStatus.
Wenn der vom Server empfangene Sicherheitskontext akzeptiert wurde, gibt SspiGetAsyncCallStatus SEC_E_OK oder einen der SSPI-Codes in der folgenden Tabelle zurück. Andernfalls kann es SEC_I_ASYNC_CALL_PENDING zurückgeben, wenn der Aufruf noch ausgeführt wird, oder einen der folgenden schwerwiegenden Fehlercodes in der zweiten Tabelle unten.
Rückgabecode |
Beschreibung |
|---|---|
|
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L |
Der Client muss CompleteAuthToken aufrufen und das Ausgabetoken an den Server übergeben. Der Client wartet dann auf ein zurückgegebenes Token und übergibt es in einem anderen Aufruf an SspiInitializeSecurityContextAsyncA. |
|
SEC_I_COMPLETE_NEEDED 0x00090313L |
Der Client muss die Erstellung der Nachricht vom Server abschließen, bevor CompleteAuthTokenaufgerufen wird. |
|
SEC_I_CONTINUE_NEEDED 0x00090312L |
Der Client muss das Ausgabetoken an den Server senden und auf ein Rückgabetoken warten. Das zurückgegebene Token wird dann in einem anderen Aufruf von SspiInitializeSecurityContextAsyncA übergeben. Das Ausgabetoken kann leer sein. |
| SEC_I_INCOMPLETE_CREDENTIALS | Verwendung mit Schannel. Der Server hat die Clientauthentifizierung angefordert, und die bereitgestellten Anmeldeinformationen enthalten entweder kein Zertifikat oder das Zertifikat wurde nicht von einer Zertifizierungsstelle ausgestellt, die vom Server als vertrauenswürdig eingestuft wurde. |
|
SEC_E_INCOMPLETE_MESSAGE 0x80090318L |
Daten für die gesamte Nachricht wurden nicht aus dem Draht gelesen. Wenn dieser Wert zurückgegeben wird, enthält der pInput-Puffer eine SecBuffer-Struktur mit einem BufferType-Element von SECBUFFER_MISSING. Das cbBuffer-Element von SecBuffer enthält einen Wert, der die Anzahl zusätzlicher Bytes angibt, die die Funktion aus dem Client lesen muss, bevor diese Funktion erfolgreich ausgeführt wird. Diese Nummer ist zwar nicht immer genau, kann aber dadurch die Leistung verbessert werden, indem mehrere Aufrufe dieser Funktion vermieden werden. |
|
SEC_E_OK 0x000000000L |
Der vom Client empfangene Sicherheitskontext wurde akzeptiert. Wenn die Funktion ein Ausgabetoken generiert hat, muss das Token an den Server gesendet werden. |
Schwerwiegende Fehlercodes
Rückgabecode |
Beschreibung |
|---|---|
|
SEC_E_INSUFFICIENT_MEMORY 0x80090300L |
Es steht nicht genügend Arbeitsspeicher zur Verfügung, um die angeforderte Aktion abzuschließen. |
|
SEC_E_INTERNAL_ERROR 0x80090304L |
Ein Fehler ist aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde. |
|
SEC_E_INVALID_HANDLE 0x80100003L |
Das an die Funktion übergebene Handle ist ungültig. |
|
SEC_E_INVALID_TOKEN 0x80090308L |
Der Fehler ist auf ein falsch formatiertes Eingabetoken zurückzuführen, z. B. ein während der Übertragung beschädigtes Token, ein Token mit falscher Größe oder ein Token, das an das falsche Sicherheitspaket übergeben wurde. Das Übergeben eines Tokens an das falsche Paket kann passieren, wenn der Client und der Server das richtige Sicherheitspaket nicht ausgehandelt haben. |
|
SEC_E_LOGON_DENIED 0x8009030CL |
Fehler bei der Anmeldung. |
|
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L |
Es konnte keine Autorität für die Authentifizierung kontaktiert werden. Der Domänenname der Authentifizierungspartei könnte falsch sein, die Domäne kann nicht erreichbar sein, oder es ist möglicherweise ein Vertrauensstellungsfehler aufgetreten. |
|
SEC_E_NO_CREDENTIALS 0x8009030EL |
Im Sicherheitspaket sind keine Anmeldeinformationen verfügbar. |
| SEC_E_TARGET_UNKNOWN | Das Ziel wurde nicht erkannt. |
|
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L |
Ein ungültiges Kontextattribute-Flag (ISC_REQ_DELEGATE oder ISC_REQ_PROMPT_FOR_CREDS) wurde im fContextReq-Parameter angegeben. |
| SEC_E_WRONG_PRINCIPAL | Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, ist nicht mit dem Prinzipal identisch, das an den pszTargetName-Parameter übergeben wurde. Dies weist auf einen Fehler bei der gegenseitigen Authentifizierung hin. |
Bemerkungen
Vollständige Hinweise finden Sie unter InitializeSecurityContext-.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 10, Version 1607 [nur Kernelmodustreiber] |
| mindestens unterstützte Server- | Windows Server 2016 [nur Kernelmodustreiber] |
| Header- | sspi.h |