InitializeSecurityContext (CredSSP) , funkcja

Funkcja InitializeSecurityContext (CredSSP) inicjuje po stronie klienta kontekst zabezpieczeń wychodzący z dojścia poświadczeń. Funkcja tworzy kontekst zabezpieczeń między aplikacją kliencką a zdalnym elementem równorzędnym. InitializeSecurityContext (CredSSP) zwraca token, który klient musi przekazać do zdalnego elementu równorzędnego; Element równorzędny z kolei przesyła ten token do lokalnej implementacji zabezpieczeń za pomocą wywołania AcceptSecurityContext (CredSSP). Wygenerowany token powinien być traktowany jako nieprzezroczystym przez wszystkie osoby wywołujące.

Zazwyczaj funkcja InitializeSecurityContext (CredSSP) jest wywoływana w pętli do momentu ustanowienia wystarczającego kontekstu zabezpieczeń.

Składnia

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parametry

phCredential (poświadczenie)[in, optional]

Dojście do poświadczeń zwróconych przez AcquireCredentialsHandle (CredSSP). Ten uchwyt służy do tworzenia kontekstu zabezpieczeń. Funkcja InitializeSecurityContext (CredSSP) wymaga co najmniej poświadczeń OUTBOUND.

phContext

Wskaźnik do struktury CtxtHandle. W pierwszym wywołaniu metody InitializeSecurityContext (CredSSP) ten wskaźnik to NULL. W drugim wywołaniu ten parametr jest wskaźnikiem do dojścia do częściowo sformułowanego kontekstu zwróconego w parametrze phNewContext przez pierwsze wywołanie.

W pierwszym wywołaniu metody InitializeSecurityContext (CredSSP) określ wartość NULL. W przyszłych wywołaniach określ token odebrany w parametrze phNewContext po pierwszym wywołaniu tej funkcji.

Ostrzeżenie

Nie używaj tego samego uchwytu kontekstu w wywołaniach współbieżnych do elementu InitializeSecurityContext (CredSSP). Implementacja interfejsu API u dostawców usług zabezpieczeń nie jest bezpieczna wątkowo.

pNazwa_celu[in, optional]

Wskaźnik do ciągu zakończonego wartością null, który jednoznacznie identyfikuje serwer docelowy. Usługa Schannel używa tej wartości do zweryfikowania certyfikatu serwera. Usługa Schannel używa również tej wartości do lokalizowania sesji w pamięci podręcznej sesji podczas ponownego publikowania połączenia. Buforowana sesja jest używana tylko wtedy, gdy spełnione są wszystkie następujące warunki:

• Nazwa docelowa jest taka sama.
• Wpis pamięci podręcznej nie wygasł.
• Proces aplikacji, który wywołuje funkcję, jest taki sam.
• Sesja logowania jest taka sama.
• Dojście poświadczeń jest takie samo.

fContextReq (Żądanie fContextReq)[in]

Flagi bitowe wskazujące żądania kontekstu. Nie wszystkie pakiety mogą obsługiwać wszystkie wymagania. Flagi używane dla tego parametru są poprzedzone ISC_REQ_, na przykład ISC_REQ_DELEGATE.

Ten parametr może być co najmniej jedną z następujących flag atrybutów.

Wartość	Znaczenie
ISC_REQ_ALLOCATE_MEMORY 0x100	Pakiet zabezpieczeń przydziela wyjściowe dla elementu wywołującego. Po zakończeniu korzystania z wyjściowych zwolnij je, wywołując funkcję FreeContextBuffer.
ISC_REQ_CONNECTION 0x800	Kontekst zabezpieczeń nie obsługuje formatowania komunikatów.
ISC_REQ_EXTENDED_ERROR 0x4000	Gdy wystąpią błędy, strona zdalna zostanie powiadomiona.
ISC_REQ_MANUAL_CRED_VALIDATION 0x80000	Dostawca obsługi zabezpieczeń poświadczeń (CredSSP) nie może automatycznie uwierzytelniać serwera. Ta flaga jest zawsze ustawiana podczas korzystania z protokołu CredSSP.
ISC_REQ_SEQUENCE_DETECT 0x8	Wykrywanie komunikatów odebranych z sekwencji.
ISC_REQ_STREAM 0x8000	Obsługa połączenia zorientowanego na strumień.
ISC_REQ_USE_SUPPLIED_CREDS 0x80	Dostawca CredSSP nie może automatycznie podawać poświadczeń dla klienta.
ISC_REQ_DELEGATE 0x1	Wskazuje, że poświadczenia użytkownika mają być delegowane do serwera. Jeśli ta flaga nie zostanie określona, pusty zestaw poświadczeń zostanie delegowany do serwera. Windows Server 2008 i Windows Vista: Ta flaga jest wymagana.
ISC_REQ_MUTUAL_AUTH 0x2	Wskazuje, że uwierzytelnianie serwera nie jest wymagane. Zasady delegowania są nadal wymuszane, jeśli ta flaga nie jest określona. Windows Server 2008 i Windows Vista: Ta flaga jest ignorowana.

Żądane atrybuty mogą nie być obsługiwane przez klienta. Aby uzyskać więcej informacji, zobacz parametr pfContextAttr.

Aby uzyskać dalsze opisy różnych atrybutów, zobacz Wymagania kontekstowe.

Zarezerwowane 1[in]

Zastrzeżony. Ten parametr musi być ustawiony na zero.

TargetDataRep (Przedstawiciel docelowy)[in]

Reprezentacja danych, taka jak kolejność bajtów, w obiekcie docelowym. Ten parametr może być SECURITY_NATIVE_DREP lub SECURITY_NETWORK_DREP.

[in, out, optional] pInput

Wskaźnik do struktury SecBufferDesc , która zawiera wskaźniki do dostarczonych jako dane wejściowe do pakietu. Jeśli kontekst klienta nie został zainicjowany przez serwer, wartość tego parametru musi znajdować NULL się w pierwszym wywołaniu funkcji. Po kolejnych wywołaniach funkcji lub po zainicjowaniu kontekstu klienta przez serwer wartość tego parametru jest wskaźnikiem do buforu przydzielonego z wystarczającą ilością pamięci do przechowywania tokenu zwróconego przez komputer zdalny.

W przypadku wywołań tej funkcji po początkowym wywołaniu muszą istnieć dwa. Pierwszy ma typ SECBUFFER_TOKEN i zawiera token otrzymany z serwera. Drugi bufor ma typ SECBUFFER_EMPTY; ustawić zarówno pvBuffer , jak i cbBuffer członków na zero.

Zarezerwowane 2[in]

Zastrzeżony. Ten parametr musi być ustawiony na zero.

phNewContext (Kontekst Nowy)[in, out, optional]

Wskaźnik do struktury CtxtHandle. Przy pierwszym wywołaniu metody InitializeSecurityContext (CredSSP) ten wskaźnik otrzymuje nowy uchwyt kontekstu. W drugim wywołaniu frazaNewContext może być taka sama jak uchwyt określony w parametrze phContext . phNewContext nigdy nie powinna być NULL.

[out, optional] pOutput

Wskaźnik do struktury SecBufferDesc . Ta struktura z kolei zawiera wskaźniki do struktury SecBuffer , która odbiera dane wyjściowe. Jeśli bufor został wpisany jako SEC_READWRITE w danych wejściowych, będzie on dostępny w danych wyjściowych. System przydzieli bufor dla tokenu zabezpieczającego, jeśli jest to wymagane (za pośrednictwem ISC_REQ_ALLOCATE_MEMORY) i wypełni adres w deskryptorze buforu dla tokenu zabezpieczającego.

Jeśli określono flagę ISC_REQ_ALLOCATE_MEMORY , credSSP przydzieli pamięć dla buforu i umieści odpowiednie informacje w secBufferDesc.

pfContextAttr[out]

Wskaźnik do zestawu flag bitowych, które wskazują atrybuty ustalonego kontekstu. Aby uzyskać opis różnych atrybutów, zobacz Wymagania dotyczące kontekstu.

Flagi używane dla tego parametru są poprzedzone ISC_RET, takimi jak ISC_RET_DELEGATE. Aby uzyskać listę prawidłowych wartości, zobacz parametr fContextReq .

