SspiAcquireCredentialsHandleAsyncW-Funktion (sspi.h)
Die SspiAcquireCredentialsHandleAsyncW-Funktion ruft asynchron ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab.
Dieses Handle ist für die Funktionen SspiInitializeSecurityContextAsync und SspiAcceptSecurityContextAsync erforderlich. Dies kann entweder bereits vorhandene Anmeldeinformationen sein, die über eine Systemanmeldung eingerichtet werden, die hier nicht beschrieben wird, oder der Aufrufer kann alternative Anmeldeinformationen bereitstellen.
Hinweis
Diese Funktion dient als asynchrones Pendant zu AcquireCredentialsHandle.
Syntax
SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
SspiAsyncContext *AsyncContext,
PSECURITY_STRING pszPrincipal,
PSECURITY_STRING pszPackage,
unsigned long fCredentialUse,
void *pvLogonId,
void *pAuthData,
SEC_GET_KEY_FN pGetKeyFn,
void *pvGetKeyArgument,
PCredHandle phCredential,
PTimeStamp ptsExpiry
);
Parameter
AsyncContext
Der asynchrone Aufrufkontext.
pszPrincipal
Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Prinzipals angibt, dessen Anmeldeinformationen das Handle asynchron referenziert.
Hinweis
Wenn der Prozess, der das Handle anfordert, keinen Zugriff auf die Anmeldeinformationen hat, gibt die Funktion einen Fehler zurück. Eine NULL-Zeichenfolge gibt an, dass der Prozess ein Handle für die Anmeldeinformationen des Benutzers erfordert, unter dessen Sicherheitskontext er ausgeführt wird.
pszPackage
Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Sicherheitspakets angibt, mit dem diese Anmeldeinformationen verwendet werden. Dies ist ein Sicherheitspaketname, der im Member Name einer SecPkgInfo-Struktur zurückgegeben wird, der von der EnumerateSecurityPackages-Funktion zurückgegeben wird. Nachdem ein Kontext eingerichtet wurde, kann QueryContextAttributes (CredSSP) aufgerufen werden, wobei ulAttribute auf SECPKG_ATTR_PACKAGE_INFO festgelegt ist, um Informationen zum verwendeten Sicherheitspaket zurückzugeben.
fCredentialUse
Ein Flag, das angibt, wie diese Anmeldeinformationen verwendet werden. Dieser Parameter kann einer der folgenden Werte sein:
Wert |
Bedeutung |
|---|---|
| SECPKG_CRED_INBOUND | Überprüfen Sie eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer authentifizierenden Autorität überprüft werden, wenn SspiInitializeSecurityContextAsync oder SspiAcceptSecurityContextAsync aufgerufen wird. Wenn eine solche Autorität nicht verfügbar ist, schlägt die Funktion fehl und gibt SEC_E_NO_AUTHENTICATING_AUTHORITY zurück. Die Validierung ist paketspezifisch. |
| SECPKG_CRED_OUTBOUND | Erlauben Sie lokalen Clientanmeldeinformationen, ein ausgehendes Token vorzubereiten. |
pvLogonId
Ein Zeiger auf einen lokal eindeutigen Bezeichner (LUID), der den Benutzer identifiziert. Dieser Parameter wird für Dateisystemprozesse wie Netzwerkumleitungen bereitgestellt. Dieser Parameter kann NULL sein.
pAuthData
Ein Zeiger auf eine CREDSSP_CRED-Struktur , die Authentifizierungsdaten für Schannel- und Negotiate-Pakete angibt.
pGetKeyFn
Zeiger auf die GetKey()-Funktion.
pvGetKeyArgument
Übergeben Sie an GetKey().
phCredential
Ein Zeiger auf die CredHandle-Struktur , die das Anmeldeinformationshandle empfängt.
ptsExpiry
Optional Ein Zeiger auf eine TimeStamp-Struktur , die den Zeitpunkt empfängt, zu dem die zurückgegebenen Anmeldeinformationen ablaufen. Der empfangene Strukturwert hängt vom Sicherheitspaket ab, das den Wert zur Ortszeit angeben muss.
Rückgabewert
Gibt SEC_E_OK zurück, wenn die asynchrone Anforderung zum Abrufen eines Anmeldeinformationshandles erfolgreich für die Ausführung in die Warteschlange gestellt wurde. Andernfalls wird der Fehler zurückgegeben, der beim Versuch der Warteschlange generiert wurde. Verwenden Sie SspiGetAsyncCallStatus, um die status des Vorgangs abzurufen.
Wenn das Handle abgerufen wurde, gibt SspiGetAsyncCallStatus SEC_E_OK 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 folgenden Tabelle.
Rückgabecode |
Beschreibung |
|---|---|
| SEC_E_INSUFFICIENT_MEMORY | Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen. |
| SEC_E_INTERNAL_ERROR | Es ist ein Fehler aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde. |
| SEC_E_NO_CREDENTIALS | Im Sicherheitspaket sind keine Anmeldeinformationen verfügbar. |
| SEC_E_NOT_OWNER | Der Aufrufer der Funktion verfügt nicht über die erforderlichen Anmeldeinformationen. |
| SEC_E_SECPKG_NOT_FOUND | Das angeforderte Sicherheitspaket ist nicht vorhanden. |
| SEC_E_UNKNOWN_CREDENTIALS | Die für das Paket angegebenen Anmeldeinformationen wurden nicht erkannt. |
Hinweise
Die SspiAcquireCredentialsHandleAsyncW-Funktion gibt ein Handle für die Anmeldeinformationen eines Prinzipals zurück, z. B. eines Benutzers oder Clients, die von einem bestimmten Sicherheitspaket verwendet werden. Die Funktion kann das Handle entweder an bereits vorhandene Anmeldeinformationen oder an neu erstellte Anmeldeinformationen zurückgeben und es zurückgeben. Dieses Handle kann in nachfolgenden Aufrufen der Funktionen SspiAcceptSecurityContextAsync und SspiInitializeSecurityContextAsync verwendet werden.
Im Allgemeinen stellt SspiAcquireCredentialsHandleAsyncW nicht die Anmeldeinformationen anderer Benutzer bereit, die auf demselben Computer angemeldet sind. Ein Aufrufer mit SE_TCB_NAME Berechtigungen kann jedoch die Anmeldeinformationen einer vorhandenen Anmeldesitzung abrufen, indem er den Anmeldebezeichner (LUID) dieser Sitzung angibt. In der Regel wird dies von Kernelmodusmodulen verwendet, die im Auftrag eines angemeldeten Benutzers handeln müssen.
Ein Paket kann die Funktion in pGetKeyFn aufrufen, die vom RPC-Laufzeittransport bereitgestellt wird. Wenn der Transport das Konzept des Rückrufs zum Abrufen von Anmeldeinformationen nicht unterstützt, muss dieser Parameter NULL sein.
Für Kernelmodusaufrufer müssen die folgenden Unterschiede beachtet werden:
- Die beiden Zeichenfolgenparameter müssen Unicode-Zeichenfolgen sein.
- Die Pufferwerte müssen im virtuellen Prozessspeicher und nicht aus dem Pool zugeordnet werden.
Wenn Sie die verwendung der zurückgegebenen Anmeldeinformationen abgeschlossen haben, geben Sie den von den Anmeldeinformationen verwendeten Arbeitsspeicher frei, indem Sie die SspiFreeCredentialsHandleAsync-Funktion aufrufen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 10, Version 1607 [nur Kernelmodustreiber] |
| Unterstützte Mindestversion (Server) | Windows Server 2016 [nur Kernelmodustreiber] |
| Kopfzeile | sspi.h |
Weitere Informationen
SspiAcceptSecurityContextAsync
SspiFreeCredentialsHandleAsync