InitializeSecurityContext (Général) , fonction

La fonction InitializeSecurityContext (Général) lance le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification. La fonction est utilisée pour générer un contexte de sécurité entre l’application cliente et un homologue distant. InitializeSecurityContext (Général) retourne un jeton que le client doit passer à l’homologue distant, que l’homologue envoie à son tour à l’implémentation de sécurité locale via l’appel AcceptSecurityContext (Général). Le jeton généré doit être considéré comme opaque par tous les appelants.

En règle générale, la fonction InitializeSecurityContext (Général) est appelée dans une boucle jusqu’à ce qu’un contexte de sécurité suffisant soit établi.

Pour plus d’informations sur l’utilisation de cette fonction avec un fournisseur de support de sécurité spécifique (SSP), consultez les rubriques suivantes.

Syntaxe

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

Paramètres

phCredential[in, optional]

Handle pour les informations d’identification retournées par AcquireCredentialsHandle (Général). Ce handle est utilisé pour générer le contexte de sécurité. La fonction InitializeSecurityContext (Général) nécessite au moins des informations d’identification SORTANTes.

phContext[in, optional]

Pointeur vers une structure CtxtHandle. Lors du premier appel à InitializeSecurityContext (Général),ce pointeur est NULL. Sur le deuxième appel, ce paramètre est un pointeur vers le handle vers le contexte partiellement formé retourné dans le paramètre phNewContext par le premier appel.

Ce paramètre est facultatif avec le SSP Microsoft Digest et peut être défini sur NULL.

Lors de l’utilisation du SSP Schannel, lors du premier appel à InitializeSecurityContext (Général), spécifiez NULL. Lors des appels futurs, spécifiez le jeton reçu dans le paramètre phNewContext après le premier appel à cette fonction.

pTargetName[in, optional]

Pointeur vers une chaîne terminée par null qui indique la cible du contexte. Le contenu de la chaîne est spécifique au package de sécurité , comme décrit dans le tableau suivant. Cette liste n’est pas exhaustive. Des fournisseurs SSP système supplémentaires et des fournisseurs de services SSP tiers peuvent être ajoutés à un système.

fContextReq[in]

Indicateurs de bits qui indiquent les requêtes pour le contexte. Tous les packages ne peuvent pas prendre en charge toutes les exigences. Les indicateurs utilisés pour ce paramètre sont préfixés par ISC_REQ_, par exemple, ISC_REQ_DELEGATE. Ce paramètre peut être un ou plusieurs des indicateurs d’attributs suivants.

Les attributs demandés peuvent ne pas être pris en charge par le client. Pour plus d’informations, consultez le paramètre pfContextAttr.

Pour obtenir des descriptions supplémentaires des différents attributs, consultez Conditions requises pour le contexte.

Réservé1[in]

Ce paramètre est réservé et doit être défini sur zéro.

TargetDataRep[in]

Représentation des données, telle que l’ordre d’octets, sur la cible. Ce paramètre peut être SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

Ce paramètre n’est pas utilisé avec Digest ou Schannel. Définissez-le sur zéro.

pEntrée[in, optional]

Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers les mémoires tampons fournies comme entrée du package. Sauf si le contexte client a été initié par le serveur, la valeur de ce paramètre doit être NULL sur le premier appel à la fonction. Lors des appels ultérieurs à la fonction ou lorsque le contexte client a été lancé par le serveur, la valeur de ce paramètre est un pointeur vers une mémoire tampon allouée avec suffisamment de mémoire pour contenir le jeton retourné par l’ordinateur distant.

Réservé2[in]

Ce paramètre est réservé et doit être défini sur zéro.

phNewContext[in, out, optional]

Pointeur vers une structure CtxtHandle. Lors du premier appel à InitializeSecurityContext (Général), ce pointeur reçoit le nouveau handle de contexte. Lors du deuxième appel, phNewContext peut être identique au handle spécifié dans le paramètre phContext . phNewContext ne doit jamais être NULL.

pSortie[in, out, optional]

Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers la structure SecBuffer qui reçoit les données de sortie. Si une mémoire tampon a été tapée en tant que SEC_READWRITE dans l’entrée, elle y sera en sortie. Le système alloue une mémoire tampon pour le jeton de sécurité si demandé (via ISC_REQ_ALLOCATE_MEMORY) et renseigne l’adresse dans le descripteur de mémoire tampon pour le jeton de sécurité.

