De functie InitializeSecurityContext (Schannel)

Met de functie InitializeSecurityContext (Schannel) wordt de uitgaande beveiligingscontext aan de clientzijde gestart vanuit een referentie-handle. De functie wordt gebruikt om een beveiligingscontext te bouwen tussen de clienttoepassing en een externe peer. InitializeSecurityContext (Schannel) retourneert een token dat de client moet doorgeven aan de externe peer, die de peer op zijn beurt verzendt naar de lokale beveiligings geïmplementeerd via de aanroep AcceptSecurityContext (Schannel). Het gegenereerde token moet door alle bellers als ondoorzichtig worden beschouwd.

Normaal gesproken wordt de functie InitializeSecurityContext (Schannel) aangeroepen in een lus totdat een voldoende beveiligingscontext tot stand is gebracht.

Syntaxis

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

Parameterwaarden

phCredential-[in, optional]

Een ingang voor de referenties die worden geretourneerd door AcquireCredentialsHandle (Schannel). Deze ingang wordt gebruikt om de beveiligingscontext te bouwen. De functie InitializeSecurityContext (Schannel) vereist ten minste UITGAANDE referenties voor de eerste aanroep. Bij volgende aanroepen kan dit zijn NULL.

phContext-[in, optional]

Een aanwijzer naar een CtxtHandle structuur. Bij de eerste aanroep van InitializeSecurityContext (Schannel) is NULLdeze aanwijzer. Bij toekomstige aanroepen is deze parameter een aanwijzer naar de ingang naar de gedeeltelijk gevormde context die wordt geretourneerd in de parameter phNewContext door de eerste aanroep naar deze functie.

pszDoelnaam[in, optional]

Een aanwijzer naar een door null beëindigde tekenreeks die de doelserver uniek identificeert. Schannel gebruikt deze waarde om het servercertificaat te verifiëren. Schannel gebruikt deze waarde ook om de sessie in de sessiecache te vinden bij het herstellen van een verbinding. De sessie in de cache wordt alleen gebruikt als aan alle volgende voorwaarden wordt voldaan:

• De doelnaam is hetzelfde.
• De cachevermelding is niet verlopen.
• Het toepassingsproces waarmee de functie wordt aangeroepen, is hetzelfde.
• De aanmeldingssessie is hetzelfde.
• De referentiehandgreep is hetzelfde.

fContextReq-[in]

Bitvlaggen die aanvragen voor de context aangeven. Niet alle pakketten kunnen alle vereisten ondersteunen. Vlaggen die voor deze parameter worden gebruikt, worden voorafgegaan door ISC_REQ_, bijvoorbeeld ISC_REQ_DELEGATE. Deze parameter kan een of meer van de volgende kenmerkenvlagken zijn.

De aangevraagde kenmerken worden mogelijk niet ondersteund door de client. Zie de parameter pfContextAttr voor meer informatie.

Zie Contextvereisten voor meer beschrijvingen van de verschillende kenmerken.

Gereserveerd1[in]

Deze parameter is gereserveerd en moet worden ingesteld op nul.

TargetDataRep-[in]

Deze parameter wordt niet gebruikt met Schannel. Stel deze in op nul.

[in, optional]

Een aanwijzer naar een SecBufferDesc-structuur die aanwijzers bevat naar de buffers die als invoer voor het pakket worden geleverd. Tenzij de clientcontext door de server is gestart, moet de waarde van deze parameter de eerste aanroep naar de functie hebben NULL . Bij volgende aanroepen naar de functie of wanneer de clientcontext door de server is gestart, is de waarde van deze parameter een aanwijzer naar een buffer die is toegewezen met voldoende geheugen om het token te bewaren dat door de externe computer wordt geretourneerd.

Bij aanroepen naar deze functie na de eerste aanroep moeten er twee buffers zijn. Het eerste type heeft SECBUFFER_TOKEN en bevat het token dat van de server is ontvangen. De tweede buffer heeft het type SECBUFFER_EMPTY; stel zowel de pvBuffer - als cbBuffer-leden in op nul.

Gereserveerd2[in]

Deze parameter is gereserveerd en moet worden ingesteld op nul.

phNewContext-[in, out, optional]

Een aanwijzer naar een CtxtHandle structuur. Bij de eerste aanroep van InitializeSecurityContext (Schannel) ontvangt deze aanwijzer de nieuwe contextgreep. In de tweede aanroep kan phNewContext hetzelfde zijn als de ingang die is opgegeven in de parameter phContext . phNewContext mag nooit zijn NULL.

pOutput-[in, out, optional]

