Funktionen InitializeSecurityContext (Schannel)

Funktionen InitializeSecurityContext (Schannel) initierar klientsidans utgående säkerhetskontext från ett autentiseringshandtag. Funktionen används för att skapa en säkerhetskontext mellan klientprogrammet och en fjärransluten peer. InitializeSecurityContext (Schannel) returnerar en token som klienten måste skicka till fjärr-peer, som peer i sin tur skickar till den lokala säkerhetsimplementeringen via anropet AcceptSecurityContext (Schannel). Den token som genereras bör betraktas som ogenomskinlig av alla anropare.

Vanligtvis anropas funktionen InitializeSecurityContext (Schannel) i en loop tills en tillräcklig säkerhetskontext har upprättats.

Syntax

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
);

Parameterar

phCredential[in, optional]

En referens till autentiseringsuppgifterna som returneras av AcquireCredentialsHandle (Schannel). Det här handtaget används för att skapa säkerhetskontexten. Funktionen InitializeSecurityContext (Schannel) kräver minst UTGÅENDE autentiseringsuppgifter vid det första anropet. Vid efterföljande anrop kan detta vara NULL.

phContext (på engelska)[in, optional]

En pekare till en CtxtHandle struktur. Vid det första anropet till InitializeSecurityContext (Schannel) är NULLden här pekaren . Vid framtida anrop är den här parametern en pekare till referensen till den delvis formade kontexten som returneras i parametern phNewContext av det första anropet till den här funktionen.

Varning

Använd inte samma kontextreferens i samtidiga anrop till InitializeSecurityContext (Schannel). API-implementeringen i säkerhetstjänstleverantörerna är inte trådsäker.

pszTargetName[in, optional]

En pekare till en null-avslutad sträng som unikt identifierar målservern. Schannel använder det här värdet för att verifiera servercertifikatet. Schannel använder också det här värdet för att hitta sessionen i sessionscachen när du återupprättar en anslutning. Den cachelagrade sessionen används endast om alla följande villkor uppfylls:

• Målnamnet är detsamma.
• Cacheposten har inte upphört att gälla.
• Programprocessen som anropar funktionen är densamma.
• Inloggningssessionen är densamma.
• Referensen för autentiseringsuppgifter är densamma.

fContextReq (på engelska)[in]

Bitflaggor som anger begäranden för kontexten. Alla paket kan inte ha stöd för alla krav. Flaggor som används för den här parametern är prefix med ISC_REQ_, till exempel ISC_REQ_DELEGATE. Den här parametern kan vara en eller flera av följande attributflaggor.

Värde	Innebörd
ISC_REQ_ALLOCATE_MEMORY	Säkerhetspaketet allokerar utdatabuffertar åt dig. När du är klar med utdatabuffertarna frigör du dem genom att anropa funktionen FreeContextBuffer.
ISC_REQ_CONFIDENTIALITY	Kryptera meddelanden med hjälp av funktionen EncryptMessage .
ISC_REQ_CONNECTION	Säkerhetskontexten hanterar inte formateringsmeddelanden.
ISC_REQ_EXTENDED_ERROR	När fel inträffar meddelas fjärrparten.
ISC_REQ_INTEGRITY	Signera meddelanden och verifiera signaturer med hjälp av funktionerna EncryptMessage och MakeSignature .
ISC_REQ_MANUAL_CRED_VALIDATION	Schannel får inte autentisera servern automatiskt.
ISC_REQ_MUTUAL_AUTH	Tjänstens princip för ömsesidig autentisering uppfylls. FÖRSIKTIGHET: Detta innebär inte nödvändigtvis att ömsesidig autentisering utförs, bara att tjänstens autentiseringsprincip är uppfylld. För att säkerställa att ömsesidig autentisering utförs anropar du funktionen QueryContextAttributes (Schannel).
ISC_REQ_REPLAY_DETECT	Identifiera uppspelade meddelanden som har kodats med hjälp av funktionerna EncryptMessage eller MakeSignature .
ISC_REQ_SEQUENCE_DETECT	Identifiera meddelanden som tagits emot utan sekvens.
ISC_REQ_STREAM	Stöd för en strömorienterad anslutning.
ISC_REQ_USE_SUPPLIED_CREDS	Schannel får inte försöka ange autentiseringsuppgifter för klienten automatiskt.

De begärda attributen kanske inte stöds av klienten. Mer information finns i parametern pfContextAttr.

Ytterligare beskrivningar av de olika attributen finns i Kontextkrav.

Reserverad1[in]

Den här parametern är reserverad och måste vara inställd på noll.

