Funktionen AcquireCredentialsHandle (Allmänt)

2025-04-08

Funktionen AcquireCredentialsHandle (Allmänt) hämtar en referens till befintliga autentiseringsuppgifter för ett säkerhetsobjekt. Den här handtaget krävs av funktionerna InitializeSecurityContext (Allmänt) och AcceptSecurityContext (Allmänt). Dessa kan vara antingen befintliga autentiseringsuppgifter, som upprättas via en systeminloggning som inte beskrivs här, eller så kan anroparen ange alternativa autentiseringsuppgifter.

Anmärkning

Detta är inte en "inloggning till nätverket" och innebär inte insamling av autentiseringsuppgifter.

Information om hur du använder den här funktionen med en specifik SSP ( Security Support Provider ) finns i följande avsnitt.

Ämne	Beskrivning
AcquireCredentialsHandle (CredSSP)	Hämtar en referens till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder Credential Security Support Provider (CredSSP).
AcquireCredentialsHandle (Sammandrag)	Hämtar ett handtag till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder Digest.
AcquireCredentialsHandle (Kerberos)	Hämtar en referens till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder Kerberos.
AcquireCredentialsHandle (förhandla)	Hämtar en referens till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder Negotiate.
AcquireCredentialsHandle (NTLM)	Hämtar ett handtag till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder NTLM.
AcquireCredentialsHandle (Schannel)	Hämtar ett handtag till befintliga autentiseringsuppgifter för ett säkerhetsobjekt som använder Schannel.

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

Parameterar

pszPrincipal [in]

En pekare till en null-avslutad sträng som anger namnet på det huvudnamn vars autentiseringsuppgifter referensen ska referera till.

När du använder Digest SSP är den här parametern valfri.

När du använder Schannel SSP används inte den här parametern och ska vara inställd på NULL.

Anmärkning

Om den process som begär handtaget inte har åtkomst till autentiseringsuppgifterna returnerar funktionen ett fel. En null-sträng anger att processen kräver en referens till autentiseringsuppgifterna för användaren under vars säkerhetskontext den körs.

pszPackage [in]

En pekare till en null-avslutad sträng som anger namnet på säkerhetspaketet som dessa autentiseringsuppgifter ska användas med. Det här är ett säkerhetspaketnamn som returneras i namnmedlemmen i en SecPkgInfo-struktur som returneras av funktionen EnumerateSecurityPackages . När en kontext har upprättats kan QueryContextAttributes (Allmänt) anropas med ulAttribute inställt på SECPKG_ATTR_PACKAGE_INFO för att returnera information om det säkerhetspaket som används.

När du använder Digest SSP anger du den här parametern till WDIGEST_SP_NAME.

När du använder Schannel SSP anger du den här parametern till UNISP_NAME.

fCredentialUse [in]

En flagga som anger hur dessa autentiseringsuppgifter ska användas. Den här parametern kan vara ett av följande värden.

Värde	Innebörd
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	Säkerheten använder inte standardautentiseringsuppgifter för inloggning eller autentiseringsuppgifter från Credential Manager. Det här värdet stöds endast av den förhandlingsbegränsade delegeringen. Windows Server 2008, Windows Vista, Windows Server 2003 och Windows XP: Det här värdet stöds inte.
SECPKG_CRED_BOTH	Verifiera en inkommande autentiseringsuppgift eller använd en lokal autentiseringsuppgift för att förbereda en utgående token. Den här flaggan aktiverar båda andra flaggor. Den här flaggan är inte giltig med SSP:erna Digest och Schannel.
SECPKG_CRED_INBOUND	Verifiera en inkommande serverautentiseringsuppgift. Inkommande autentiseringsuppgifter kan verifieras med hjälp av en autentiserande utfärdare när InitializeSecurityContext (Allmänt) eller AcceptSecurityContext (Allmänt) anropas. Om en sådan utfärdare inte är tillgänglig misslyckas funktionen och returnerar SEC_E_NO_AUTHENTICATING_AUTHORITY. Valideringen är paketspecifik.
SECPKG_CRED_OUTBOUND	Tillåt att en lokal klientautentiseringsuppgift förbereder en utgående token.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	Funktionen bearbetar serverprincipen och returnerar SEC_E_NO_CREDENTIALS, vilket anger att programmet ska fråga efter autentiseringsuppgifter. Det här värdet stöds endast av den förhandlingsbegränsade delegeringen. Windows Server 2008, Windows Vista, Windows Server 2003 och Windows XP: Det här värdet stöds inte.

pvLogonID [in]

En pekare till en lokalt unik identifierare (LUID) som identifierar användaren. Den här parametern tillhandahålls för filsystemprocesser som nätverksomdirigeringar. Den här parametern kan vara NULL-.

När du använder Schannel SSP används inte den här parametern och ska vara inställd på NULL.

pAuthData [in]

