Uwaga
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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 NULL
wartość .
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_NAME
wartość .
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_NAME
wartość .
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 NULL
wartość .
pAuthData[in, optional]
Wskaźnik do danych specyficznych dla pakietu. Ten parametr może mieć NULL
wartość , 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 NULL
wartość .
pvGetKeyArgument[in, optional]
Ten parametr nie jest używany i powinien być ustawiony na NULL
wartość .
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_OK
wartość .
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)