InitializeSecurityContext (Negotiate), funkcja

Funkcja InitializeSecurityContext (Negotiate) 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 (Negotiate) 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 (Negotiate). Wygenerowany token powinien być traktowany jako nieprzezroczystym przez wszystkie osoby wywołujące.

Zazwyczaj funkcja InitializeSecurityContext (Negotiate) 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_        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 (Negotiate). Ten uchwyt służy do tworzenia kontekstu zabezpieczeń. Funkcja InitializeSecurityContext (Negotiate) wymaga co najmniej poświadczeń OUTBOUND.

phContext

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

pszNazwa_docelowa[in, optional]

Wskaźnik do ciągu zakończonego wartością null, który wskazuje nazwę główną usługi (SPN) lub kontekst zabezpieczeń serwera docelowego.

Aplikacje muszą podać prawidłową nazwę SPN, aby ułatwić eliminowanie ataków powtarzania.

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.

[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 (Negotiate) 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.

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.

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 (Negotiate) 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 (Negotiate).
4. AcceptSecurityContext (Negotiate) może zwrócić token, który serwer wysyła do klienta na drugie wywołanie metody InitializeSecurityContext (Negotiate), 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 (Negotiate) 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 elementu InitializeSecurityContext (Negotiate). 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 (Negotiate) i nie jest oczekiwana żadna odpowiedź 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 metody InitializeSecurityContext (Negotiate). 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 (Negotiate) 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 (Negotiate). 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.

Wymagania

Zobacz też

funkcji SSPI

AcceptSecurityContext (negocjować)

AcquireCredentialsHandle (Negocjuj)

CompleteAuthToken (Kompletny AuthToken)

DeleteSecurityContext

FreeContextBuffer (bufor FreeContextBuffer)

Bufor SecBuffer (bufor sekcyjny)

SecBufferDesc