Lorsque vous utilisez le SSP Microsoft Digest, ce paramètre reçoit la réponse de défi qui doit être envoyée au serveur.

Lorsque vous utilisez le SSP Schannel, si l’indicateur ISC_REQ_ALLOCATE_MEMORY est spécifié, le SSP Schannel alloue de la mémoire pour la mémoire tampon et place les informations appropriées dans secBufferDesc. En outre, l’appelant doit passer une mémoire tampon de type SECBUFFER_ALERT. En sortie, si une alerte est générée, cette mémoire tampon contient des informations sur cette alerte et la fonction échoue.

pfContextAttr[out]

Pointeur vers une variable pour recevoir un ensemble d’indicateurs de bits qui indiquent les attributs du contexte établi. Pour obtenir une description des différents attributs, consultez Conditions requises pour le contexte.

Les indicateurs utilisés pour ce paramètre sont précédés de ISC_RET, tels que ISC_RET_DELEGATE. Pour obtenir la liste des valeurs valides, consultez le paramètre fContextReq .

Ne vérifiez pas les attributs liés à la sécurité tant que l’appel de fonction final n’a pas renvoyé une réussite. Les indicateurs d’attribut qui ne sont pas liés à la sécurité, tels que l’indicateur ASC_RET_ALLOCATED_MEMORY, peuvent être vérifiés avant le retour final.

ptsExpiration[out, optional]

Pointeur vers une structure TimeStamp qui reçoit l’heure d’expiration du contexte. Il est recommandé que le package de sécurité retourne toujours cette valeur dans l’heure locale. Ce paramètre est facultatif et NULL doit être passé pour les clients de courte durée.

Il n’y a pas de délai d’expiration pour les informations d’identification ou les contextes de sécuritédu fournisseur de services partagés Microsoft Digest.

Valeur de retour

Si la fonction réussit, la fonction retourne l’un des codes de réussite suivants.

Si la fonction échoue, la fonction retourne l’un des codes d’erreur suivants.

Remarques

Il est de la responsabilité de l’appelant de déterminer si les attributs de contexte finaux sont suffisants. Si, par exemple, la confidentialité a été demandée, mais n’a pas pu être établie, certaines applications peuvent choisir d’arrêter la connexion immédiatement.

Si les attributs du contexte de sécurité ne sont pas suffisants, le client doit libérer le contexte partiellement créé en appelant la fonction DeleteSecurityContext .

La fonction InitializeSecurityContext (Général) est utilisée par un client pour initialiser un contexte sortant.

Pour un contexte de sécurité à deux jambes, la séquence d’appels est la suivante :

1. Le client appelle la fonction avec phContext défini sur NULL et remplit le descripteur de mémoire tampon avec le message d’entrée.
2. Le package de sécurité examine les paramètres et construit un jeton opaque, le plaçant dans l’élément TOKEN dans le tableau de mémoires tampons. Si le paramètre fContextReq inclut l’indicateur ISC_REQ_ALLOCATE_MEMORY, le package de sécurité alloue la mémoire et retourne le pointeur dans l’élément TOKEN.
3. Le client envoie le jeton retourné dans la mémoire tampon pOutput au serveur cible. Le serveur transmet ensuite le jeton en tant qu’argument d’entrée dans un appel à la fonction AcceptSecurityContext (Général).
4. AcceptSecurityContext (Général) peut retourner un jeton, que le serveur envoie au client pour un deuxième appel à InitializeSecurityContext (Général) si le premier appel a retourné SEC_I_CONTINUE_NEEDED.

Pour les contextes de sécuritéà plusieurs jambes, tels que l’authentification mutuelle, la séquence d’appels est la suivante :

1. Le client appelle la fonction comme décrit précédemment, mais le package retourne le code de réussite SEC_I_CONTINUE_NEEDED.
2. Le client envoie le jeton de sortie au serveur et attend la réponse du serveur.
3. Lors de la réception de la réponse du serveur, le client appelle à nouveau InitializeSecurityContext (Général), avec phContext défini sur le handle retourné à partir du dernier appel. Le jeton reçu du serveur est fourni dans le paramètre pInput .
4. N’utilisez pas la valeur phContext dans les appels simultanés à InitializeSecurityContext (Général). L’implémentation dans les fournisseurs de sécurité n’est pas thread-safe.

Si le serveur a répondu correctement, le package de sécurité retourne SEC_E_OK et une session sécurisée est établie.

