Funkce InitializeSecurityContext (Schannel)

Funkce InitializeSecurityContext (Schannel) inicializujeodchozí kontext zabezpečení na straně klienta z popisovače přihlašovacích údajů. Funkce se používá k vytvoření kontextu zabezpečení mezi klientskou aplikací a vzdáleným partnerským vztahem. InitializeSecurityContext (Schannel) vrátí token, který musí klient předat vzdálenému partnerskému uzlu, který pak partnerský vztah odešle do místní implementace zabezpečení prostřednictvím volání AcceptSecurityContext (Schannel). Vygenerovaný token by měl být považován za neprůzný všemi volajícími.

Funkce InitializeSecurityContext (Schannel) se obvykle volá ve smyčce, dokud se nenaváže dostatečný kontext zabezpečení .

Syntaxe

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

pověření phCredential[in, optional]

Popisovač přihlašovacích údajů vrácených rutinou AcquireCredentialsHandle (Schannel) Tento popisovač se používá k sestavení kontextu zabezpečení. Funkce InitializeSecurityContext (Schannel) vyžaduje při prvním volání alespoň přihlašovací údaje OUTBOUND. Při následných voláních to může být NULL.

[in, optional] phContext

Ukazatel na strukturu CtxtHandle. Při prvním volání InitializeSecurityContext (Schannel) je NULLtento ukazatel . Při budoucích voláních je tento parametr ukazatelem na popisovač na částečně vytvořený kontext vrácený v parametru phNewContext prvním voláním této funkce.

Výstraha

Nepoužívejte stejný popisovač kontextu v souběžných voláních InitializeSecurityContext (Schannel). Implementace rozhraní API ve zprostředkovatelích služeb zabezpečení není bezpečná pro přístup z více vláken.

pszNázev_cíle[in, optional]

Ukazatel na řetězec ukončený hodnotou null, který jednoznačně identifikuje cílový server. Schannel používá tuto hodnotu k ověření certifikátu serveru. Schannel také používá tuto hodnotu k vyhledání relace v mezipaměti relace při opětovném publikování připojení. Relace uložená v mezipaměti se používá pouze v případě, že jsou splněny všechny následující podmínky:

  • Cílový název je stejný.
  • Platnost položky mezipaměti nevypršela.
  • Proces aplikace, který volá funkci, je stejný.
  • Přihlašovací relace je stejná.
  • Popisovač přihlašovacích údajů je stejný.

fContextReq[in]

Bitové příznaky, které označují požadavky na kontext. Ne všechny balíčky můžou podporovat všechny požadavky. Příznaky použité pro tento parametr mají předponu ISC_REQ_, například ISC_REQ_DELEGATE. Tento parametr může být jeden nebo více příznaků následujících atributů.

Hodnota Význam
ISC_REQ_ALLOCATE_MEMORY Balíček zabezpečení za vás přiděluje výstupní vyrovnávací paměti. Po dokončení používání výstupních vyrovnávacích pamětí je uvolněte voláním FreeContextBuffer funkce.
ISC_REQ_CONFIDENTIALITY Zašifrujte zprávy pomocí funkce EncryptMessage .
ISC_REQ_CONNECTION Kontext zabezpečení nezpracuje zprávy formátování.
ISC_REQ_EXTENDED_ERROR Pokud dojde k chybám, bude vzdálená strana upozorněna.
ISC_REQ_INTEGRITY Podepište zprávy a ověřte podpisy pomocí funkcí EncryptMessage a MakeSignature .
ISC_REQ_MANUAL_CRED_VALIDATION Schannel nesmí automaticky ověřovat server.
ISC_REQ_MUTUAL_AUTH Zásady vzájemného ověřování služby budou splněny.
OPATRNOST: To nemusí nutně znamenat, že se provádí vzájemné ověřování, pouze že jsou splněny zásady ověřování služby. Pokud chcete zajistit, aby se provedlo vzájemné ověřování, zavolejte funkci QueryContextAttributes (Schannel).
ISC_REQ_REPLAY_DETECT Pomocí funkcí EncryptMessage nebo MakeSignature detekujte přehrání zpráv, které byly kódovány.
ISC_REQ_SEQUENCE_DETECT Detekce zpráv přijatých mimo posloupnost
ISC_REQ_STREAM Podpora připojení orientovaného na stream
ISC_REQ_USE_SUPPLIED_CREDS Schannel se nesmí pokoušet o automatické zadání přihlašovacích údajů pro klienta.

Požadované atributy nemusí klient podporovat. Další informace naleznete v pfContextAttr parametr.

Další popisy různých atributů najdete v tématu Požadavky na kontext.

Rezervovaný 1[in]

Tento parametr je vyhrazený a musí být nastaven na nulu.

