AcquireCredentialsHandleA-Funktion (sspi.h)

Artikel
08/26/2023

Die Funktion AcquireCredentialsHandle (CredSSP) ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab. Dieses Handle ist für die Funktionen InitializeSecurityContext (CredSSP) und AcceptSecurityContext (CredSSP) 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 Dies ist kein "Anmelden beim Netzwerk" und impliziert nicht das Sammeln von Anmeldeinformationen.

Syntax

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [in]            unsigned long  fCredentialUse,
  [in, optional]  void           *pvLogonId,
  [in, optional]  void           *pAuthData,
  [in, optional]  SEC_GET_KEY_FN pGetKeyFn,
  [in, optional]  void           *pvGetKeyArgument,
  [out]           PCredHandle    phCredential,
  [out, optional] PTimeStamp     ptsExpiry
);

Parameter

[in, optional] pszPrincipal

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Namen des Prinzipals angibt, auf dessen Anmeldeinformationen das Handle verweist.

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.

[in] 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.

[in] fCredentialUse

Ein Flag, das angibt, wie diese Anmeldeinformationen verwendet werden. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
SECPKG_CRED_INBOUND 0x1	Überprüfen Sie eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer authentifizierenden Autorität überprüft werden, wenn InitializeSecurityContext (CredSSP) oder AcceptSecurityContext (CredSSP) 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 0x2	Erlauben Sie lokalen Clientanmeldeinformationen, ein ausgehendes Token vorzubereiten.

Wert

Bedeutung

SECPKG_CRED_INBOUND
0x1

Überprüfen Sie eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer authentifizierenden Autorität überprüft werden, wenn InitializeSecurityContext (CredSSP) oder AcceptSecurityContext (CredSSP) 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
0x2

Erlauben Sie lokalen Clientanmeldeinformationen, ein ausgehendes Token vorzubereiten.

[in, optional] 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.

[in, optional] pAuthData

Ein Zeiger auf eine CREDSSP_CRED-Struktur , die Authentifizierungsdaten für Schannel- und Negotiate-Pakete angibt.

[in, optional] pGetKeyFn

Reserviert. Dieser Parameter wird nicht verwendet und sollte auf NULL festgelegt werden.

[in, optional] pvGetKeyArgument

Reserviert. Dieser Parameter muss auf NULL festgelegt werden.

[out] phCredential

Ein Zeiger auf die CredHandle-Struktur , die das Anmeldeinformationshandle empfängt.

[out, optional] ptsExpiry

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

Wenn die Funktion erfolgreich ist, gibt sie SEC_E_OK zurück.

Wenn die Funktion fehlschlägt, gibt sie einen der folgenden Fehlercodes zurück.

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 Funktion AcquireCredentialsHandle (CredSSP) gibt ein Handle an die Anmeldeinformationen eines Prinzipals zurück, z. B. eines Benutzers oder Clients, wie sie 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 AcceptSecurityContext (CredSSP) und InitializeSecurityContext (CredSSP) verwendet werden.

Im Allgemeinen stellt AcquireCredentialsHandle (CredSSP) 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 mit der Verwendung der zurückgegebenen Anmeldeinformationen fertig sind, geben Sie den von den Anmeldeinformationen verwendeten Arbeitsspeicher frei, indem Sie die FreeCredentialsHandle-Funktion aufrufen.

Hinweis

Der sspi.h-Header definiert AcquireCredentialsHandle als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	sspi.h (einschließlich Security.h)
Bibliothek	Secur32.lib
DLL	Secur32.dll

Weitere Informationen

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

SSPI-Funktionen