TargetDataRep (på engelska)[in]

Den här parametern används inte med Schannel. Ställ in den på noll.

pIngång[in, optional]

En pekare till en SecBufferDesc-struktur som innehåller pekare till de buffertar som tillhandahålls som indata till paketet. Om inte klientkontexten initierades av servern måste värdet för den här parametern vara NULL vid det första anropet till funktionen. Vid efterföljande anrop till funktionen eller när klientkontexten initierades av servern är värdet för den här parametern en pekare till en buffert som allokerats med tillräckligt med minne för att lagra den token som returnerades av fjärrdatorn.

Vid anrop till den här funktionen efter det första anropet måste det finnas två buffertar. Den första har typen SECBUFFER_TOKEN och innehåller den token som tagits emot från servern. Den andra bufferten har typen SECBUFFER_EMPTY; ange både pvBuffer - och cbBuffer-medlemmarna till noll.

Reserverad 2[in]

Den här parametern är reserverad och måste vara inställd på noll.

phNewContext[in, out, optional]

En pekare till en CtxtHandle struktur. Vid det första anropet till InitializeSecurityContext (Schannel) tar den här pekaren emot det nya kontexthandtaget. Vid det andra anropet kan phNewContext vara samma som referensen som anges i parametern phContext . phNewContext ska aldrig vara NULL.

pUtdata[in, out, optional]

En pekare till en SecBufferDesc-struktur som innehåller pekare till SecBuffer-strukturen som tar emot utdata. Om en buffert har skrivits som SEC_READWRITE i indata kommer den att finnas där vid utdata. Systemet allokerar en buffert för säkerhetstoken om det begärs (via ISC_REQ_ALLOCATE_MEMORY) och fyller i adressen i buffertbeskrivningen för säkerhetstoken.

Om flaggan ISC_REQ_ALLOCATE_MEMORY anges allokerar Schannel SSP minne för bufferten och lägger lämplig information i SecBufferDesc. Dessutom måste anroparen skicka in en buffert av typen SECBUFFER_ALERT. Om en avisering genereras i utdata innehåller den här bufferten information om aviseringen och funktionen misslyckas.

pfContextAttr[out]

En pekare till en variabel för att ta emot en uppsättning bitflaggor som anger attributen för den etablerade kontexten. En beskrivning av de olika attributen finns i Kontextkrav.

Flaggor som används för den här parametern är prefix med ISC_RET, till exempel ISC_RET_DELEGATE. En lista över giltiga värden finns i parametern fContextReq .

Sök inte efter säkerhetsrelaterade attribut förrän det slutliga funktionsanropet returneras. Attributflaggor som inte är relaterade till säkerhet, till exempel flaggan ASC_RET_ALLOCATED_MEMORY, kan kontrolleras innan den slutliga returen.

Anmärkning

Vissa kontextattribut kan ändras under förhandling med en fjärransluten peer.

ptsFörfallodatum[out, optional]

En pekare till en TimeStamp struktur som tar emot förfallotiden för kontexten. Vi rekommenderar att säkerhetspaketet alltid returnerar det här värdet i lokal tid. Den här parametern är valfri och NULL bör skickas för kortlivade klienter.

Returvärde

Om funktionen lyckas returnerar funktionen någon av följande lyckade koder.

Returkod	Beskrivning
SEC_I_COMPLETE_AND_CONTINUE	Klienten måste anropa CompleteAuthToken och sedan skicka utdata till servern. Klienten väntar sedan på en returnerad token och skickar den i ett annat anrop till InitializeSecurityContext (Schannel).
SEC_I_COMPLETE_NEEDED	Klienten måste slutföra skapandet av meddelandet och anropa sedan funktionen CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	Klienten måste skicka utdatatoken till servern och vänta på en returtoken. Den returnerade token skickas sedan i ett annat anrop till InitializeSecurityContext (Schannel). Utdatatoken kan vara tom.
SEC_I_INCOMPLETE_CREDENTIALS	Servern har begärt klientautentisering och de angivna autentiseringsuppgifterna innehåller antingen inget certifikat eller så har certifikatet inte utfärdats av en certifikatutfärdare (CA) som är betrodd av servern. Mer information finns i Anmärkningar.
SEC_E_INCOMPLETE_MESSAGE	Data för hela meddelandet lästes inte från tråden. När det här värdet returneras innehåller pInput-bufferten en SecBuffer-struktur med en BufferType-medlemi SECBUFFER_MISSING. CbBuffer-medlemmen i SecBuffer innehåller ett värde som anger antalet ytterligare byte som funktionen måste läsa från klienten innan den här funktionen lyckas. Även om det här talet inte alltid är korrekt kan det hjälpa till att förbättra prestanda genom att undvika flera anrop till den här funktionen.
SEC_E_OK	Säkerhetskontexten initierades. Det finns inget behov av ett annat InitializeSecurityContext-anrop (Schannel). Om funktionen returnerar en utdatatoken, d.v.s. om SECBUFFER_TOKEN in pOutput har en längd som inte är noll, måste denna token skickas till servern.

