Udostępnij za pośrednictwem


AcquireCredentialsHandle (Schannel) , funkcja

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

Uwaga

Nie jest to "logowanie do sieci" i nie oznacza zbierania poświadczeń.

Składnia

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

Parametry

pszPrincipal[in, optional]

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 SSP Schannel ten parametr nie jest używany i powinien być ustawiony na NULLwartość .

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 (Schannel) mogą być wywoływane z parametrem ulAttribute ustawionym na SECPKG_ATTR_PACKAGE_INFO , aby zwrócić informacje dotyczące używanego pakietu zabezpieczeń .

W przypadku korzystania z dostawcy SSP Schannel ustaw ten parametr na UNISP_NAMEwartość .

Uwaga

Wywołujące tryb jądra, które napotykają problemy podczas wywoływania metody InitializeSecurityContext (Schannel) po wywołaniu metody AcquireCredentialsHandle (Schannel), mogą również ustawić wartość pszPackage na SCHANNEL_NAMEwartość .

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 (Schannel) lub AcceptSecurityContext (Schannel). 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, optional]

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 mieć wartość NULL.

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

pAuthData[in, optional]

Wskaźnik do danych specyficznych dla pakietu. Ten parametr może mieć NULLwartość , 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 SSP Schannel określ strukturę SCH_CREDENTIALS , która wskazuje protokół do użycia i ustawienia dla różnych funkcji kanału, które można dostosować.

pGetKeyFn[in, optional]

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

pvGetKeyArgument[in, optional]

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

phCredential[out]

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

ptsExpiry[out, optional]

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.

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_OKwartość .

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

Kod powrotny Opis
SEC_E_INSUFFICIENT_MEMORY Za mało pamięci, aby ukończyć żądaną akcję.
SEC_E_INTERNAL_ERROR Wystąpił błąd, który nie został zamapowyny na kod błędu interfejsu SSPI.
SEC_E_NO_CREDENTIALS W ograniczonej delegowaniu nie są dostępne żadne poświadczenia.
SEC_E_NOT_OWNER Obiekt wywołujący funkcji nie ma niezbędnych poświadczeń.
SEC_E_SECPKG_NOT_FOUND Żądany pakiet zabezpieczeń nie istnieje.
SEC_E_UNKNOWN_CREDENTIALS Poświadczenia dostarczone do pakietu nie zostały rozpoznane.

Uwagi

Funkcja AcquireCredentialsHandle (Schannel) 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 (Schannel) i InitializeSecurityContext (Schannel).

Ogólnie rzecz biorąc, AcquireCredentialsHandle (Schannel) 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 uprawnieniamiSE_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

Wymaganie Wartość
Minimalny obsługiwany klient Windows XP [tylko aplikacje klasyczne]
Minimalny obsługiwany serwer Windows Server 2003 [tylko aplikacje klasyczne]
Nagłówek Sspi.h (include Security.h)
Biblioteka Secur32.lib
DLL Secur32.dll
Nazwy Unicode i ANSI AcquireCredentialsHandleW (Unicode) i AcquireCredentialsHandleA (ANSI)

Zobacz też

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

funkcji SSPI