Cílová datarep[in]

Tento parametr se nepoužívá s Schannel. Nastavte ji na nulu.

pVstup[in, optional]

Ukazatel na strukturu SecBufferDesc , která obsahuje ukazatele na vyrovnávací paměti zadané jako vstup balíčku. Pokud server neicializoval kontext klienta, musí být NULL hodnota tohoto parametru při prvním volání funkce. Při následných voláních funkce nebo při spuštění kontextu klienta serverem je hodnota tohoto parametru ukazatelem na vyrovnávací paměť přidělenou dostatek paměti pro uložení tokenu vráceného vzdáleným počítačem.

Při volání této funkce po počátečním volání musí existovat dvě vyrovnávací paměti. První má typ SECBUFFER_TOKEN a obsahuje token přijatý ze serveru. Druhá vyrovnávací paměť má typ SECBUFFER_EMPTY; nastavte oba členy pvBuffer a cbBuffer na nulu.

Vyhrazeno 2[in]

Tento parametr je vyhrazený a musí být nastaven na nulu.

[in, out, optional] phNewContext

Ukazatel na strukturu CtxtHandle. Při prvním volání InitializeSecurityContext (Schannel) tento ukazatel obdrží nový popisovač kontextu. Při druhém volání může být phNewContext stejný jako popisovač zadaný v parametru phContext . phNewContext by nikdy neměly být NULL.

pVýstup[in, out, optional]

Ukazatel na strukturu SecBufferDesc , která obsahuje ukazatele na strukturu SecBuffer , která přijímá výstupní data. Pokud byla vyrovnávací paměť zadána jako SEC_READWRITE ve vstupu, bude tam ve výstupu. Systém přidělí vyrovnávací paměť tokenu zabezpečení v případě požadavku (prostřednictvím ISC_REQ_ALLOCATE_MEMORY) a vyplní adresu v popisovači vyrovnávací paměti tokenu zabezpečení.

Pokud je zadán příznak ISC_REQ_ALLOCATE_MEMORY, zprostředkovatel zabezpečení Schannel přidělí paměť pro vyrovnávací paměť a umístí příslušné informace do secBufferDesc. Volající navíc musí předat vyrovnávací paměť typu SECBUFFER_ALERT. Pokud se ve výstupu vygeneruje výstraha, tato vyrovnávací paměť obsahuje informace o tomto upozornění a funkce selže.

pfContextAttr[out]

Ukazatel na proměnnou pro příjem sady bitových příznaků, které označují atributy vytvořeného kontextu. Popis různých atributů najdete v tématu Kontextové požadavky.

Příznaky použité pro tento parametr mají předponu ISC_RET, například ISC_RET_DELEGATE. Seznam platných hodnot najdete v parametru fContextReq .

Nekontrolujte atributy související se zabezpečením, dokud se konečné volání funkce úspěšně nevrátí. Příznaky atributů, které nesouvisí se zabezpečením, jako je například příznak ASC_RET_ALLOCATED_MEMORY, je možné zkontrolovat před konečným vrácením.

Poznámka:

Během vyjednávání se vzdáleným partnerským vztahem se můžou změnit konkrétní atributy kontextu.

ptsVypršení platnosti[out, optional]

Ukazatel na strukturu TimeStamp, která přijímá čas vypršení platnosti kontextu. Doporučuje se, aby balíček zabezpečení vždy vrátil tuto hodnotu v místním čase. Tento parametr je volitelný a NULL měl by být předán pro krátkodobé klienty.

Návratová hodnota

Pokud je funkce úspěšná, vrátí funkce jeden z následujících kódů úspěchu.

Návratový kód Popis
SEC_I_COMPLETE_AND_CONTINUE Klient musí volat CompleteAuthToken a pak předat výstup serveru. Klient pak čeká na vrácený token a předá ho v jiném volání do InitializeSecurityContext (Schannel).
SEC_I_COMPLETE_NEEDED Klient musí dokončit sestavení zprávy a potom volat funkci CompleteAuthToken .
SEC_I_CONTINUE_NEEDED Klient musí odeslat výstupní token serveru a počkat na návratový token. Vrácený token se pak předá v jiném volání InitializeSecurityContext (Schannel). Výstupní token může být prázdný.
SEC_I_INCOMPLETE_CREDENTIALS Server požádal o ověření klienta a zadané přihlašovací údaje buď neobsahují certifikát, nebo certifikát nebyl vydán certifikační autoritou (CA), která je serverem důvěryhodná. Další informace naleznete v tématu Poznámky.
SEC_E_INCOMPLETE_MESSAGE Data pro celou zprávu nebyla načtena z drátu.
Pokud je tato hodnota vrácena, pInput vyrovnávací paměť obsahuje secBuffer struktury s bufferType člen SECBUFFER_MISSING. CbBuffer člen SecBuffer obsahuje hodnotu, která označuje počet dalších bajtů, které funkce musí číst z klienta dříve, než bude tato funkce úspěšná. I když toto číslo není vždy přesné, může jeho použití přispět ke zlepšení výkonu tím, že zabrání více voláním této funkce.
SEC_E_OK Kontext zabezpečení byl úspěšně inicializován. Další volání InitializeSecurityContext (Schannel) není potřeba. Pokud funkce vrací výstupní token, to znamená, že pokud má SECBUFFER_TOKEN in pOutput nenulovou délku, musí být tento token odeslán na server.

