InitializeSecurityContext (Ogólne) — funkcja

Funkcja InitializeSecurityContext (Ogólne) inicjuje po stronie klienta kontekst zabezpieczeń wychodzących z dojścia poświadczeń. Funkcja służy do tworzenia kontekstu zabezpieczeń między aplikacją kliencką a zdalnym elementem równorzędnym. InitializeSecurityContext (Ogólne) zwraca token, który klient musi przekazać do zdalnego elementu równorzędnego, który element równorzędny z kolei przesyła do lokalnej implementacji zabezpieczeń za pośrednictwem wywołania AcceptSecurityContext (Ogólne). Wygenerowany token powinien być traktowany jako nieprzezroczystym przez wszystkie osoby wywołujące.

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

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 InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parametry

phCredential (poświadczenie)[in, optional]

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

phContext

Wskaźnik do struktury CtxtHandle. W pierwszym wywołaniu metody InitializeSecurityContext (Ogólne) 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.

Ten parametr jest opcjonalny za pomocą dostawcy usług udostępnionych Microsoft Digest i można go ustawić na NULLwartość .

W przypadku korzystania z dostawcy SSP Schannel w pierwszym wywołaniu metody InitializeSecurityContext (Ogólne)określ wartość NULL. W przyszłych wywołaniach określ token odebrany w parametrze phNewContext po pierwszym wywołaniu tej funkcji.

pNazwa_celu[in, optional]

Wskaźnik do ciągu zakończonego wartością null, który wskazuje element docelowy kontekstu. Zawartość ciągu jest specyficzna dla pakietu zabezpieczeń , zgodnie z opisem w poniższej tabeli. Ta lista nie jest wyczerpująca. Do systemu można dodać dodatkowe dostawcy SSP systemu i dostawcy SSP innych firm.

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.

Żą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]

Ten parametr jest zarezerwowany i 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.

Ten parametr nie jest używany z skrótem ani Schannel. Ustaw ją na zero.

[in, 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.

Zarezerwowane 2[in]

Ten parametr jest zarezerwowany i musi być ustawiony na zero.

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

Wskaźnik do struktury CtxtHandle. Przy pierwszym wywołaniu metody InitializeSecurityContext (Ogólne) 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.

[in, out, optional] pOutput

Wskaźnik do struktury SecBufferDesc , która 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.

W przypadku korzystania z dostawcy usług udostępnionych Microsoft Digest ten parametr odbiera odpowiedź na żądanie, która musi zostać wysłana na serwer.

W przypadku korzystania z dostawcy SSP Schannel, jeśli określono flagę ISC_REQ_ALLOCATE_MEMORY, dostawca SSP Schannel przydzieli pamięć dla buforu i umieści odpowiednie informacje w secBufferDesc. Ponadto obiekt wywołujący musi przekazać bufor typu SECBUFFER_ALERT. Po wygenerowaniu alertu ten bufor zawiera informacje o tym alercie, a funkcja kończy się niepowodzeniem.

pfContextAttr[out]

Wskaźnik do zmiennej w celu odbierania zestawu flag bitowych wskazujących 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.

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.

Nie ma czasu wygaśnięcia dla kontekstów zabezpieczeń dostawcy Zabezpieczeńmicrosoft Digest lub poświadczeń.

Wartość zwracana

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

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

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 .

Funkcja InitializeSecurityContext (Ogólne) jest używana przez klienta do inicjowania kontekstu wychodzącego.

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 (Ogólne).
4. AcceptSecurityContext (Ogólne) może zwrócić token, który serwer wysyła do klienta na drugie wywołanie metody InitializeSecurityContext (Ogólne), jeśli pierwsze wywołanie zwróciło SEC_I_CONTINUE_NEEDED.

W przypadku kontekstów zabezpieczeńz wieloma elementami, takich jak wzajemne uwierzytelnianie, sekwencja wywołująca jest następująca:

1. Klient wywołuje funkcję zgodnie z wcześniejszym opisem, ale pakiet zwraca kod powodzenia SEC_I_CONTINUE_NEEDED.
2. Klient wysyła token wyjściowy do serwera i czeka na odpowiedź serwera.
3. Po otrzymaniu odpowiedzi serwera klient ponownie wywołuje metodę InitializeSecurityContext (Ogólne) z parametrem phContext ustawionym na uchwyt zwrócony z ostatniego wywołania. Token otrzymany z serwera jest dostarczany w parametrze pInput .
4. Nie używaj wartości phContext w wywołaniach współbieżnych do parametru InitializeSecurityContext (Ogólne). Implementacja dostawców zabezpieczeń nie jest bezpieczna wątkowo.

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.

Aby zainicjować kontekst zabezpieczeń, może być wymagane więcej niż jedno wywołanie 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. Parametr pfContextAttributes jest prawidłowy w przypadku dowolnego pomyślnego powrotu, ale tylko w przypadku końcowego pomyślnego powrotu należy zbadać flagi odnoszące się do aspektów zabezpieczeń kontekstu. 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 . Nie jest to ogólne rozwiązanie, ale 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 (ogólne) i nie ma oczekiwanej odpowiedzi z serwera. Jeśli kod zwracany jest SEC_I_CONTINUE_NEEDED, klient oczekuje tokenu w odpowiedzi z serwera i przekazuje go w drugim wywołaniu metody InitializeSecurityContext (Ogólne). Kod zwrotny SEC_I_COMPLETE_NEEDED wskazuje, że klient musi zakończyć tworzenie komunikatu i wywołać funkcję CompleteAuthToken . Kod SEC_I_COMPLETE_AND_CONTINUE zawiera obie te akcje.

Jeśli funkcja InitializeSecurityContext (Ogólne) 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óźniejszej części wymiany uwierzytelniania.

Po pomyślnym zakończeniu klient może ponownie wywołać metodę InitializeSecurityContext (Ogólne). Oznacza to pakiet zabezpieczeń , że jest poszukiwana ponowna autoryzacja.

Wywołujące tryb jądra mają następujące różnice: nazwa docelowa jest ciągiem Unicode , który należy przydzielić 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 zwraca SEC_I_INCOMPLETE_CREDENTIALS przy użyciu dostawcy SSP Schannel, sprawdź, czy określono prawidłowy i zaufany certyfikat w poświadczeniach. Certyfikat jest określony podczas wywoływania funkcji AcquireCredentialsHandle (Ogólne). 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 (Ogólne) i określ atrybut SECPKG_ATTR_ISSUER_LIST_EX.

W przypadku korzystania z dostawcy usług udostępnionych Schannel po odebraniu certyfikatu uwierzytelniania z urzędu certyfikacji zaufanego przez serwer aplikacja tworzy nowe poświadczenia, wywołując funkcję AcquireCredentialsHandle (Ogólne), a następnie ponownie wywołując funkcję InitializeSecurityContext (Ogólne), określając nowe poświadczenie w parametrze phCredential .

Wymagania

Zobacz też

funkcji SSPI

Obsługa rozszerzonej ochrony uwierzytelniania (EPA) w usłudze

AcceptSecurityContext (ogólne)

AcquireCredentialsHandle (ogólne)

CompleteAuthToken (Kompletny AuthToken)

DeleteSecurityContext

FreeContextBuffer (bufor FreeContextBuffer)

Bufor SecBuffer (bufor sekcyjny)

SecBufferDesc