Freigeben über

AcquireCredentialsHandle (CredSSP)-Funktion

Die AcquireCredentialsHandle (CredSSP) -Funktion erhält ein Handle zum Vorabexistenz von Anmeldeinformationen eines Sicherheitsprinzipals. Dieses Handle wird von den Funktionen InitializeSecurityContext (CredSSP) und AcceptSecurityContext (CredSSP) benötigt. Hierbei kann es sich entweder um bereits vorhandene Anmeldeinformationen handeln, 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 AcquireCredentialsHandle(
  _In_opt_   SEC_CHAR       *pszPrincipal,
  _In_       SEC_CHAR       *pszPackage,
  _In_       unsigned long  fCredentialUse,
  _In_opt_   void           *pvLogonID,
  _In_opt_   void           *pAuthData,
  _In_opt_   SEC_GET_KEY_FN pGetKeyFn,
  _Reserved_ void           *pvGetKeyArgument,
  _Out_      PCredHandle    phCredential,
  _Out_opt_  PTimeStamp     ptsExpiry
);

Die Parameter

pszPrincipal [in, optional]

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 das 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 er ausgeführt wird.

pszPackage [in]

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-Element einer SecPkgInfo-Struktur zurückgegeben wird, die von der Funktion EnumerateSecurityPackages 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 [in]

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_AUTHORITY zurück. Die Überprüfung ist paketspezifisch.
SECPKG_CRED_OUTBOUND
0x0		 Zulassen, dass lokale Clientanmeldeinformationen ein ausgehendes Token vorbereiten.

pvLogonId [in, optional]

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

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

pGetKeyFn [in, optional]

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

pvGetKeyArgument [in, optional]

Reserviert. Dieser Parameter muss auf NULL festgelegt werden.

phCredential [out]

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

ptsExpiry [out, 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 in der lokalen Zeit angeben muss.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird SEC_E_OK zurü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 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 bereitgestellten Anmeldeinformationen wurden nicht erkannt.

Bemerkungen

Die Funktion AcquireCredentialsHandle (CredSSP) gibt ein Handle an die Anmeldeinformationen eines Prinzipals zurück, z. B. ein Benutzer oder Client, wie es von einem bestimmten Sicherheitspaket verwendet 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 Funktionen AcceptSecurityContext (CredSSP) und InitializeSecurityContext (CredSSP) 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 Berechtigung kann jedoch die Anmeldeinformationen einer vorhandenen Anmeldesitzung abrufen, indem er die Anmelde-ID (LUID) dieser Sitzung angibt. Dies wird in der Regel von Kernelmodusmodulen verwendet, die im Namen eines angemeldeten Benutzers handeln müssen.

Ein Paket ruft möglicherweise die Funktion 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 Arbeitsspeicher frei, indem Sie die FreeCredentialsHandle-Funktion aufrufen.

Anforderungen

Anforderung Wert
Mindest unterstützter Client Windows Vista [nur Desktop-Apps]
Unterstützter Server (Mindestversion) Windows Server 2008 [Nur Desktop-Apps]
Kopfzeile Sspi.h (einschließlich Security.h)
Bibliothek Secur32.lib
DLL Secur32.dll
Unicode- und ANSI-Namen AcquireCredentialsHandleW (Unicode) und AcquireCredentialsHandleA (ANSI)

Siehe auch