Een aanwijzer naar een SecBufferDesc-structuur die aanwijzers bevat naar de SecBuffer-structuur die de uitvoergegevens ontvangt. Als een buffer is getypt als SEC_READWRITE in de invoer, wordt deze in de uitvoer weergegeven. Het systeem wijst een buffer toe voor het beveiligingstoken indien aangevraagd (via ISC_REQ_ALLOCATE_MEMORY) en vult het adres in de bufferdescriptor voor het beveiligingstoken in.

Als de vlag ISC_REQ_ALLOCATE_MEMORY is opgegeven, wijst de Schannel-SSP geheugen toe voor de buffer en plaatst u de juiste informatie in secbufferDesc. Bovendien moet de beller een buffer van het type SECBUFFER_ALERT doorgeven. Als er een waarschuwing wordt gegenereerd, bevat deze buffer informatie over die waarschuwing en mislukt de functie.

pfContextAttr-[out]

Een aanwijzer naar een variabele om een set bitvlaggen te ontvangen die de kenmerken van de tot stand gebrachte context aangeven. Zie Contextvereistenvoor een beschrijving van de verschillende kenmerken.

Vlaggen die voor deze parameter worden gebruikt, worden voorafgegaan door ISC_RET, zoals ISC_RET_DELEGATE. Zie de parameter fContextReq voor een lijst met geldige waarden.

Controleer pas op beveiligingskenmerken als de laatste functie-aanroep is geretourneerd. Kenmerkvlagmen die niet zijn gerelateerd aan beveiliging, zoals de vlag ASC_RET_ALLOCATED_MEMORY, kunnen worden gecontroleerd voordat de definitieve terugkeer wordt uitgevoerd.

ptsExpiry-[out, optional]

Een aanwijzer naar een TimeStamp structuur die de verlooptijd van de context ontvangt. Het wordt aanbevolen dat het beveiligingspakket deze waarde altijd in lokale tijd retourneert. Deze parameter is optioneel en NULL moet worden doorgegeven voor clients met een korte levensduur.

Retourwaarde

Als de functie slaagt, retourneert de functie een van de volgende succescodes.

Als de functie mislukt, retourneert de functie een van de volgende foutcodes.

Opmerkingen

De aanroeper is verantwoordelijk voor het bepalen of de uiteindelijke contextkenmerken voldoende zijn. Als er bijvoorbeeld om vertrouwelijkheid is gevraagd, maar niet tot stand kon worden gebracht, kunnen sommige toepassingen ervoor kiezen om de verbinding onmiddellijk af te sluiten.

Als kenmerken van de beveiligingscontext niet voldoende zijn, moet de client de gedeeltelijk gemaakte context vrij maken door de functie DeleteSecurityContext aan te roepen.

De functie InitializeSecurityContext (Schannel) wordt door een client gebruikt om een uitgaande context te initialiseren.

Voor een beveiligingscontext met twee been is de aanroepvolgorde als volgt:

1. De client roept de functie aan met phContext ingesteld op NULL en vult de bufferdescriptor in met het invoerbericht.
2. Het beveiligingspakket onderzoekt de parameters en bouwt een ondoorzichtig token, waarbij het in het TOKEN-element in de buffermatrix wordt geplaatst. Als de parameter fContextReq de vlag ISC_REQ_ALLOCATE_MEMORY bevat, wijst het beveiligingspakket het geheugen toe en wordt de aanwijzer in het TOKEN-element geretourneerd.
3. De client verzendt het token dat is geretourneerd in de pOutput-buffer naar de doelserver. De server geeft het token vervolgens door als invoerargument in een aanroep naar de functie AcceptSecurityContext (Schannel ).
4. AcceptSecurityContext (Schannel) kan een token retourneren, dat de server naar de client verzendt voor een tweede aanroep naar InitializeSecurityContext (Schannel) als de eerste aanroep SEC_I_CONTINUE_NEEDED geretourneerd.

Voor beveiligingscontextenmet meerdere been, zoals wederzijdse verificatie, is de aanroepvolgorde als volgt:

1. De client roept de functie aan zoals eerder beschreven, maar het pakket retourneert de SEC_I_CONTINUE_NEEDED succescode.
2. De client verzendt het uitvoertoken naar de server en wacht op het antwoord van de server.
3. Na ontvangst van het antwoord van de server roept de client InitializeSecurityContext (Schannel) opnieuw aan, waarbij phContext is ingesteld op de ingang die is geretourneerd door de laatste aanroep. Het token dat van de server is ontvangen, wordt geleverd in de parameter pInput .
4. Gebruik de phContext-waarde niet in gelijktijdige aanroepen naar InitializeSecurityContext (Schannel). De implementatie in de beveiligingsproviders is niet thread-safe.