Si la fonction retourne l’une des réponses d’erreur, la réponse du serveur n’est pas acceptée et la session n’est pas établie.

Si la fonction retourne SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED ou SEC_I_COMPLETE_AND_CONTINUE, les étapes 2 et 3 sont répétées.

Pour initialiser un contexte de sécurité, plusieurs appels à cette fonction peuvent être nécessaires, en fonction du mécanisme d’authentification sous-jacent, ainsi que des choix spécifiés dans le paramètre fContextReq .

Les paramètres fContextReq et pfContextAttributes sont des masques de bits qui représentent différents attributs de contexte. Pour obtenir une description des différents attributs, consultez Conditions requises pour le contexte. Le paramètre pfContextAttributes est valide sur n’importe quel retour réussi, mais uniquement sur le retour réussi final si vous examinez les indicateurs relatifs aux aspects de sécurité du contexte. Les renvois intermédiaires peuvent définir, par exemple, l’indicateur ISC_RET_ALLOCATED_MEMORY.

Si l’indicateur ISC_REQ_USE_SUPPLIED_CREDS est défini, le package de sécurité doit rechercher un type de mémoire tampon SECBUFFER_PKG_PARAMS dans la mémoire tampon d’entrée pInput . Il ne s’agit pas d’une solution générique, mais elle permet un appairage fort du package de sécurité et de l’application, le cas échéant.

Si ISC_REQ_ALLOCATE_MEMORY a été spécifié, l’appelant doit libérer la mémoire en appelant la fonction FreeContextBuffer .

Par exemple, le jeton d’entrée peut être le défi d’un gestionnaire LAN. Dans ce cas, le jeton de sortie est la réponse chiffrée par NTLM au défi.

L’action effectuée par le client dépend du code de retour de cette fonction. Si le code de retour est SEC_E_OK, il n’y aura pas de deuxième appel InitializeSecurityContext (Général) et aucune réponse du serveur n’est attendue. Si le code de retour est SEC_I_CONTINUE_NEEDED, le client attend un jeton en réponse du serveur et le transmet dans un deuxième appel à InitializeSecurityContext (Général). Le code de retour SEC_I_COMPLETE_NEEDED indique que le client doit terminer la génération du message et appeler la fonction CompleteAuthToken . Le code SEC_I_COMPLETE_AND_CONTINUE intègre ces deux actions.

Si InitializeSecurityContext (Général) retourne la réussite sur le premier appel (ou uniquement), l’appelant doit finalement appeler la fonction DeleteSecurityContext sur le handle retourné, même si l’appel échoue à une étape ultérieure de l’échange d’authentification.

Le client peut appeler InitializeSecurityContext (Général) une fois qu’il a réussi. Cela indique au package de sécurité qu’une réauthentification est souhaitée.

Les appelants en mode noyau ont les différences suivantes : le nom cible est une chaîne Unicode qui doit être allouée en mémoire virtuelle à l’aide de VirtualAlloc ; il ne doit pas être alloué à partir du pool. Les mémoires tampons passées et fournies dans pInput et pOutput doivent être en mémoire virtuelle, et non dans le pool.

Lorsque vous utilisez le SSP Schannel, si la fonction retourne SEC_I_INCOMPLETE_CREDENTIALS, vérifiez que vous avez spécifié un certificat valide et approuvé dans vos informations d’identification. Le certificat est spécifié lors de l’appel de la fonction AcquireCredentialsHandle (Général). Le certificat doit être un certificat d’authentification client émis par une autorité de certification approuvée par le serveur. Pour obtenir la liste des autorités de certification approuvées par le serveur, appelez la fonction QueryContextAttributes (Général) et spécifiez l’attribut SECPKG_ATTR_ISSUER_LIST_EX.

Lorsque vous utilisez le SSP Schannel, une fois qu’une application cliente reçoit un certificat d’authentification d’une autorité de certification approuvée par le serveur, l’application crée des informations d’identification en appelant la fonction AcquireCredentialsHandle (Général), puis en appelant à nouveau InitializeSecurityContext (Général), en spécifiant les nouvelles informations d’identification dans le paramètre phCredential .

Spécifications

Voir aussi

Fonctions SSPI

Prise en charge de la protection étendue pour l’authentification (EPA) dans un service

AcceptSecurityContext (Général)

AcquireCredentialsHandle (Général)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc