De functie InitializeSecurityContext (CredSSP)

De functie InitializeSecurityContext (CredSSP) initieert de clientzijde, uitgaande beveiligingscontext vanuit een referentie-handle. De functie bouwt een beveiligingscontext tussen de clienttoepassing en een externe peer. InitializeSecurityContext (CredSSP) retourneert een token dat de client moet doorgeven aan de externe peer; de peer verzendt dat token op zijn beurt naar de lokale beveiligingsuitvoering via de aanroep AcceptSecurityContext (CredSSP). Het gegenereerde token moet door alle bellers als ondoorzichtig worden beschouwd.

Normaal gesproken wordt de functie InitializeSecurityContext (CredSSP) aangeroepen in een lus totdat er 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_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameterwaarden

phCredential-[in, optional]

Een ingang naar de referenties die worden geretourneerd door AcquireCredentialsHandle (CredSSP). Deze ingang wordt gebruikt om de beveiligingscontext te bouwen. Voor de functie InitializeSecurityContext (CredSSP) zijn ten minste UITGAANDE referenties vereist.

phContext-[in, optional]

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

Geef bij de eerste aanroep van InitializeSecurityContext (CredSSP) op NULL. Geef bij toekomstige aanroepen het token op dat is ontvangen in de parameter phNewContext na de eerste aanroep van deze functie.

pDoelnaam[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]

Gereserveerd. Deze parameter moet worden ingesteld op nul.

TargetDataRep-[in]

De gegevensweergave, zoals bytevolgorde, op het doel. Deze parameter kan worden SECURITY_NATIVE_DREP of SECURITY_NETWORK_DREP.

[in, out, 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]

Gereserveerd. Deze parameter moet worden ingesteld op nul.

phNewContext-[in, out, optional]

Een aanwijzer naar een CtxtHandle structuur. Bij de eerste aanroep van InitializeSecurityContext (CredSSP) 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-[out, optional]

Een aanwijzer naar een SecBufferDesc-structuur . Deze structuur bevat op zijn beurt aanwijzers 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 CredSSP geheugen toe voor de buffer en plaatst u de juiste informatie in secbufferDesc.

pfContextAttr-[out]

Een aanwijzer naar een set bitvlaggen 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, wordt een van de volgende succescodes geretourneerd.

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 client roept de functie InitializeSecurityContext (CredSSP) aan 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 retourneert de aanwijzer in het TOKEN-element.
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 (CredSSP).
4. AcceptSecurityContext (CredSSP) kan een token retourneren. De server verzendt dit token naar de client via een tweede InitializeSecurityContext-aanroep (CredSSP) als de eerste aanroep SEC_I_CONTINUE_NEEDED geretourneerd.

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.

Initialisatie van beveiligingscontext kan meer dan één aanroep van deze functie vereisen, 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. Hoewel de parameter pfContextAttributes geldig is voor een geslaagde retour, moet u de vlaggen onderzoeken die betrekking hebben op beveiligingsaspecten van de context alleen op de uiteindelijke geslaagde retour. Tussenliggende returns kunnen 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 . Hoewel dit geen algemene oplossing is, is het mogelijk om een sterk combinatie van beveiligingspakket en toepassing mogelijk te maken, indien van toepassing.

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 (CredSSP) 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 (CredSSP). 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 (CredSSP) 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 op een later tijdstip van de verificatie-uitwisseling mislukt.

De client kan InitializeSecurityContext (CredSSP) 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 de r-referenties die zijn doorgegeven aan de functie AcquireCredentialsHandle (CredSSP) een geldig en vertrouwd certificaat opgegeven. Het certificaat moet een certificaat voor clientverificatie zijn dat is uitgegeven door een certificeringsinstantie 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 (CredSSP) aan met het kenmerk SECPKG_ATTR_ISSUER_LIST_EX .

Na ontvangst van een verificatiecertificaat van een certificeringsinstantie die de server vertrouwt, maakt de clienttoepassing een nieuwe referentie. Dit doet u door de functie AcquireCredentialsHandle (CredSSP) aan te roepen en vervolgens InitializeSecurityContext (CredSSP) opnieuw aan te roepen, waarbij u de nieuwe referentie opgeeft in de parameter phCredential .

Vereisten

Zie ook

SSPI-functies

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc