De functie InitializeSecurityContext (Kerberos)

De functie InitializeSecurityContext (Kerberos) initieert de uitgaande beveiligingscontext aan de clientzijde vanuit een referentiehandle. De functie wordt gebruikt om een beveiligingscontext te bouwen tussen de clienttoepassing en een externe peer. InitializeSecurityContext (Kerberos) retourneert een token dat de client moet doorgeven aan de externe peer, die de peer op zijn beurt verzendt naar de lokale beveiligingsimplementatie via de aanroep AcceptSecurityContext (Kerberos). Het gegenereerde token moet door alle bellers als ondoorzichtig worden beschouwd.

Doorgaans wordt de functie InitializeSecurityContext (Kerberos) in een lus aangeroepen totdat er een voldoende beveiligingscontext is vastgesteld.

Syntaxis

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

Parameterwaarden

phCredential-[in, optional]

Een ingang voor de referenties die worden geretourneerd door AcquireCredentialsHandle (Kerberos). Deze ingang wordt gebruikt om de beveiligingscontext te bouwen. Voor de functie InitializeSecurityContext (Kerberos) zijn ten minste OUTBOUND-referenties vereist.

phContext-[in, optional]

Een aanwijzer naar een CtxtHandle structuur. Bij de eerste aanroep van InitializeSecurityContext (Kerberos) 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 .

pszDoelnaam[in]

Een aanwijzer naar een door null beëindigde tekenreeks die de SPN (Service Principal Name) of de beveiligingscontext van de doelserver aangeeft.

Gebruik een volledig gekwalificeerde doelnaam omdat korte namen niet worden ondersteund in forests.

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]

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

[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.

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 (Kerberos) ontvangt deze aanwijzer de nieuwe contextnaam. 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.

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 is raadzaam dat het beveiligingspakket deze waarde altijd in lokale tijd retourneert. Omdat deze parameter optioneel is, NULL moet deze worden doorgegeven voor klanten 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 (Kerberos) 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 (Kerberos).
4. AcceptSecurityContext (Kerberos) kan een token retourneren dat door de server naar de client wordt verzonden voor een tweede aanroep naar InitializeSecurityContext (Kerberos) 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 (Kerberos) opnieuw aan, waarbij phContext is ingesteld op de handle die is geretourneerd van de laatste aanroep. Het token dat van de server is ontvangen, wordt geleverd in de parameter pInput .
4. Gebruik de waarde phContext niet in gelijktijdige aanroepen naar InitializeSecurityContext (Kerberos). De implementatie in de beveiligingsproviders is niet thread-safe.

Als de server met succes heeft gereageerd, wordt het beveiligingspakket weer 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 SEC_E_OK is, wordt er geen tweede Kerberos-aanroep (InitializeSecurityContext) weergegeven en wordt er geen reactie van de server verwacht. Als de retourcode SEC_I_CONTINUE_NEEDED is, verwacht de client een token als reactie van de server en geeft deze in een tweede aanroep door aan InitializeSecurityContext (Kerberos). 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 (Kerberos) slaagt bij de eerste (of enige) aanroep, moet de aanroeper uiteindelijk de functie DeleteSecurityContext aanroepen op de geretourneerde handle, zelfs als de aanroep mislukt op een later deel van de verificatie-uitwisseling.

De client kan InitializeSecurityContext (Kerberos) 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.

Behoeften

Zie ook

SSPI-functies

AcceptSecurityContext (Kerberos)

AcquireCredentialsHandle (Kerberos)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc