AcquireCredentialsHandle (Schannel)-Funktion

Die Funktion AcquireCredentialsHandle (Schannel) erwirbt ein Handle zum Vorabexistenz von Anmeldeinformationen eines Sicherheitsprinzipals. Dieser Handle wird von den Funktionen InitializeSecurityContext (Schannel) und AcceptSecurityContext (Schannel) 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.

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
);

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.

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

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 (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 UNISP_NAME.

fCredentialUse[in]

Ein Flag, das angibt, wie diese Anmeldeinformationen verwendet werden. Dieser Parameter kann einer der folgenden Werte sein:

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 .NULL

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

Geben Sie bei Verwendung des Schannel-SSP 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 NULL.

pvGetKeyArgument[in, optional]

Dieser Parameter wird nicht verwendet und sollte auf NULL.

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 der lokalen Zeit zurückgeben.

Bei Verwendung des Schannel-SSP ist dieser Parameter optional. Wenn die für die Authentifizierung zu verwendenden Anmeldeinformationen ein Zertifikat sind, 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, wird die Funktion zurückgegeben SEC_E_OK.

Wenn die Funktion fehlschlägt, wird eine der folgenden Fehlercodes zurückgegeben.

Bemerkungen

Die Funktion AcquireCredentialsHandle (Schannel) gibt ein Handle an die Anmeldeinformationen eines Prinzipals zurück, z. B. ein Benutzer oder Client, 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) keinen Prozess zu, um 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. 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 sein NULL.

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

Siehe auch

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

SSPI-Funktionen