Funktionen InitializeSecurityContext (Kerberos)

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

Vanligtvis anropas funktionen InitializeSecurityContext (Kerberos) 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_        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 (Kerberos). Det här handtaget används för att skapa säkerhetskontexten. Funktionen InitializeSecurityContext (Kerberos) kräver minst UTGÅENDE autentiseringsuppgifter.

phContext (på engelska)[in, optional]

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

Varning

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

pszTargetName[in]

En pekare till en null-avslutad sträng som anger tjänstens huvudnamn (SPN) eller målserverns säkerhetskontext .

Använd ett fullständigt kvalificerat målnamn eftersom korta namn inte stöds i skogar.

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. Det här värdet är standardvärdet.
ISC_REQ_DELEGATE	Servern kan använda kontexten för att autentisera till andra servrar som klient. Flaggan ISC_REQ_MUTUAL_AUTH måste anges för att flaggan ska fungera. Giltigt för Kerberos. Ignorera den här flaggan för begränsad delegering.
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_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 (Kerberos).
ISC_REQ_NO_INTEGRITY	Om den här flaggan anges ignoreras flaggan ISC_REQ_INTEGRITY .
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_SESSION_KEY	En ny sessionsnyckel måste förhandlas.

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]

Datarepresentationen, till exempel byteordning, på målet. Den här parametern kan vara antingen SECURITY_NATIVE_DREP eller SECURITY_NETWORK_DREP.

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.

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

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 lokalt. Eftersom den här parametern är valfri NULL bör den skickas för kortlivade klienter.

Returvärde

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

Returkod	Beskrivning
SEC_E_OK	Säkerhetskontexten initierades. Det finns inget behov av ett annat Kerberos-anrop (InitializeSecurityContext). 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.
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 (Kerberos).
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 (Kerberos). Utdatatoken kan vara tom.
SEC_I_INCOMPLETE_CREDENTIALS	Använd med Schannel. 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 Kommentarer.

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.

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 (Kerberos) 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 (Kerberos).
4. AcceptSecurityContext (Kerberos) kan returnera en token som servern skickar till klienten för ett andra anrop till InitializeSecurityContext (Kerberos) 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 (Kerberos) 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 (Kerberos). 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 Kerberos-anrop (InitializeSecurityContext) 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 (Kerberos). 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 Kerberos (InitializeSecurityContext) 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 (Kerberos) 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.

Krav

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

Se även

SSPI-funktioner

AcceptSecurityContext (Kerberos)

AcquireCredentialsHandle (Kerberos)

CompleteAuthToken (på engelska)

DeleteSecurityContext (Ta bort SecurityContext)

FreeContextBuffer (på engelska)

SecBuffer (på engelska)

SecBufferDesc (på engelska)