InitializeSecurityContext (Digest), funkcja

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

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

phContext

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

Ostrzeżenie

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

pszNazwa_docelowa[in, optional]

Wskaźnik do ciągu zakończonego wartością null, który jednoznacznie identyfikuje identyfikator URI żądanego zasobu. Ciąg musi składać się z znaków dozwolonych w identyfikatorze URI i musi być reprezentowany przez zestaw kodu US ASCII. Kodowanie percent może służyć do reprezentowania znaków poza zestawem kodu US ASCII.

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	Pakiet zabezpieczeń przydziela wyjściowe. Po zakończeniu korzystania z wyjściowych zwolnij je, wywołując funkcję FreeContextBuffer.
ISC_REQ_CONFIDENTIALITY	Szyfruj komunikaty przy użyciu funkcji EncryptMessage .
ISC_REQ_EXTENDED_ERROR	Gdy wystąpią błędy, strona zdalna zostanie powiadomiona.
ISC_REQ_HTTP	Użyj skrótu dla protokołu HTTP. Pomiń tę flagę, aby użyć skrótu jako mechanizmu SASL.
ISC_REQ_INTEGRITY	Podpisywanie komunikatów i weryfikowanie podpisów przy użyciu funkcji EncryptMessage i MakeSignature .
ISC_REQ_MUTUAL_AUTH	Zasady wzajemnego uwierzytelniania usługi będą spełnione. OSTROŻNOŚĆ: Niekoniecznie oznacza to, że jest wykonywane wzajemne uwierzytelnianie, tylko że zasady uwierzytelniania usługi są spełnione. Aby upewnić się, że jest wykonywane wzajemne uwierzytelnianie, wywołaj funkcję QueryContextAttributes (Digest).
ISC_REQ_REPLAY_DETECT	Wykryj ponownie odtwarzane komunikaty, które zostały zakodowane przy użyciu funkcji EncryptMessage lub MakeSignature .
ISC_REQ_SEQUENCE_DETECT	Wykrywanie komunikatów odebranych z sekwencji.
ISC_REQ_STREAM	Obsługa połączenia zorientowanego na strumień.

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

Ten parametr nie jest używany z skrótem. 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.

Aby uzyskać informacje o konfiguracji buforu, zobacz Input Buffers for the Digest Challenge Response (wejściowe odpowiedzi na żądanie skrótu).

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 (Digest) 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.

Ten parametr odbiera odpowiedź na żądanie, która musi zostać wysłana na serwer.

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.

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.

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.

Kod powrotny	Opis
SEC_E_OK	Kontekst zabezpieczeń został pomyślnie zainicjowany. Nie ma potrzeby innego wywołania InitializeSecurityContext (Digest). Jeśli funkcja zwraca token wyjściowy, oznacza to, że jeśli SECBUFFER_TOKEN w pOutput ma długość inną niżzerowa, ten 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 (Skrót).
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. Zwrócony token jest następnie przekazywany w innym wywołaniu metody InitializeSecurityContext (Digest). Token wyjściowy może być pusty.
SEC_I_INCOMPLETE_CREDENTIALS	Użyj z usługą Schannel. Serwer zażądał uwierzytelniania klienta, a podane poświadczenia nie zawierają certyfikatu lub certyfikat nie został wystawiony przez urząd certyfikacji zaufany przez 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	Błąd jest spowodowany nieprawidłowo sformułowanym tokenem wejściowym, takim jak token uszkodzony podczas przesyłania, token o nieprawidłowym rozmiarze lub token przekazany do nieprawidłowego ograniczonego delegowania. Przekazanie tokenu do nieprawidłowego pakietu może wystąpić, jeśli klient i serwer nie wynegocjowały odpowiedniego ograniczonego delegowania.
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 ograniczonej delegowaniu nie są dostępne żadne poświadczenia.
SEC_E_TARGET_UNKNOWN	Obiekt docelowy nie został rozpoznany.
SEC_E_UNSUPPORTED_FUNCTION	Flaga atrybutu kontekstu, która jest nieprawidłowa (ISC_REQ_DELEGATE lub ISC_REQ_PROMPT_FOR_CREDS) została określona w parametrze fContextReq .
SEC_E_WRONG_PRINCIPAL	Podmiot zabezpieczeń, który odebrał żądanie uwierzytelniania, nie jest taki sam jak podmiot przekazany do parametru pszTargetName . Oznacza to niepowodzenie w wzajemnym uwierzytelnianiu.

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 (Digest) 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 (Digest).
4. Metoda AcceptSecurityContext (Szyfrowana) może zwrócić token, który serwer wysyła do klienta na drugie wywołanie metody InitializeSecurityContext (Digest), 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 (Digest) 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 (Digest). 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 (Szyfrowane) i nie jest oczekiwana żadna odpowiedź z serwera. Jeśli zwracany kod jest SEC_I_CONTINUE_NEEDED, klient oczekuje tokenu w odpowiedzi z serwera i przekazuje go w drugim wywołaniu do initializeSecurityContext (Skrót). 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 (Skrót) 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.

Po pomyślnym zakończeniu klient może ponownie wywołać metodę InitializeSecurityContext (Digest). 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

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 (w tym Security.h)
Biblioteka	Secur32.lib powiedział:
DLL	Secur32.dll

Zobacz też

funkcji SSPI

AcceptSecurityContext (skrót)

AcquireCredentialsHandle (skrót)

CompleteAuthToken (Kompletny AuthToken)

DeleteSecurityContext

FreeContextBuffer (bufor FreeContextBuffer)

Bufor SecBuffer (bufor sekcyjny)

SecBufferDesc