AcquireCredentialsHandle (General), funkcja

Funkcja AcquireCredentialsHandle (Ogólne) uzyskuje dojście do istniejących poświadczeń podmiotu zabezpieczeń. Ta obsługa jest wymagana przez funkcje InitializeSecurityContext (Ogólne) i AcceptSecurityContext (Ogólne). Mogą to być wstępnie istniejące poświadczenia, które są ustanawiane za pośrednictwem logowania systemu, który nie został opisany w tym miejscu, lub obiekt wywołujący może podać alternatywne poświadczenia.

Aby uzyskać informacje o korzystaniu z tej funkcji z określonym dostawcą obsługi zabezpieczeń (SSP), zobacz następujące tematy.

Składnia

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

Parametry

pszPrincipal [in]

Wskaźnik do ciągu zakończonego wartością null, który określa nazwę podmiotu zabezpieczeń, którego poświadczenia będą się odwoływać.

W przypadku korzystania z dostawcy usług udostępnionych skrótów ten parametr jest opcjonalny.

W przypadku korzystania z dostawcy SSP Schannel ten parametr nie jest używany i powinien być ustawiony na wartość NULL.

Uwaga

Jeśli proces, który żąda dojścia, nie ma dostępu do poświadczeń, funkcja zwróci błąd. Ciąg o wartości null wskazuje, że proces wymaga dojścia do poświadczeń użytkownika, w którym jest wykonywany kontekst zabezpieczeń .

 

pszPackage [in]

Wskaźnik do ciągu zakończonego wartością null, który określa nazwę pakietu zabezpieczeń , za pomocą którego będą używane te poświadczenia. Jest to nazwa pakietu zabezpieczeń zwrócona w elemencie Name struktury SecPkgInfo zwróconej przez funkcję EnumerateSecurityPackages . Po ustanowieniu kontekstu atrybuty QueryContextAttributes (Ogólne) mogą być wywoływane z parametrem ulAttribute ustawionym na SECPKG_ATTR_PACKAGE_INFO w celu zwrócenia informacji o używanym pakiecie zabezpieczeń .

W przypadku korzystania z dostawcy SSP skrótu ustaw ten parametr na WDIGEST_SP_NAME.

W przypadku korzystania z dostawcy SSP Schannel ustaw ten parametr na UNISP_NAME.

fCredentialUse [in]

Flaga wskazująca sposób użycia tych poświadczeń. Ten parametr może być jedną z następujących wartości.

Wartość	Znaczenie
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	Zabezpieczenia nie używają domyślnych poświadczeń logowania ani poświadczeń z Menedżera poświadczeń. Ta wartość jest obsługiwana tylko przez delegowanie ograniczone negocjowania. Windows Server 2008, Windows Vista, Windows Server 2003 i Windows XP: Ta wartość nie jest obsługiwana.
SECPKG_CRED_BOTH	Zweryfikuj poświadczenia przychodzące lub użyj poświadczeń lokalnych, aby przygotować token wychodzący. Ta flaga włącza obie inne flagi. Ta flaga jest nieprawidłowa z dostawcami SSPs skrótu i Schannel.
SECPKG_CRED_INBOUND	Zweryfikuj poświadczenia serwera przychodzącego. Poświadczenia przychodzące mogą być weryfikowane przy użyciu urzędu uwierzytelniania, gdy wywoływana jest funkcja InitializeSecurityContext (Ogólne) lub AcceptSecurityContext (Ogólne). Jeśli taki urząd jest niedostępny, funkcja zakończy się niepowodzeniem i zwróci SEC_E_NO_AUTHENTICATING_AUTHORITY. Walidacja jest specyficzna dla pakietu.
SECPKG_CRED_OUTBOUND	Zezwalaj lokalnemu poświadczenie klienta na przygotowanie tokenu wychodzącego.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	Funkcja przetwarza zasady serwera i zwraca SEC_E_NO_CREDENTIALS wskazującą, że aplikacja powinna monitować o poświadczenia. Ta wartość jest obsługiwana tylko przez delegowanie ograniczone negocjowania. Windows Server 2008, Windows Vista, Windows Server 2003 i Windows XP: Ta wartość nie jest obsługiwana.

 

pvLogonID [in]

Wskaźnik do lokalnego unikatowego identyfikatora (LUID), który identyfikuje użytkownika. Ten parametr jest udostępniany dla procesów systemu plików, takich jak przekierowania sieciowe. Ten parametr może być null.

W przypadku korzystania z dostawcy SSP Schannel ten parametr nie jest używany i powinien być ustawiony na wartość NULL.

