AcquireCredentialsHandle -Funktion (Allgemein)

Artikel
06/13/2023

Die Funktion AcquireCredentialsHandle (Allgemein) ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab. Dieses Handle ist für die Funktionen InitializeSecurityContext (Allgemein) und AcceptSecurityContext (Allgemein) 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.

Informationen zur Verwendung dieser Funktion mit einem bestimmten Sicherheitsunterstützungsanbieter (Security Support Provider , SSP) finden Sie in den folgenden Themen.

Thema	BESCHREIBUNG
AcquireCredentialsHandle (CredSSP)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der den Sicherheitsunterstützungsanbieter für Anmeldeinformationen (Credential Security Support Provider, CredSSP) verwendet.
AcquireCredentialsHandle (Digest)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der Digest verwendet.
AcquireCredentialsHandle (Kerberos)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der Kerberos verwendet.
AcquireCredentialsHandle (Negotiate)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der Negotiate verwendet.
AcquireCredentialsHandle (NTLM)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der NTLM verwendet.
AcquireCredentialsHandle (Schannel)	Ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab, der Schannel verwendet.

Syntax

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

Parameter

pszPrincipal [in]

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

Bei Verwendung des Digest-SSP ist dieser Parameter optional.

Bei Verwendung des Schannel-SSP wird dieser Parameter nicht verwendet und sollte auf NULL festgelegt werden.

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

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 (General) aufgerufen werden, wobei ulAttribute auf SECPKG_ATTR_PACKAGE_INFO festgelegt ist, um Informationen zum verwendeten Sicherheitspaket zurückzugeben.

Legen Sie bei Verwendung des Digest-SSP diesen Parameter auf WDIGEST_SP_NAME fest.

Legen Sie bei Verwendung des Schannel-SSP diesen Parameter auf UNISP_NAME fest.

fCredentialUse [in]

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

Wert	Bedeutung
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	Die Sicherheit verwendet keine Standardanmeldeinformationen oder Anmeldeinformationen aus dem Anmeldeinformations-Manager. Dieser Wert wird nur von der eingeschränkten Delegierung Negotiate unterstützt. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SECPKG_CRED_BOTH	Überprüfen Sie eingehende Anmeldeinformationen, oder verwenden Sie lokale Anmeldeinformationen, um ein ausgehendes Token vorzubereiten. Dieses Flag ermöglicht beide anderen Flags. Dieses Flag ist für die Digest- und Schannel-SSPs ungültig.
SECPKG_CRED_INBOUND	Überprüfen Sie eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer authentifizierenden Autorität überprüft werden, wenn InitializeSecurityContext (Allgemein) oder AcceptSecurityContext (Allgemein) 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.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	Die Funktion verarbeitet die Serverrichtlinie und gibt SEC_E_NO_CREDENTIALS zurück, die angibt, dass die Anwendung zur Eingabe von Anmeldeinformationen aufgefordert werden soll. Dieser Wert wird nur von der eingeschränkten Delegierung Negotiate unterstützt. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

pvLogonID [in]

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.

Bei Verwendung des Schannel-SSP wird dieser Parameter nicht verwendet und sollte auf NULL festgelegt werden.

pAuthData [in]

Ein Zeiger auf paketspezifische Daten. Dieser Parameter kann NULL sein, was angibt, dass die Standardanmeldeinformationen für dieses Sicherheitspaket verwendet werden müssen. Um die angegebenen Anmeldeinformationen zu verwenden, übergeben Sie eine SEC_WINNT_AUTH_IDENTITY-Struktur , die diese Anmeldeinformationen in diesem Parameter enthält. Die RPC-Laufzeit vergeht, was in RpcBindingSetAuthInfo bereitgestellt wurde.

Bei Verwendung des Digest-SSP ist dieser Parameter ein Zeiger auf eine SEC_WINNT_AUTH_IDENTITY-Struktur , die Authentifizierungsinformationen enthält, die zum Suchen der Anmeldeinformationen verwendet werden sollen.

Geben Sie bei Verwendung des Schannel-SSP eine SCHANNEL_CRED-Struktur an, die das zu verwendende Protokoll und die Einstellungen für verschiedene anpassbare Kanalfeatures angibt.

Bei Verwendung der NTLM- oder Negotiate-Pakete beträgt die maximale Zeichenlänge für Benutzername, Kennwort und Domäne 256, 256 bzw. 15.

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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

phCredential [out]

Ein Zeiger auf eine CredHandle-Struktur zum Empfangen des Anmeldeinformationshandles.

ptsExpiry [out]

Ein Zeiger auf eine TimeStamp-Struktur , die den Zeitpunkt empfängt, zu dem die zurückgegebenen Anmeldeinformationen ablaufen. Der in dieser TimeStamp-Struktur zurückgegebene Wert hängt von der eingeschränkten Delegierung ab. Das Sicherheitspaket muss diesen Wert zur Ortszeit zurückgeben.

Dieser Parameter ist auf eine konstante maximale Zeit festgelegt. Es gibt keine Ablaufzeit für Digest-Sicherheitskontexteoder Anmeldeinformationen oder bei Verwendung des Digest-SSP.

Wenn Sie den Schannel-SSP verwenden, ist dieser Parameter optional. Wenn es sich bei den Anmeldeinformationen, die für die Authentifizierung verwendet werden sollen, um ein Zertifikat handelt, empfängt dieser Parameter die Ablaufzeit für dieses Zertifikat. Wenn kein Zertifikat angegeben wurde, wird ein maximaler Zeitwert zurückgegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion 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	In der eingeschränkten Delegierung 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.

Bemerkungen

Die Funktion AcquireCredentialsHandle (Allgemein) gibt ein Handle für die Anmeldeinformationen eines Prinzipals zurück, z. B. eines Benutzers oder Clients, wie sie von einer bestimmten eingeschränkten Delegierung verwendet werden. Dies kann das Handle für bereits vorhandene Anmeldeinformationen sein, oder die Funktion kann einen neuen Satz von Anmeldeinformationen erstellen und zurückgeben. Dieses Handle kann in nachfolgenden Aufrufen der Funktionen AcceptSecurityContext (Allgemein) und InitializeSecurityContext (Allgemein) verwendet werden.

Im Allgemeinen lässt AcquireCredentialsHandle (Allgemein) einem Prozess nicht zu, ein Handle für die Anmeldeinformationen anderer Benutzer abzurufen, die auf demselben Computer angemeldet sind. Ein Aufrufer mit SE_TCB_NAME Berechtigung hat jedoch die Möglichkeit, den Anmeldebezeichner (LUID) eines vorhandenen Anmeldesitzungstokens anzugeben, um ein Handle für die Anmeldeinformationen dieser Sitzung abzurufen. 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.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Header	Sspi.h (einschließlich Security.h)
Bibliothek	Secur32.lib
DLL	Secur32.dll
Unicode- und ANSI-Name	AcquireCredentialsHandleW (Unicode) und AcquireCredentialsHandleA (ANSI)

Siehe auch

SSPI-Funktionen
AcceptSecurityContext (Allgemein)
InitializeSecurityContext (Allgemein)
FreeCredentialsHandle

Freigeben über