Pokud funkce selže, vrátí funkce jeden z následujících kódů chyb.

Návratový kód Popis
SEC_E_INSUFFICIENT_MEMORY K dokončení požadované akce není k dispozici dostatek paměti.
SEC_E_INTERNAL_ERROR Došlo k chybě, která se nenamapovala na kód chyby SSPI.
SEC_E_INVALID_HANDLE Popisovač předaný funkci není platný.
SEC_E_INVALID_TOKEN Příčinou chyby je poškozený vstupní token, například token poškozený při přenosu, token s nesprávnou velikostí nebo token předaný nesprávnému omezenému delegování. Předání tokenu nesprávnému balíčku může nastat, pokud klient a server nevyjednávaly správné omezené delegování.
SEC_E_LOGON_DENIED Přihlášení se nezdařilo.
SEC_E_NO_AUTHENTICATING_AUTHORITY K ověření nelze kontaktovat žádnou autoritu. Název domény ověřovací strany může být chybný, doména může být nedostupná nebo došlo k selhání vztahu důvěryhodnosti.
SEC_E_NO_CREDENTIALS V omezeném delegování nejsou k dispozici žádné přihlašovací údaje.
SEC_E_TARGET_UNKNOWN Cíl nebyl rozpoznán.
SEC_E_UNSUPPORTED_FUNCTION Příznak atributu kontextu, který není platný (ISC_REQ_DELEGATE nebo ISC_REQ_PROMPT_FOR_CREDS) byl zadán v parametru fContextReq .
SEC_E_WRONG_PRINCIPAL Objekt zabezpečení, který obdržel požadavek na ověření, není stejný jako objekt předaný do parametru pszTargetName . To značí selhání vzájemného ověřování.
SEC_E_APPLICATION_PROTOCOL_MISMATCH Mezi klientem a serverem neexistuje žádný běžný aplikační protokol.

Poznámky

Volající zodpovídá za určení, jestli jsou konečné kontextové atributy dostatečné. Pokud se například požaduje důvěrnost, ale nepodařilo se navázat, některé aplikace se můžou rozhodnout připojení okamžitě vypnout.

Pokud atributy kontextu zabezpečení nestačí, klient musí uvolnit částečně vytvořený kontext voláním funkce DeleteSecurityContext .

Funkce InitializeSecurityContext (Schannel) je používána klientem k inicializaci odchozího kontextu.

Pro kontext zabezpečení se dvěma nohami je volající sekvence následující:

  1. Klient volá funkci s phContext nastaveným NULL a vyplní popisovač vyrovnávací paměti vstupní zprávou.
  2. Balíček zabezpečení prozkoumá parametry a vytvoří neprůpaný token a umístí ho do elementu TOKEN v poli vyrovnávací paměti. Pokud parametr fContextReq obsahuje příznak ISC_REQ_ALLOCATE_MEMORY, balíček zabezpečení přidělí paměť a vrátí ukazatel v elementu TOKEN.
  3. Klient odešle token vrácený do vyrovnávací paměti pOutput cílovému serveru. Server pak token předá jako vstupní argument ve volání funkce AcceptSecurityContext (Schannel).
  4. AcceptSecurityContext (Schannel) může vrátit token, který server odešle klientovi pro druhé volání InitializeSecurityContext (Schannel), pokud první volání vráceno SEC_I_CONTINUE_NEEDED.

Pro kontext zabezpečenís více nohami, jako je například vzájemné ověřování, je volající sekvence následující:

  1. Klient volá funkci, jak je popsáno výše, ale balíček vrátí kód SEC_I_CONTINUE_NEEDED úspěchu.
  2. Klient odešle výstupní token serveru a čeká na odpověď serveru.
  3. Po přijetí odpovědi serveru klient znovu volá InitializeSecurityContext (Schannel) s phContext nastavený na popisovač vrácený z posledního volání. Token přijatý ze serveru se zadává v parametru pInput .
  4. Nepoužívejte hodnotu phContext v souběžných voláních initializeSecurityContext (Schannel). Implementace v zprostředkovatelích zabezpečení není bezpečná pro přístup z více vláken.