pAuthData [in]

Wskaźnik do danych specyficznych dla pakietu. Ten parametr może mieć wartość NULL, co oznacza, że należy użyć domyślnych poświadczeń dla tego pakietu zabezpieczeń . Aby użyć podanych poświadczeń, przekaż SEC_WINNT_AUTH_IDENTITY strukturę zawierającą te poświadczenia w tym parametrze. Czas wykonywania RPC przechodzi niezależnie od tego, co zostało podane w RpcBindingSetAuthInfo.

W przypadku korzystania z dostawcy usług udostępnionych skrótów ten parametr jest wskaźnikiem do struktury SEC_WINNT_AUTH_IDENTITY zawierającej informacje o uwierzytelnianiu używane do lokalizowania poświadczeń.

W przypadku korzystania z dostawcy SSP Schannel określ strukturę SCHANNEL_CRED , która wskazuje protokół do użycia i ustawienia dla różnych funkcji kanału, które można dostosować.

W przypadku korzystania z pakietów NTLM lub Negotiate maksymalna długość znaków dla nazwy użytkownika, hasła i domeny to odpowiednio 256, 256 i 15.

pGetKeyFn [in]

Ten parametr nie jest używany i powinien być ustawiony na wartość NULL.

pvGetKeyArgument [in]

Ten parametr nie jest używany i powinien być ustawiony na wartość NULL.

phCredential [out]

Wskaźnik do struktury CredHandle w celu odebrania dojścia poświadczeń.

ptsExpiry [out]

Wskaźnik do struktury Sygnatura czasowa , która odbiera czas wygaśnięcia zwróconych poświadczeń. Wartość zwrócona w tej strukturze znacznika czasu zależy od ograniczonego delegowania. Pakiet zabezpieczeń musi zwrócić tę wartość w czasie lokalnym.

Ten parametr jest ustawiony na stały maksymalny czas. Nie ma czasu wygaśnięcia dla poświadczeń lub poświadczeń kontekstu zabezpieczeńskrótu ani w przypadku korzystania z dostawcy SSP skrótu.

W przypadku korzystania z dostawcy SSP Schannel ten parametr jest opcjonalny. Gdy poświadczenie do użycia do uwierzytelniania jest certyfikatem, ten parametr otrzymuje czas wygaśnięcia dla tego certyfikatu. Jeśli certyfikat nie został dostarczony, zwracana jest maksymalna wartość czasu.

Wartość zwracana

Jeśli funkcja powiedzie się, funkcja zwróci SEC_E_OK.

Jeśli funkcja zakończy się niepowodzeniem, zwraca jeden z następujących kodów błędów.

Uwagi

Funkcja AcquireCredentialsHandle (Ogólne) zwraca dojście do poświadczeń podmiotu zabezpieczeń, takiego jak użytkownik lub klient, używane przez określone ograniczone delegowanie. Może to być dojście do istniejących poświadczeń lub funkcja może utworzyć nowy zestaw poświadczeń i zwrócić go. Ten uchwyt może być używany w kolejnych wywołaniach funkcji AcceptSecurityContext (General) i InitializeSecurityContext (Ogólne).

Ogólnie rzecz biorąc, acquireCredentialsHandle (ogólne) nie zezwala na proces uzyskiwania dojścia do poświadczeń innych użytkowników zalogowanych na tym samym komputerze. Jednak obiekt wywołujący z uprawnieniami SE_TCB_NAME ma możliwość określenia identyfikatora logowania (LUID) dowolnego istniejącego tokenu sesji logowania w celu uzyskania dojścia do poświadczeń tej sesji. Zazwyczaj jest to używane przez moduły trybu jądra, które muszą działać w imieniu zalogowanego użytkownika.

Pakiet może wywołać funkcję w pGetKeyFn dostarczonym przez transport czasu wykonywania RPC. Jeśli transport nie obsługuje pojęcia wywołania zwrotnego w celu pobrania poświadczeń, ten parametr musi mieć wartość NULL.

W przypadku wywołań trybu jądra należy zauważyć następujące różnice:

• Dwa parametry ciągu muszą być ciągami Unicode .
• Wartości buforu należy przydzielić w pamięci wirtualnej procesu, a nie z puli.

Po zakończeniu korzystania z zwróconych poświadczeń zwolnij pamięć używaną przez poświadczenia, wywołując funkcję FreeCredentialsHandle .

Wymagania

Zobacz też

funkcji SSPI

AcceptSecurityContext (ogólne)

InitializeSecurityContext (ogólne)

FreeCredentialsHandle