Om funktionen misslyckas returnerar funktionen någon av följande felkoder.

Returkod	Beskrivning
SEC_E_INSUFFICIENT_MEMORY	Det finns inte tillräckligt med minne för att slutföra den begärda åtgärden.
SEC_E_INTERNAL_ERROR	Ett fel uppstod som inte mappades till en SSPI-felkod.
SEC_E_INVALID_HANDLE	Handtaget som skickas till funktionen är inte giltigt.
SEC_E_INVALID_TOKEN	Felet beror på en felaktig indatatoken, till exempel en token som är skadad under överföring, en token med felaktig storlek eller en token som skickas till fel begränsad delegering. Att skicka en token till fel paket kan inträffa om klienten och servern inte förhandlade om rätt begränsad delegering.
SEC_E_LOGON_DENIED	Inloggningen misslyckades.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Det gick inte att kontakta någon utfärdare för autentisering. Domännamnet för den autentiserande parten kan vara fel, domänen kan inte nås eller så kan det ha uppstått ett förtroenderelationsfel.
SEC_E_NO_CREDENTIALS	Inga autentiseringsuppgifter är tillgängliga i den begränsade delegeringen.
SEC_E_TARGET_UNKNOWN	Målet kändes inte igen.
SEC_E_UNSUPPORTED_FUNCTION	En kontextattributflagga som inte är giltig (ISC_REQ_DELEGATE eller ISC_REQ_PROMPT_FOR_CREDS) angavs i parametern fContextReq .
SEC_E_WRONG_PRINCIPAL	Det huvudnamn som tog emot autentiseringsbegäran är inte detsamma som det som skickades till parametern pszTargetName . Detta indikerar ett fel i ömsesidig autentisering.
SEC_E_APPLICATION_PROTOCOL_MISMATCH	Det finns inget gemensamt programprotokoll mellan klienten och servern.

Anmärkningar

Anroparen ansvarar för att avgöra om de slutliga kontextattributen är tillräckliga. Om till exempel konfidentialitet begärdes, men inte kunde upprättas, kan vissa program välja att stänga av anslutningen omedelbart.

Om attributen i säkerhetskontexten inte räcker till måste klienten frigöra den delvis skapade kontexten genom att anropa funktionen DeleteSecurityContext .

Funktionen InitializeSecurityContext (Schannel) används av en klient för att initiera en utgående kontext.

För en säkerhetskontext med två steg är anropssekvensen följande:

1. Klienten anropar funktionen med phContext inställt på NULL och fyller i buffertbeskrivningen med indatameddelandet.
2. Säkerhetspaketet undersöker parametrarna och konstruerar en ogenomskinlig token och placerar den i TOKEN-elementet i buffertmatrisen. Om parametern fContextReq innehåller flaggan ISC_REQ_ALLOCATE_MEMORY allokerar säkerhetspaketet minnet och returnerar pekaren i TOKEN-elementet.
3. Klienten skickar token som returneras i pOutput-bufferten till målservern. Servern skickar sedan token som ett indataargument i ett anrop till funktionen AcceptSecurityContext (Schannel).
4. AcceptSecurityContext (Schannel) kan returnera en token som servern skickar till klienten för ett andra anrop till InitializeSecurityContext (Schannel) om det första anropet returnerades SEC_I_CONTINUE_NEEDED.

För säkerhetskontexter medflera ben, till exempel ömsesidig autentisering, är anropssekvensen följande:

1. Klienten anropar funktionen enligt beskrivningen tidigare, men paketet returnerar SEC_I_CONTINUE_NEEDED lyckad kod.
2. Klienten skickar utdatatoken till servern och väntar på serverns svar.
3. När serverns svar har tagits emot anropar klienten InitializeSecurityContext (Schannel) igen, med phContext inställt på handtaget som returnerades från det senaste anropet. Den token som tas emot från servern anges i parametern pInput .
4. Använd inte phContext-värdet i samtidiga anrop till InitializeSecurityContext (Schannel). Implementeringen i säkerhetsprovidrar är inte trådsäker.

Om servern har svarat returnerar säkerhetspaketet SEC_E_OK och en säker session upprättas.

