AcquireCredentialsHandleA-Funktion (sspi.h)

Artikel
11/20/2024

Die AcquireCredentialsHandle (CredSSP)-Funktion erwirbt ein Handle, um Anmeldeinformationen eines Sicherheitsprinzipalsvorhanden zu sein. Dieser Handle wird vom InitializeSecurityContext (CredSSP) und AcceptSecurityContext (CredSSP) Funktionen benötigt. Dies kann entweder bereits Anmeldeinformationenvorhanden sein, die über eine Systemanmeldung eingerichtet werden, die hier nicht beschrieben wird, oder der Aufrufer kann alternative Anmeldeinformationen bereitstellen.

Hinweis Dies ist kein "Anmelden am 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 mit Null beendete Zeichenfolge, die den Namen des Prinzipals angibt, auf dessen Anmeldeinformationen das Handle verweist.

Hinweis Wenn der Prozess, der den Handle anfordert, keinen Zugriff auf die Anmeldeinformationen hat, gibt die Funktion einen Fehler zurück. Eine NULL-Zeichenfolge gibt an, dass für den Prozess ein Handle für die Anmeldeinformationen des Benutzers erforderlich ist, unter dessen Sicherheitskontext ausgeführt wird.

[in] pszPackage

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Namen des Sicherheitspakets angibt mit dem diese Anmeldeinformationen verwendet werden. Dies ist ein Sicherheitspaketname, der im Name Member einer SecPkgInfo- Struktur zurückgegeben wird, die von der EnumerateSecurityPackages--Funktion zurückgegeben wird. Nachdem ein Kontext eingerichtet wurde, können 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 einer der folgenden Werte sein:

Wert	Bedeutung
SECPKG_CRED_INBOUND 0x1	Überprüfen sie die Anmeldeinformationen eines Posteingangsservers. Eingehende Anmeldeinformationen können mithilfe einer Authentifizierungsautoritä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_AUTHORITYzurück. Die Überprüfung ist paketspezifisch.
SECPKG_CRED_OUTBOUND 0x2	Zulassen, dass lokale Clientanmeldeinformationen ein ausgehendes Token vorbereiten.

Wert

Bedeutung

SECPKG_CRED_INBOUND
0x1

Überprüfen sie die Anmeldeinformationen eines Posteingangsservers. Eingehende Anmeldeinformationen können mithilfe einer Authentifizierungsautoritä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_AUTHORITYzurück. Die Überprüfung ist paketspezifisch.

SECPKG_CRED_OUTBOUND
0x2

Zulassen, dass lokale Clientanmeldeinformationen ein ausgehendes Token vorbereiten.

[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 den Anmeldeinformationshandle-Handle 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 in der lokalen Zeit angeben muss.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird SEC_E_OKzurückgegeben.

Wenn die Funktion fehlschlägt, wird eine der folgenden Fehlercodes zurückgegeben.

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	Ein Fehler ist aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde.
SEC_E_NO_CREDENTIALS	Im Sicherheitspaketsind 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 bereitgestellten Anmeldeinformationen wurden nicht erkannt.

Bemerkungen

Die AcquireCredentialsHandle (CredSSP) Funktion gibt ein Handle an die Anmeldeinformationen eines Prinzipals zurück, z. B. ein Benutzer oder Client, wie es von einem bestimmten Sicherheitspaketverwendet wird. Die Funktion kann das Handle entweder an vorhandene Anmeldeinformationen oder neu erstellte Anmeldeinformationen zurückgeben und zurückgeben. Dieses Handle kann in nachfolgenden Aufrufen der AcceptSecurityContext (CredSSP) und InitializeSecurityContext (CredSSP) Funktionen verwendet werden.

Im Allgemeinen stellt AcquireCredentialsHandle (CredSSP) nicht die Anmeldeinformationen anderer Benutzer bereit, die sich auf demselben Computer angemeldet haben. Ein Aufrufer mit SE_TCB_NAME Berechtigungen kann jedoch die Anmeldeinformationen einer vorhandenen Anmeldesitzung abrufen, indem der Anmeldebezeichner (LUID) dieser Sitzung angegeben wird. Dies wird in der Regel von Kernelmodusmodulen verwendet, die im Namen eines angemeldeten Benutzers handeln müssen.

Ein Paket ruft die Funktion möglicherweise in pGetKeyFn- auf, die vom RPC-Laufzeittransport bereitgestellt wird. Wenn der Transport den Begriff des Rückrufs zum Abrufen von Anmeldeinformationen nicht unterstützt, muss dieser Parameter NULL-sein.

Bei Kernelmodusaufrufern müssen die folgenden Unterschiede beachtet werden:

Die beiden Zeichenfolgenparameter müssen Unicode- Zeichenfolgen sein.
Die Pufferwerte müssen im virtuellen Prozessspeicher zugewiesen werden, nicht aus dem Pool.

Wenn Sie die zurückgegebenen Anmeldeinformationen verwendet haben, geben Sie den von den Anmeldeinformationen verwendeten Speicher frei, indem Sie die FreeCredentialsHandle--Funktion aufrufen.

Anmerkung

Der header sspi.h 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 Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	sspi.h (include Security.h)
Library	Secur32.lib
DLL-	Secur32.dll

Siehe auch

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle-

InitializeSecurityContext (CredSSP)

SSPI-Funktionen

Freigeben über