Nie sprawdzaj atrybutów związanych z zabezpieczeniami, dopóki ostateczne wywołanie funkcji nie zostanie pomyślnie zwrócone. Flagi atrybutów, które nie są związane z zabezpieczeniami, takie jak flaga ASC_RET_ALLOCATED_MEMORY , można sprawdzić przed ostatecznym zwróceniem.

Uwaga

Określone atrybuty kontekstu mogą ulec zmianie podczas negocjacji z zdalnym elementem równorzędnym.

ptsWygaśnięcie[out, optional]

Wskaźnik do struktury sygnatury czasowej, która odbiera czas wygaśnięcia kontekstu. Zaleca się, aby pakiet zabezpieczeń zawsze zwracał tę wartość w czasie lokalnym. Ten parametr jest opcjonalny i NULL powinien zostać przekazany dla krótkoterminowych klientów.

Wartość zwracana

Jeśli funkcja powiedzie się, zwraca jeden z następujących kodów powodzenia.

Kod powrotny	Opis
SEC_E_INCOMPLETE_MESSAGE	Dane dla całego komunikatu nie zostały odczytane z przewodu. Gdy ta wartość zostanie zwrócona, bufor pInput zawiera strukturę SecBuffer z elementem członkowskim BufferTypeSECBUFFER_MISSING. Element członkowski cbBuffersecBuffer określa liczbę dodatkowych bajtów, które funkcja musi odczytać z klienta, zanim ta funkcja zakończy się pomyślnie. Chociaż ta liczba nie zawsze jest dokładna, użycie jej może pomóc zwiększyć wydajność, unikając wielu wywołań tej funkcji.
SEC_E_OK	Kontekst zabezpieczeń został pomyślnie zainicjowany. Nie ma potrzeby innego wywołania InitializeSecurityContext (CredSSP). Jeśli funkcja zwraca token wyjściowy — oznacza to, że jeśli SECBUFFER_TOKEN w pOutput ma długość inną niżzerowa — token musi zostać wysłany do serwera.
SEC_I_COMPLETE_AND_CONTINUE	Klient musi wywołać metodę CompleteAuthToken , a następnie przekazać dane wyjściowe do serwera. Następnie klient czeka na zwrócony token i przekazuje go w innym wywołaniu do metody InitializeSecurityContext (CredSSP).
SEC_I_COMPLETE_NEEDED	Klient musi zakończyć tworzenie komunikatu, a następnie wywołać funkcję CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	Klient musi wysłać token wyjściowy do serwera i poczekać na token powrotny. Klient przekazuje zwrócony token w innym wywołaniu metody InitializeSecurityContext (CredSSP). Token wyjściowy może być pusty.
SEC_I_INCOMPLETE_CREDENTIALS	Serwer zażądał uwierzytelniania klienta, ale podane poświadczenia nie zawierają certyfikatu lub certyfikat nie został wystawiony przez urząd certyfikacji, któremu ufa serwer. Aby uzyskać więcej informacji zobacz uwagi.

