AcquireCredentialsHandle(General)-Funktion
Die AcquireCredentialsHandle (General)-Funktion erhält ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals. Dieses Handle ist für die Funktionen InitializeSecurityContext (General) und AcceptSecurityContext (General) erforderlich. Dies können 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 keine "Anmeldung beim Netzwerk" und impliziert nicht das Sammeln von Anmeldeinformationen.
Informationen zur Verwendung dieser Funktion mit einem bestimmten Sicherheitssupportanbieter (Security Support Provider, SSP) finden Sie in den folgenden Themen.
| Thema | Beschreibung |
|---|---|
| AcquireCredentialsHandle (CredSSP) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, der credSSP (Credential Security Support Provider) verwendet. |
| AcquireCredentialsHandle (Digest) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, der digest verwendet. |
| AcquireCredentialsHandle (Kerberos) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, der Kerberos verwendet. |
| AcquireCredentialsHandle (Negotiate) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, der Negotiate verwendet. |
| AcquireCredentialsHandle (NTLM) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, der NTLM verwendet. |
| AcquireCredentialsHandle (Schannel) |
Übernimmt ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals, 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 auf 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 angibt, 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 auf 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, kann QueryContextAttributes (General) mit ulAttribute aufgerufen werden, das auf SECPKG ATTR PACKAGE INFO festgelegt ist, um Informationen zum sicherheitspaket zurück zu geben, das _ verwendet _ _ wird.
Wenn Sie den Digest-SSP verwenden, legen Sie 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 Anmeldeinformationsverwaltung.
Dieser Wert wird nur von der eingeschränkten Negotiate-Delegierung 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 aktiviert beide anderen Flags. Dieses Flag ist für die SSPs Digest und Schannel ungültig. - SECPKG _ CRED _ EINGEHEND
Überprüfen Sie die Anmeldeinformationen eines eingehenden Servers. Eingehende Anmeldeinformationen können mithilfe einer Authentifizierungsstelle überprüft werden, wenn InitializeSecurityContext (General) oder AcceptSecurityContext (General) aufgerufen wird. Wenn eine solche Autorität nicht verfügbar ist, ist die Funktion nicht verfügbar und gibt SEC _ E _ NO _ AUTHENTICATING AUTHORITY _ zurück. Die Validierung ist paketspezifisch. - SECPKG _ CRED _ OUTBOUND
Ermöglichen Sie es lokalen Client-Anmeldeinformationen, ein ausgehendes Token vorzubereiten. - SECPKG _ CRED _ PROCESS _ POLICY _ ONLY
- 0x00000020
Die Funktion verarbeitet die Serverrichtlinie und gibt SEC E NO CREDENTIALS _ _ _ zurück, was angibt, dass die Anwendung zur Eingabe von Anmeldeinformationen aufgefordert werden soll.
Dieser Wert wird nur von der eingeschränkten Negotiate-Delegierung 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 übergibt das, 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.
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, um das Anmeldeinformationshandle zu empfangen.
-
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 in Ortszeit zurückgeben.
Dieser Parameter wird auf eine konstante maximale Zeit festgelegt. Es gibt keine Ablaufzeit für Digestsicherheitskontexteoder Anmeldeinformationen oder bei Verwendung des Digest-SSP.
Bei Verwendung des Schannel-SSP ist dieser Parameter optional. Wenn die für die Authentifizierung zu verwendenden Anmeldeinformationen ein Zertifikat sind, erhält 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, wird einer der folgenden Fehlercodes zurückgegeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abschließen zu können. |
|
Es ist ein Fehler aufgetreten, der einem SSPI-Fehlercode nicht zuordnen konnte. |
|
In der eingeschränkten Delegierung sind keine Anmeldeinformationen verfügbar. |
|
Der Aufrufer der Funktion verfügt nicht über die erforderlichen Anmeldeinformationen. |
|
Das angeforderte Sicherheitspaket ist nicht vorhanden. |
|
Die für das Paket angegebenen Anmeldeinformationen wurden nicht erkannt. |
Hinweise
Die Funktion AcquireCredentialsHandle (Allgemein) gibt ein Handle für die Anmeldeinformationen eines Prinzipals zurück, z. B. eines Benutzers oder Clients, wie von einer bestimmten eingeschränkten Delegierungverwendet. 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) nicht zu, dass ein Prozess ein Handle für die Anmeldeinformationen anderer Benutzer erhält, 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 Namen eines angemeldeten Benutzers agieren müssen.
Ein Paket ruft möglicherweise die Funktion in pGetKeyFn auf, 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.
Bei Kernelmodusaufrufern 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 zurückgegebenen Anmeldeinformationen verwendet haben, können Sie den von den Anmeldeinformationen verwendeten Arbeitsspeicher freigeben, indem Sie die FreeCredentialsHandle-Funktion aufrufen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) |
Windows [Nur XP-Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
Windows Nur Server [ 2003-Desktop-Apps] |
| Header |
|
| Bibliothek |
|
| DLL |
|
| Unicode- und ANSI-Name |
AcquireCredentialsHandleW (Unicode) und AcquireCredentialsHandleA (ANSI) |