Om funktionen returnerar ett av felsvaren godkänns inte serverns svar och sessionen upprättas inte.

Om funktionen returnerar SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED eller SEC_I_COMPLETE_AND_CONTINUE upprepas steg 2 och 3.

För att initiera en säkerhetskontext kan fler än ett anrop till den här funktionen krävas, beroende på den underliggande autentiseringsmekanismen samt de val som anges i parametern fContextReq .

Parametrarna fContextReq och pfContextAttributes är bitmasker som representerar olika kontextattribut. En beskrivning av de olika attributen finns i Kontextkrav. Parametern pfContextAttributes är giltig vid lyckad retur, men endast vid den slutliga lyckade returen bör du undersöka flaggorna som gäller säkerhetsaspekter i kontexten. Mellanliggande returer kan till exempel ange flaggan ISC_RET_ALLOCATED_MEMORY.

Om flaggan ISC_REQ_USE_SUPPLIED_CREDS anges måste säkerhetspaketet leta efter en SECBUFFER_PKG_PARAMS bufferttyp i pInput-indatabufferten. Detta är inte en allmän lösning, men det möjliggör en stark parkoppling av säkerhetspaket och program när det är lämpligt.

Om ISC_REQ_ALLOCATE_MEMORY har angetts måste anroparen frigöra minnet genom att anropa funktionen FreeContextBuffer .

Till exempel kan indatatoken vara utmaningen från en LAN Manager. I det här fallet skulle utdatatoken vara det NTLM-krypterade svaret på utmaningen.

Vilken åtgärd klienten vidtar beror på returkoden från den här funktionen. Om returkoden är SEC_E_OK kommer det inte att finnas något andra InitializeSecurityContext-anrop (Schannel) och inget svar från servern förväntas. Om returkoden är SEC_I_CONTINUE_NEEDED förväntar sig klienten en token som svar från servern och skickar den i ett andra anrop till InitializeSecurityContext (Schannel). Den SEC_I_COMPLETE_NEEDED returkoden anger att klienten måste slutföra skapandet av meddelandet och anropa funktionen CompleteAuthToken . Koden SEC_I_COMPLETE_AND_CONTINUE innehåller båda dessa åtgärder.

Om InitializeSecurityContext (Schannel) returnerar framgång vid det första (eller enda) anropet måste anroparen slutligen funktionen DeleteSecurityContext i det returnerade handtaget, även om anropet misslyckas under en senare del av autentiseringsutbytet.

Klienten kan anropa InitializeSecurityContext (Schannel) igen när den har slutförts. Detta anger för säkerhetspaketet att en omautentisering är önskad.

Anropare i kernelläge har följande skillnader: målnamnet är en Unicode-sträng som måste allokeras i virtuellt minne med hjälp av VirtualAlloc. Den får inte allokeras från poolen. Buffertar som skickas och tillhandahålls i pInput och pOutput måste finnas i virtuellt minne, inte i poolen.

Om funktionen returnerar SEC_I_INCOMPLETE_CREDENTIALS kontrollerar du att du har angett ett giltigt och betrott certifikat i dina autentiseringsuppgifter. Certifikatet anges när du anropar funktionen AcquireCredentialsHandle (Schannel). Certifikatet måste vara ett certifikat för klientautentisering som utfärdats av en certifikatutfärdare (CA) som är betrodd av servern. Om du vill hämta en lista över certifikatutfärdare som är betrodda av servern anropar du funktionen QueryContextAttributes (Schannel) och anger attributet SECPKG_ATTR_ISSUER_LIST_EX.

När ett klientprogram har fått ett autentiseringscertifikat från en certifikatutfärdare som är betrodd av servern skapar programmet en ny autentiseringsuppgift genom att anropa funktionen AcquireCredentialsHandle (Schannel) och sedan anropa InitializeSecurityContext (Schannel) igen och ange den nya autentiseringsuppgiften i parametern phCredential .

Krav

Krav	Värde
Lägsta klient som stöds	Windows 8.1 [endast skrivbordsappar]
Lägsta server som stöds	Windows Server 2012 R2 [endast skrivbordsappar]
Rubrik	Sspi.h (inkludera Security.h)
Bibliotek	Secur32.lib
DLL	Secur32.dll

Se även

SSPI-funktioner

AcceptSecurityContext (Schannel)

AcquireCredentialsHandle (Schannel)

CompleteAuthToken (på engelska)

DeleteSecurityContext (Ta bort SecurityContext)

FreeContextBuffer (på engelska)

SecBuffer (på engelska)

SecBufferDesc (på engelska)