Als de server heeft gereageerd, retourneert het beveiligingspakket SEC_E_OK en wordt er een beveiligde sessie tot stand gebracht.

Als de functie een van de foutreacties retourneert, wordt het antwoord van de server niet geaccepteerd en wordt de sessie niet tot stand gebracht.

Als de functie SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED of SEC_I_COMPLETE_AND_CONTINUE retourneert, worden stap 2 en 3 herhaald.

Als u een beveiligingscontext wilt initialiseren, is mogelijk meer dan één aanroep naar deze functie vereist, afhankelijk van het onderliggende verificatiemechanisme en de keuzes die zijn opgegeven in de parameter fContextReq .

De parameters fContextReq en pfContextAttributes zijn bitmaskers die verschillende contextkenmerken vertegenwoordigen. Zie Contextvereistenvoor een beschrijving van de verschillende kenmerken. De parameter pfContextAttributes is geldig voor een geslaagde retour, maar alleen bij de uiteindelijke geslaagde retour moet u de vlaggen onderzoeken die betrekking hebben op beveiligingsaspecten van de context. Tussenliggende retourneert kan bijvoorbeeld de ISC_RET_ALLOCATED_MEMORY vlag instellen.

Als de vlag ISC_REQ_USE_SUPPLIED_CREDS is ingesteld, moet het beveiligingspakket zoeken naar een SECBUFFER_PKG_PARAMS buffertype in de invoerbuffer pInput . Dit is geen algemene oplossing, maar biedt waar nodig een sterke koppeling van beveiligingspakketten en toepassingen.

Als ISC_REQ_ALLOCATE_MEMORY is opgegeven, moet de aanroeper het geheugen vrij maken door de functie FreeContextBuffer aan te roepen.

Het invoertoken kan bijvoorbeeld de uitdaging zijn van een LAN Manager. In dit geval is het uitvoertoken de met NTLM versleutelde reactie op de uitdaging.

De actie die de client uitvoert, is afhankelijk van de retourcode van deze functie. Als de retourcode is SEC_E_OK, wordt er geen tweede initializeSecurityContext-aanroep (Schannel) weergegeven en wordt er geen reactie van de server verwacht. Als de retourcode is SEC_I_CONTINUE_NEEDED, verwacht de client een token in reactie van de server en geeft deze door in een tweede aanroep naar InitializeSecurityContext (Schannel). De SEC_I_COMPLETE_NEEDED retourcode geeft aan dat de client het bericht moet voltooien en de functie CompleteAuthToken moet aanroepen. De SEC_I_COMPLETE_AND_CONTINUE code bevat beide acties.

Als InitializeSecurityContext (Schannel) een succes retourneert bij de eerste (of alleen) aanroep, moet de aanroeper uiteindelijk de functie DeleteSecurityContext aanroepen op de geretourneerde ingang, zelfs als de aanroep mislukt op een later deel van de verificatie-uitwisseling.

De client kan InitializeSecurityContext (Schannel) opnieuw aanroepen nadat deze is voltooid. Dit geeft aan het beveiligingspakket aan dat een herauthenticatie is gewenst.

Bellers in de kernelmodus hebben de volgende verschillen: de doelnaam is een Unicode-tekenreeks die moet worden toegewezen in het virtuele geheugen met behulp van VirtualAlloc; deze mag niet worden toegewezen vanuit de pool. Buffers die zijn doorgegeven en geleverd in pInput en pOutput , moeten zich in het virtuele geheugen bevinden, niet in de pool.

Als de functie SEC_I_INCOMPLETE_CREDENTIALS retourneert, controleert u of u een geldig en vertrouwd certificaat hebt opgegeven in uw referenties. Het certificaat wordt opgegeven bij het aanroepen van de functie AcquireCredentialsHandle (Schannel ). Het certificaat moet een certificaat voor clientverificatie zijn dat is uitgegeven door een certificeringsinstantie (CA) die wordt vertrouwd door de server. Als u een lijst wilt ophalen van de CA's die door de server worden vertrouwd, roept u de functie QueryContextAttributes (Schannel) aan en geeft u het kenmerk SECPKG_ATTR_ISSUER_LIST_EX op.

Nadat een clienttoepassing een verificatiecertificaat heeft ontvangen van een CA die wordt vertrouwd door de server, maakt de toepassing een nieuwe referentie door de functie AcquireCredentialsHandle (Schannel) aan te roepen en vervolgens InitializeSecurityContext (Schannel) opnieuw aan te roepen, waarbij de nieuwe referentie wordt opgegeven in de parameter phCredential .

Vereisten

Zie ook

SSPI-functies

AcceptSecurityContext (Schannel)

AcquireCredentialsHandle (Schannel)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc