AcquireCredentialsHandle(Schannel)-Funktion
Die Funktion AcquireCredentialsHandle (Schannel) ruft ein Handle für bereits vorhandene Anmeldeinformationen eines Sicherheitsprinzipals ab. Dieses Handle ist für die Funktionen InitializeSecurityContext (Schannel) und AcceptSecurityContext (Schannel) erforderlich. Dabei kann es sich entweder um bereits vorhandene Anmeldeinformationen handeln, die über eine hier nicht beschriebene Systemanmeldung eingerichtet werden, 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 AcquireCredentialsHandle(
_In_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_opt_ PLUID pvLogonID,
_In_opt_ PVOID pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_In_opt_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
Parameter
pszPrincipal[in, optional]
Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des Prinzipals angibt, auf dessen Anmeldeinformationen das Handle verweist.
Bei Verwendung des Schannel-SSP wird dieser Parameter nicht verwendet und sollte auf NULLfestgelegt 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-endende 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, die von der EnumerateSecurityPackages-Funktion zurückgegeben wird. Nachdem ein Kontext eingerichtet wurde, kann QueryContextAttributes (Schannel) aufgerufen werden, wobei ulAttribute auf SECPKG_ATTR_PACKAGE_INFO festgelegt ist, um Informationen zum verwendeten Sicherheitspaket zurückzugeben.
Wenn Sie den Schannel-SSP verwenden, legen Sie diesen Parameter auf fest UNISP_NAME.
Hinweis
Aufrufer im Kernelmodus, bei denen beim Aufrufen von InitializeSecurityContext (Schannel) nach dem Aufruf von AcquireCredentialsHandle (Schannel) Probleme auftreten, können pszPackage alternativ auf SCHANNEL_NAMEfestlegen.
fCredentialUse[in]
Ein Flag, das angibt, wie diese Anmeldeinformationen verwendet werden. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
| SECPKG_CRED_INBOUND | Überprüfen Sie eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer Authentifizierungsautorität überprüft werden, wenn InitializeSecurityContext (Schannel) oder AcceptSecurityContext (Schannel) 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 | 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.
Bei Verwendung des Schannel-SSP wird dieser Parameter nicht verwendet und sollte auf NULLfestgelegt werden.
pAuthData[in, optional]
Ein Zeiger auf paketspezifische Daten. Dieser Parameter kann sein NULL, 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 auch immer in RpcBindingSetAuthInfo bereitgestellt wurde.
Wenn Sie den Schannel-SSP verwenden, geben Sie eine SCH_CREDENTIALS-Struktur an, die das zu verwendende Protokoll und die Einstellungen für verschiedene anpassbare Kanalfeatures angibt.
pGetKeyFn[in, optional]
Dieser Parameter wird nicht verwendet und sollte auf NULLfestgelegt werden.
pvGetKeyArgument[in, optional]
Dieser Parameter wird nicht verwendet und sollte auf NULLfestgelegt werden.
phCredential[out]
Ein Zeiger auf eine CredHandle-Struktur zum Empfangen des Anmeldeinformationshandles.
ptsExpiry[out, optional]
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.
Bei Verwendung des Schannel-SSP ist dieser Parameter optional. Wenn es sich bei den für die Authentifizierung zu verwendenden Anmeldeinformationen 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 zurück SEC_E_OK.
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. |
Hinweise
Die AcquireCredentialsHandle -Funktion (Schannel) gibt ein Handle für die Anmeldeinformationen eines Prinzipals zurück, z. B. eines Benutzers oder Clients, wie es von einer bestimmten eingeschränkten Delegierung verwendet wird. 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 (Schannel) und InitializeSecurityContext (Schannel) verwendet werden.
Im Allgemeinen lässt AcquireCredentialsHandle (Schannel) einem Prozess nicht zu, ein Handle für die Anmeldeinformationen anderer Benutzer abzurufen, die auf demselben Computer angemeldet sind. Ein Aufrufer mit SE_TCB_NAMEBerechtigung 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 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 sein NULL.
Für Aufrufer im Kernelmodus 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 verwendung der zurückgegebenen Anmeldeinformationen abgeschlossen haben, geben Sie den von den Anmeldeinformationen verwendeten Arbeitsspeicher frei, indem Sie die Funktion FreeCredentialsHandle 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) |
Weitere Informationen
AcceptSecurityContext (Schannel)