Jeśli funkcja zakończy się niepowodzeniem, funkcja zwróci 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_INVALID_HANDLE	Dojście przekazane do funkcji jest nieprawidłowe.
SEC_E_INVALID_TOKEN	Token wejściowy jest źle sformułowany. Możliwe przyczyny obejmują token uszkodzony podczas przesyłania, token nieprawidłowego rozmiaru i token przekazany do nieprawidłowego pakietu zabezpieczeń. Ten ostatni warunek może wystąpić, jeśli klient i serwer nie wynegocjowali odpowiedniego pakietu zabezpieczeń.
SEC_E_LOGON_DENIED	Logowanie nie powiodło się.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Nie można skontaktować się z urzędem w celu uwierzytelnienia. Nazwa domeny uwierzytelniania strony może być nieprawidłowa, domena może być nieosiągalna lub wystąpił błąd relacji zaufania.
SEC_E_NO_CREDENTIALS	W pakiecie zabezpieczeń nie są dostępne żadne poświadczenia.
SEC_E_TARGET_UNKNOWN	Obiekt docelowy nie został rozpoznany.
SEC_E_UNSUPPORTED_FUNCTION	Wartość parametru fContextReq jest nieprawidłowa. Nie określono wymaganej flagi lub określono flagę, która nie jest obsługiwana przez dostawcę CredSSP.
SEC_E_WRONG_PRINCIPAL	Podmiot zabezpieczeń, który odebrał żądanie uwierzytelniania, nie jest taki sam jak podmiot przekazany do parametru pszTargetName . Ten błąd wskazuje błąd w wzajemnym uwierzytelnianiu.
SEC_E_DELEGATION_POLICY	Zasady nie obsługują delegowania poświadczeń do serwera docelowego.
SEC_E_POLICY_NLTM_ONLY	Delegowanie poświadczeń do serwera docelowego nie jest dozwolone, gdy nie zostanie osiągnięte wzajemne uwierzytelnianie.
SEC_E_MUTUAL_AUTH_FAILED	Uwierzytelnianie serwera nie powiodło się, gdy flaga ISC_REQ_MUTUAL_AUTH jest określona w parametrze fContextReq .

Uwagi

Obiekt wywołujący jest odpowiedzialny za określenie, czy ostateczne atrybuty kontekstu są wystarczające. Jeśli na przykład zażądano poufności, ale nie można jej ustanowić, niektóre aplikacje mogą zdecydować się na natychmiastowe zamknięcie połączenia.

Jeśli atrybuty kontekstu zabezpieczeń nie są wystarczające, klient musi zwolnić częściowo utworzony kontekst, wywołując funkcję DeleteSecurityContext .

Klient wywołuje funkcję InitializeSecurityContext (CredSSP), aby zainicjować kontekst wychodzący.

W przypadku kontekstu zabezpieczeń z dwoma elementami sekwencja wywołująca jest następująca:

1. Klient wywołuje funkcję z frazą phContext ustawioną na NULL i wypełnia deskryptor buforu komunikatem wejściowym.
2. Pakiet zabezpieczeń sprawdza parametry i konstruuje nieprzezroczystym tokenem, umieszczając go w elemecie TOKEN w tablicy. Jeśli parametr fContextReq zawiera flagę ISC_REQ_ALLOCATE_MEMORY , pakiet zabezpieczeń przydziela pamięć i zwraca wskaźnik w elemecie TOKEN.
3. Klient wysyła token zwrócony w buforze pOutput do serwera docelowego. Następnie serwer przekazuje token jako argument wejściowy w wywołaniu funkcji AcceptSecurityContext (CredSSP).
4. Metoda AcceptSecurityContext (CredSSP) może zwrócić token. Serwer wysyła ten token do klienta za pośrednictwem drugiego wywołania InitializeSecurityContext (CredSSP), jeśli pierwsze wywołanie zwróciło SEC_I_CONTINUE_NEEDED.

Jeśli serwer pomyślnie odpowiedział, pakiet zabezpieczeń zwraca SEC_E_OK i zostanie ustanowiona bezpieczna sesja.

Jeśli funkcja zwróci jedną z odpowiedzi na błędy, odpowiedź serwera nie zostanie zaakceptowana i sesja nie zostanie ustanowiona.

Jeśli funkcja zwraca SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED lub SEC_I_COMPLETE_AND_CONTINUE, kroki 2 i 3 są powtarzane.

Inicjowanie kontekstu zabezpieczeń może wymagać więcej niż jednego wywołania tej funkcji, w zależności od podstawowego mechanizmu uwierzytelniania, a także opcji określonych w parametrze fContextReq .

Parametry fContextReq i pfContextAttributes to maski bitów reprezentujące różne atrybuty kontekstu. Aby uzyskać opis różnych atrybutów, zobacz Wymagania dotyczące kontekstu. Chociaż parametr pfContextAttributes jest prawidłowy w przypadku dowolnego pomyślnego powrotu, należy sprawdzić flagi odnoszące się do aspektów zabezpieczeń kontekstu tylko w przypadku końcowego pomyślnego powrotu. Zwroty pośrednie mogą na przykład ustawić flagę ISC_RET_ALLOCATED_MEMORY .