Pokud server úspěšně odpověděl, balíček zabezpečení vrátí SEC_E_OK a vytvoří se zabezpečená relace.

Pokud funkce vrátí jednu z chybových odpovědí, odpověď serveru není přijata a relace není vytvořena.

Pokud funkce vrátí SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED nebo SEC_I_COMPLETE_AND_CONTINUE, opakují se kroky 2 a 3.

K inicializaci kontextu zabezpečení může být vyžadováno více než jedno volání této funkce v závislosti na základním ověřovacím mechanismu a také na možnostech zadaných v parametru fContextReq .

Parametry fContextReq a pfContextAttributes jsou bitové masky , které představují různé kontextové atributy. Popis různých atributů najdete v tématu Kontextové požadavky. Parametr pfContextAttributes je platný při každém úspěšném vrácení, ale pouze při posledním úspěšném vrácení byste měli prozkoumat příznaky, které se týkají aspektů zabezpečení kontextu. Přechodné návraty můžou například nastavit příznak ISC_RET_ALLOCATED_MEMORY.

Pokud je příznak ISC_REQ_USE_SUPPLIED_CREDS nastaven, musí balíček zabezpečení vyhledat typ vyrovnávací paměti SECBUFFER_PKG_PARAMS ve vstupní vyrovnávací paměti pInput . Nejedná se o obecné řešení, ale v případě potřeby umožňuje silné párování balíčku zabezpečení a aplikace.

Pokud byl zadán ISC_REQ_ALLOCATE_MEMORY, volající musí uvolnit paměť voláním Funkce FreeContextBuffer .

Vstupní token může být například výzvou správce sítě LAN. V tomto případě by výstupní token byl odpovědí na výzvu zašifrovanou protokolem NTLM.

Akce, která klient provede, závisí na návratovém kódu z této funkce. Pokud je návratový kód SEC_E_OK, nebude k dispozici žádné druhé volání InitializeSecurityContext (Schannel) a neočekává se žádná odpověď ze serveru. Pokud je návratový kód SEC_I_CONTINUE_NEEDED, klient očekává token v odpovědi ze serveru a předá ho v druhém volání InitializeSecurityContext (Schannel). Návratový kód SEC_I_COMPLETE_NEEDED označuje, že klient musí dokončit sestavení zprávy a volat funkci CompleteAuthToken . Kód SEC_I_COMPLETE_AND_CONTINUE zahrnuje obě tyto akce.

Pokud InitializeSecurityContext (Schannel) vrátí úspěch při prvním (nebo pouze) volání, volající musí nakonec volat funkci DeleteSecurityContext na vrácený popisovač, i když volání selže na pozdější noze výměny ověřování.

Klient může po úspěšném dokončení znovu volat InitializeSecurityContext (Schannel ). To značí balíček zabezpečení , že se chce znovu ověřit.

Volající v režimu jádra mají následující rozdíly: cílový název je řetězec Unicode , který musí být přidělen ve virtuální paměti pomocí virtualAlloc; nesmí být přiděleno z fondu. Předané vyrovnávací paměti a dodané v pInput a pOutput musí být ve virtuální paměti, ne ve fondu.

Pokud funkce vrátí SEC_I_INCOMPLETE_CREDENTIALS, zkontrolujte, jestli jste v přihlašovacích údajích zadali platný a důvěryhodný certifikát. Certifikát se zadává při volání funkce AcquireCredentialsHandle (Schannel). Certifikát musí být certifikátem ověřování klienta vydaným certifikační autoritou (CA), který server považuje za důvěryhodný. Chcete-li získat seznam certifikačních autorit důvěryhodných serverem, zavolejte funkci QueryContextAttributes (Schannel) a zadejte atribut SECPKG_ATTR_ISSUER_LIST_EX.

Jakmile klientská aplikace obdrží ověřovací certifikát od certifikační autority, která je serverem důvěryhodná, aplikace vytvoří nové přihlašovací údaje voláním funkce AcquireCredentialsHandle (Schannel) a opětovným voláním InitializeSecurityContext (Schannel) a zadáním nových přihlašovacích údajů v parametru phCredential .

Požadavky

Požadavek Hodnota
Minimální podporovaný klient Windows 8.1 [jenom desktopové aplikace]
Minimální podporovaný server Windows Server 2012 R2 [jenom desktopové aplikace]
Záhlaví Sspi.h (včetně Security.h)
Knihovna Secur32.lib řekl:
Knihovna dll Secur32.dll

Viz také

funkcí SSPI

AcceptSecurityContext (Schannel)

AcquireCredentialsHandle (Schannel)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer – metoda FreeContextBuffer

Vyrovnávací paměť SecBuffer

SecBufferDesc

  • Last updated on