AcquireCredentialsHandle (Schannel)-Funktion

Die Funktion "AcquireCredentialsHandle" (Schannel) erhält einen Handle, um Anmeldeinformationen eines Sicherheitsprinzipals vorzugeben. Dieser Handle ist von den Funktionen InitializeSecurityContext (Schannel) und AcceptSecurityContext (Schannel) erforderlich. Dies kann entweder bereits vorhandene Anmeldeinformationen sein, die über eine Systemanmeldung eingerichtet werden, die hier nicht beschrieben wird, oder der Anrufer kann alternative Anmeldeinformationen bereitstellen.

Hinweis

Dies ist kein "Anmelden im Netzwerk" und bedeutet 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-beendete Zeichenfolge, die den Namen des Prinzipals angibt, auf dessen Anmeldeinformationen der Handle verweist.

Wenn Sie den Schannel-SSP verwenden, wird dieser Parameter nicht verwendet und sollte auf NULL festgelegt werden.

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 der Prozess einen Handle für die Anmeldeinformationen des Benutzers erfordert, dessen Sicherheitskontext er ausgeführt wird.

 

pszPackage [in]

Ein Zeiger auf eine null-beendete Zeichenfolge, die den Namen des Sicherheitspakets angibt, mit dem diese Anmeldeinformationen verwendet werden. Dies ist ein Sicherheitspaketname , der im Namenmitglied einer SecPkgInfo-Struktur zurückgegeben wird, die von der Funktion "EnumerateSecurityPackages " zurückgegeben wird. Nachdem ein Kontext eingerichtet wurde, kann QueryContextAttributes (Schannel) mit ulAttribute-Set auf SECPKG_ATTR_PACKAGE_INFO aufgerufen werden, um Informationen über das verwendete Sicherheitspaket zurückzugeben.

Legen Sie diesen Parameter beim Verwenden des Schannel-SSP 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_INBOUND
Überprüfen Sie eine eingehende Serveranmeldeinformationen. Eingehende Anmeldeinformationen können mithilfe einer Authentifizierungsstelle überprüft werden, wenn InitializeSecurityContext (Schannel) oder AcceptSecurityContext (Schannel) aufgerufen wird. Wenn eine solche Behörde 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
Zulassen, dass eine 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.

Wenn Sie den Schannel-SSP verwenden, wird dieser Parameter nicht verwendet und sollte auf NULL festgelegt werden.

pAuthData [in, optional]

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, was in RpcBindingSetAuthInfo bereitgestellt wurde.

Geben Sie bei Verwendung des Schannel-SSP eine SCH_CREDENTIALS Struktur an, die das Protokoll angibt, das verwendet werden soll, und die Einstellungen für verschiedene anpassbare Kanalfeatures.

pGetKeyFn [in, optional]

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

pvGetKeyArgument [in, optional]

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

phCredential [out]

Ein Zeiger auf eine CredHandle-Struktur , um den Anmeldeinformationenhandhandle-Handle zu erhalten.

ptsExpiry [out, optional]

Ein Zeiger auf eine TimeStamp-Struktur , die die Zeit empfängt, zu der 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 der lokalen Zeit zurückgeben.

Bei Verwendung des Schannel-SSP ist dieser Parameter optional. Wenn die für die Authentifizierung verwendeten 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, 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
Fehler, der einem SSPI-Fehlercode nicht zugeordnet wurde.
SEC_E_NO_CREDENTIALS
Es sind keine Anmeldeinformationen in der eingeschränkten Delegierung 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 an das Paket bereitgestellten Anmeldeinformationen wurden nicht erkannt.

 

Hinweise

Die Funktion "AcquireCredentialsHandle" (Schannel) gibt einen Handle an die Anmeldeinformationen eines Prinzipals zurück, z. B. einen Benutzer oder einen Client, der von einer bestimmten eingeschränkten Delegation verwendet wird. Dies kann das Handle sein, um Anmeldeinformationen vorzugeben, oder die Funktion kann einen neuen Satz von Anmeldeinformationen erstellen und zurückgeben. Dieser Handle kann in nachfolgenden Aufrufen der Funktionen AcceptSecurityContext (Schannel) und InitializeSecurityContext (Schannel) verwendet werden.

Im Allgemeinen erlaubt die AcquireCredentialsHandle (Schannel) keinen Prozess, um einen Handle für die Anmeldeinformationen anderer Benutzer abzurufen, die sich auf demselben Computer angemeldet haben. Ein Aufrufer mit SE_TCB_NAME-Berechtigungen hat jedoch die Möglichkeit, den Anmeldebezeichner (LUID) eines vorhandenen Anmeldesitzungstokens anzugeben, um ein Handle zu den Anmeldeinformationen dieser Sitzung abzurufen. Dies wird in der Regel 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 den Begriff des Rückrufs zum Abrufen von Anmeldeinformationen nicht unterstützt, muss dieser Parameter NULL sein.

Für Kernelmodusanrufer müssen die folgenden Unterschiede festgestellt werden:

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

Wenn Sie die zurückgegebenen Anmeldeinformationen verwendet haben, können Sie den von den Anmeldeinformationen verwendeten Speicher freizugeben, indem Sie die Funktion "FreeCredentialsHandle " aufrufen.

Requirements (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)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

SSPI-Funktionen