Jeśli ustawiono flagę ISC_REQ_USE_SUPPLIED_CREDS , pakiet zabezpieczeń musi wyszukać typ buforu SECBUFFER_PKG_PARAMS w buforze wejściowym pInput . Chociaż nie jest to ogólne rozwiązanie, umożliwia silne parowanie pakietu zabezpieczeń i aplikacji, jeśli jest to konieczne.

Jeśli określono ISC_REQ_ALLOCATE_MEMORY , obiekt wywołujący musi zwolnić pamięć przez wywołanie funkcji FreeContextBuffer .

Na przykład token wejściowy może być wyzwaniem z poziomu programu LAN Manager. W takim przypadku token wyjściowy będzie odpowiedzią szyfrowaną NTLM na wyzwanie.

Akcja wykonywana przez klienta zależy od kodu zwrotnego z tej funkcji. Jeśli kod zwracany jest SEC_E_OK, nie będzie drugiego wywołania InitializeSecurityContext (CredSSP) i nie ma oczekiwanej odpowiedzi z serwera. Jeśli kod powrotny jest SEC_I_CONTINUE_NEEDED, klient oczekuje tokenu w odpowiedzi z serwera i przekazuje go w drugim wywołaniu do InitializeSecurityContext (CredSSP). Kod zwrotny SEC_I_COMPLETE_NEEDED wskazuje, że klient musi zakończyć kompilowanie komunikatu i wywołać funkcję CompleteAuthToken . Kod SEC_I_COMPLETE_AND_CONTINUE zawiera obie te akcje.

Jeśli funkcja InitializeSecurityContext (CredSSP) zwróci powodzenie w pierwszym wywołaniu (lub tylko), obiekt wywołujący musi ostatecznie wywołać funkcję DeleteSecurityContext w zwróconym dojściu, nawet jeśli wywołanie zakończy się niepowodzeniem w późniejszym etapie wymiany uwierzytelniania.

Klient może ponownie wywołać metodę InitializeSecurityContext (CredSSP) po pomyślnym zakończeniu. Oznacza to pakiet zabezpieczeń, że jest poszukiwana ponowna autoryzacja.

Wywołania trybu jądra mają następujące różnice: nazwa docelowa jest ciągiem Unicode , który musi zostać przydzielony w pamięci wirtualnej przy użyciu elementu VirtualAlloc; nie może być przydzielona z puli. przekazywane i dostarczane w pInput i pOutput muszą znajdować się w pamięci wirtualnej, a nie w puli.

Jeśli funkcja zwróci SEC_I_INCOMPLETE_CREDENTIALS, sprawdź, czy poświadczenia języka r przekazane do funkcji AcquireCredentialsHandle (CredSSP) określiły prawidłowy i zaufany certyfikat Certyfikat musi być certyfikatem uwierzytelniania klienta wystawionym przez urząd certyfikacji zaufany przez serwer. Aby uzyskać listę urzędów certyfikacji zaufanych przez serwer, wywołaj funkcję QueryContextAttributes (CredSSP) z atrybutem SECPKG_ATTR_ISSUER_LIST_EX .

Po otrzymaniu certyfikatu uwierzytelniania z urzędu certyfikacji, któremu ufa serwer, aplikacja kliencka tworzy nowe poświadczenie. W tym celu wywołuje funkcję AcquireCredentialsHandle (CredSSP), a następnie ponownie wywołuje metodę InitializeSecurityContext (CredSSP), określając nowe poświadczenie w parametrze phCredential .

Wymagania

Wymaganie	Wartość
Minimalny obsługiwany klient	Windows Vista [tylko aplikacje klasyczne]
Minimalny obsługiwany serwer	Windows Server 2008 [tylko aplikacje klasyczne]
Nagłówek	Sspi.h (w tym Security.h)
Biblioteka	Secur32.lib powiedział:
DLL	Secur32.dll

Zobacz też

funkcji SSPI

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken (Kompletny AuthToken)

DeleteSecurityContext

FreeContextBuffer (bufor FreeContextBuffer)

Bufor SecBuffer (bufor sekcyjny)

SecBufferDesc