En pekare till paketspecifika data. Den här parametern kan vara NULL, vilket anger att standardautentiseringsuppgifterna för säkerhetspaketet måste användas. Om du vill använda angivna autentiseringsuppgifter skickar du en SEC_WINNT_AUTH_IDENTITY struktur som innehåller dessa autentiseringsuppgifter i den här parametern. RPC-körningstiden passerar det som angavs i RpcBindingSetAuthInfo.

När du använder Digest SSP är den här parametern en pekare till en SEC_WINNT_AUTH_IDENTITY struktur som innehåller autentiseringsinformation som ska användas för att hitta autentiseringsuppgifterna.

När du använder Schannel SSP anger du en SCHANNEL_CRED struktur som anger vilket protokoll som ska användas och inställningarna för olika anpassningsbara kanalfunktioner.

När du använder NTLM- eller Negotiate-paketen är de maximala teckenlängderna för användarnamn, lösenord och domän 256, 256 respektive 15.

pGetKeyFn [in]

Den här parametern används inte och ska vara inställd på NULL.

pvGetKeyArgument [in]

Den här parametern används inte och ska vara inställd på NULL.

phCredential [out]

En pekare till en CredHandle-struktur för att ta emot referensen för autentiseringsuppgifter.

ptsExpiry [ut]

En pekare till en TimeStamp-struktur som tar emot den tid då de returnerade autentiseringsuppgifterna upphör att gälla. Värdet som returneras i den här TimeStamp-strukturen beror på den begränsade delegeringen. Säkerhetspaketet måste returnera det här värdet i lokal tid.

Den här parametern är inställd på en konstant maximal tid. Det finns ingen förfallotid för sammanfattade säkerhetskontextereller autentiseringsuppgifter eller när du använder Digest SSP.

När du använder Schannel SSP är den här parametern valfri. När autentiseringsuppgifterna som ska användas för autentisering är ett certifikat får den här parametern förfallotiden för certifikatet. Om inget certifikat har angetts returneras ett maximalt tidsvärde.

Returvärde

Om funktionen lyckas returnerar funktionen SEC_E_OK.

Om funktionen misslyckas returneras någon av följande felkoder.

Returkod	Beskrivning
SEC_E_INSUFFICIENT_MEMORY	Det finns inte tillräckligt med minne för att slutföra den begärda åtgärden.
SEC_E_INTERNAL_ERROR	Ett fel uppstod som inte mappades till en SSPI-felkod.
SEC_E_NO_CREDENTIALS	Inga autentiseringsuppgifter är tillgängliga i den begränsade delegeringen.
SEC_E_NOT_OWNER	Anroparen för funktionen har inte de nödvändiga autentiseringsuppgifterna.
SEC_E_SECPKG_NOT_FOUND	Det begärda säkerhetspaketet finns inte.
SEC_E_UNKNOWN_CREDENTIALS	De autentiseringsuppgifter som angavs för paketet kändes inte igen.

Anmärkningar

Funktionen AcquireCredentialsHandle (Allmänt) returnerar en referens till autentiseringsuppgifterna för ett huvudnamn, till exempel en användare eller klient, som används av en specifik begränsad delegering. Detta kan vara handtaget för befintliga autentiseringsuppgifter, eller så kan funktionen skapa en ny uppsättning autentiseringsuppgifter och returnera den. Den här referensen kan användas i efterföljande anrop till funktionerna AcceptSecurityContext (Allmänt) och InitializeSecurityContext (Allmänt).

I allmänhet tillåter Inte AcquireCredentialsHandle (Allmänt) en process för att hämta en handtag till autentiseringsuppgifterna för andra användare som är inloggade på samma dator. En anropare med SE_TCB_NAME behörighet har dock möjlighet att ange inloggningsidentifieraren (LUID) för en befintlig inloggningssessionstoken för att få en referens till sessionens autentiseringsuppgifter. Detta används vanligtvis av moduler i kernelläge som måste agera för en inloggad användares räkning.

Ett paket kan anropa funktionen i pGetKeyFn som tillhandahålls av RPC-körningstransporten. Om transporten inte stöder begreppet återanrop för att hämta autentiseringsuppgifter måste den här parametern vara NULL.

För anropare i kernelläge måste följande skillnader noteras:

De två strängparametrarna måste vara Unicode-strängar .
Buffertvärdena måste allokeras i process virtuellt minne, inte från poolen.

När du är klar med de returnerade autentiseringsuppgifterna frigör du det minne som används av autentiseringsuppgifterna genom att anropa funktionen FreeCredentialsHandle .

Krav

Krav	Värde
Lägsta klient som stöds	Windows XP [endast skrivbordsappar]
Lägsta server som stöds	Windows Server 2003 [endast skrivbordsappar]
Header	Sspi.h (inkludera Security.h)
Bibliotek	Secur32.lib
DLL	Secur32.dll
Unicode- och ANSI-namn	AcquireCredentialsHandleW (Unicode) och AcquireCredentialsHandleA (ANSI)

Se även

SSPI Functions
AcceptSecurityContext (allmänt)
InitializeSecurityContext (Allmänt)
FreeCredentialsHandle