AcquireCredentialsHandle (Digest), funkcja

Funkcja AcquireCredentialsHandle (Digest) uzyskuje dojście do istniejących poświadczeń podmiotu zabezpieczeń. Ta obsługa jest wymagana przez funkcje AcceptSecurityContext (Digest) i InitializeSecurityContext (Digest). 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.

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.

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 (Szyfrowane) 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.

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_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 (Skrót) lub AcceptSecurityContext (Skrót). 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.

 

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.

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

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.

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 (Digest) 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 (Digest) i InitializeSecurityContext (Digest).

Ogólnie rzecz biorąc, funkcja AcquireCredentialsHandle (Skrót) nie zezwala na uzyskanie 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 (skrót)

InitializeSecurityContext (Skrót)

FreeCredentialsHandle