Fonction InitializeSecurityContextW (sspi.h)
La fonction InitializeSecurityContext (Général) initie le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification. La fonction est utilisée pour créer 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 à son tour envoie à 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é (SSP) spécifique, consultez les rubriques suivantes.
| Rubrique | Description |
|---|---|
| InitializeSecurityContext (CredSSP) | Initie le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du fournisseur de support de sécurité des informations d’identification (CredSSP). |
| InitializeSecurityContext (Digest) | Lance le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du package de sécurité Digest. |
| InitializeSecurityContext (Kerberos) | Lance le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du package de sécurité Kerberos. |
| InitializeSecurityContext (Negotiate) | Initie le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du package de sécurité Negotiate. |
| InitializeSecurityContext (NTLM) | Lance le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du package de sécurité NTLM. |
| InitializeSecurityContext (Schannel) | Lance le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification à l’aide du package de sécurité Schannel. |
Syntaxe
KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY InitializeSecurityContextW(
[in, optional] PCredHandle phCredential,
[in, optional] PCtxtHandle phContext,
[in, optional] PSECURITY_STRING pTargetName,
[in] unsigned long fContextReq,
[in] unsigned long Reserved1,
[in] unsigned long TargetDataRep,
[in, optional] PSecBufferDesc pInput,
[in] unsigned long Reserved2,
[in, out, optional] PCtxtHandle phNewContext,
[in, out, optional] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Paramètres
[in, optional] phCredential
Handle des 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.
[in, optional] phContext
Pointeur vers une structure CtxtHandle . Lors du premier appel à InitializeSecurityContext (Général), ce pointeur a la valeur NULL. Lors du 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 fournisseur 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.
[in, optional] pTargetName
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 SSP système supplémentaires et des SSP tiers peuvent être ajoutés à un système.
| Fournisseur de services partagés en cours d’utilisation | Signification |
|---|---|
|
Chaîne terminée par null qui identifie de manière unique l’URI de la ressource demandée. La chaîne doit être composée de caractères autorisés dans un URI et doit être représentée par le jeu de code US ASCII. L’encodage en pourcentage peut être utilisé pour représenter des caractères en dehors du jeu de codes US ASCII. |
|
Nom du principal du service (SPN) ou contexte de sécurité du serveur de destination. |
|
Nom du principal du service (SPN) ou contexte de sécurité du serveur de destination. |
|
Chaîne terminée par null qui identifie de manière unique le serveur cible. Schannel utilise cette valeur pour vérifier le certificat de serveur. Schannel utilise également cette valeur pour localiser la session dans le cache de session lors du rétablissement d’une connexion. La session mise en cache est utilisée uniquement si toutes les conditions suivantes sont remplies :
|
[in] fContextReq
Indicateurs de bits qui indiquent les demandes 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écédés d’ISC_REQ_, par exemple, ISC_REQ_DELEGATE. Ce paramètre peut être un ou plusieurs des indicateurs d’attributs suivants.
| Valeur | Signification |
|---|---|
|
Le package de sécurité alloue des mémoires tampons de sortie pour vous. Lorsque vous avez terminé d’utiliser les mémoires tampons de sortie, libérez-les en appelant la fonction FreeContextBuffer . |
|
Chiffrez les messages à l’aide de la fonction EncryptMessage . |
|
Le contexte de sécurité ne gère pas la mise en forme des messages. Cette valeur est la valeur par défaut pour les packages de sécurité Kerberos, Negotiate et NTLM. |
|
Le serveur peut utiliser le contexte pour s’authentifier auprès d’autres serveurs en tant que client. L’indicateur ISC_REQ_MUTUAL_AUTH doit être défini pour que cet indicateur fonctionne. Valide pour Kerberos. Ignorez cet indicateur pour la délégation contrainte. |
|
Lorsque des erreurs se produisent, la partie distante est avertie. |
|
Utilisez Digest pour HTTP. Omettez cet indicateur pour utiliser Digest comme mécanisme SASL. |
|
Signez des messages et vérifiez les signatures à l’aide des fonctions EncryptMessage et MakeSignature . |
|
Schannel ne doit pas authentifier le serveur automatiquement. |
|
La stratégie d’authentification mutuelle du service sera satisfaite.
Attention Cela ne signifie pas nécessairement que l’authentification mutuelle est effectuée, mais seulement que la stratégie d’authentification du service est satisfaite. Pour vous assurer que l’authentification mutuelle est effectuée, appelez la fonction QueryContextAttributes (Général).
|
|
Si cet indicateur est défini, l’indicateur ISC_REQ_INTEGRITY est ignoré.
Cette valeur est prise en charge uniquement par les packages de sécurité Negotiate et Kerberos. |
|
Détectez les messages relus qui ont été encodés à l’aide des fonctions EncryptMessage ou MakeSignature . |
|
Détecter les messages reçus hors séquence. |
|
Prise en charge d’une connexion orientée flux. |
|
Une nouvelle clé de session doit être négociée.
Cette valeur est prise en charge uniquement par le package de sécurité Kerberos. |
|
Schannel ne doit pas tenter de fournir automatiquement des informations d’identification pour le client. |
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 Configuration requise pour le contexte.
[in] Reserved1
Ce paramètre est réservé et doit être défini sur zéro.
[in] TargetDataRep
Représentation des données, telle que l’ordre des 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.
[in, optional] pInput
Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers les mémoires tampons fournies en tant qu’entrée du package. Sauf si le contexte client a été initié par le serveur, la valeur de ce paramètre doit être NULL lors du 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.
[in] Reserved2
Ce paramètre est réservé et doit être défini sur zéro.
[in, out, optional] phNewContext
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 .
Lors de l’utilisation du SSP Schannel, lors des appels après le premier appel, transmettez le handle retourné ici en tant que paramètre phContext et spécifiez NULL pour phNewContext.
[in, out, optional] pOutput
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 comme SEC_READWRITE dans l’entrée, elle sera là lors de la 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 fournisseur de services partagés Microsoft Digest, ce paramètre reçoit la réponse de demande qui doit être envoyée au serveur.
Lors de l’utilisation du 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. Lors de la sortie, si une alerte est générée, cette mémoire tampon contient des informations sur cette alerte et la fonction échoue.
[out] pfContextAttr
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 Configuration requise du contexte.
Les indicateurs utilisés pour ce paramètre sont précédés de ISC_RET, comme ISC_RET_DELEGATE.
Pour obtenir la liste des valeurs valides, consultez le paramètre fContextReq .
Ne case activée pas pour les attributs liés à la sécurité tant que l’appel de fonction final n’est pas retourné. 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.
[out, optional] ptsExpiry
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 en heure locale. Ce paramètre est facultatif et NULL doit être transmis pour les clients de courte durée.
Il n’existe aucun délai d’expiration pour les contextes de sécurité ou les informations d’identification du fournisseur de services partagés Microsoft Digest.
Valeur retournée
Si la fonction réussit, la fonction retourne l’un des codes de réussite suivants.
| Code de retour | Description |
|---|---|
|
Le client doit appeler CompleteAuthToken , puis passer la sortie au serveur. Le client attend ensuite un jeton retourné et le transmet, dans un autre appel, à InitializeSecurityContext (Général). |
|
Le client doit terminer la génération du message, puis appeler la fonction CompleteAuthToken . |
|
Le client doit envoyer le jeton de sortie au serveur et attendre un jeton de retour. Le jeton retourné est ensuite passé dans un autre appel à InitializeSecurityContext (Général). Le jeton de sortie peut être vide. |
|
Utilisez avec Schannel. Le serveur a demandé l’authentification du client et les informations d’identification fournies n’incluent pas de certificat ou le certificat n’a pas été émis par une autorité de certification approuvée par le serveur. Pour plus d'informations, consultez la section Notes. |
|
Utilisez avec Schannel. Les données de l’ensemble du message n’ont pas été lues à partir du réseau.
Lorsque cette valeur est retournée, la mémoire tampon pInput contient une structure SecBuffer avec un membre BufferTypede SECBUFFER_MISSING. Le membre cbBuffer de SecBuffer contient une valeur qui indique le nombre d’octets supplémentaires que la fonction doit lire à partir du client avant que cette fonction réussisse. Bien que ce nombre ne soit pas toujours précis, son utilisation peut aider à améliorer les performances en évitant plusieurs appels à cette fonction. |
|
Le contexte de sécurité a été initialisé avec succès. Il n’est pas nécessaire d’effectuer un autre appel InitializeSecurityContext (Général). Si la fonction retourne un jeton de sortie, c’est-à-dire si le SECBUFFER_TOKEN dans pOutput est d’une longueur différente de zéro, ce jeton doit être envoyé au serveur. |
Si la fonction échoue, la fonction retourne l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
|
La mémoire disponible est insuffisante pour effectuer l’action demandée. |
|
Une erreur qui n’a pas été mappée à un code d’erreur SSPI s’est produite. |
|
Le handle passé à la fonction n’est pas valide. |
|
L’erreur est due à un jeton d’entrée mal formé, tel qu’un jeton endommagé en transit, un jeton de taille incorrecte ou un jeton passé dans le package de sécurité incorrect. La transmission d’un jeton au mauvais package peut se produire si le client et le serveur n’ont pas négocié le package de sécurité approprié. |
|
Échec de l’ouverture de session. |
|
Aucune autorité n’a pu être contactée pour l’authentification. Le nom de domaine de la partie qui s’authentifie peut être incorrect, le domaine peut être inaccessible ou une relation d’approbation a peut-être échoué. |
|
Aucune information d’identification n’est disponible dans le package de sécurité. |
|
La cible n’a pas été reconnue. |
|
Un indicateur d’attribut de contexte non valide (ISC_REQ_DELEGATE ou ISC_REQ_PROMPT_FOR_CREDS) a été spécifié dans le paramètre fContextReq . |
|
Le principal qui a reçu la demande d’authentification n’est pas le même que celui passé dans le paramètre pszTargetName . Cela indique un échec de l’authentification mutuelle. |
Remarques
L’appelant est chargé 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 étapes, la séquence d’appel est la suivante :
- 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.
- Le package de sécurité examine les paramètres et construit un jeton opaque, en le plaçant dans l’élément TOKEN du 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.
- 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).
- 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.
- Le client appelle la fonction comme décrit précédemment, mais le package retourne le code de réussite SEC_I_CONTINUE_NEEDED.
- Le client envoie le jeton de sortie au serveur et attend la réponse du serveur.
- À 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é par le dernier appel. Le jeton reçu du serveur est fourni dans le paramètre pInput .
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 et 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 Configuration requise du contexte. Le paramètre pfContextAttributes est valide sur tout retour réussi, mais uniquement sur le retour final réussi si vous examinez les indicateurs qui se rapportent aux aspects de sécurité du contexte. Les retours 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 DE RÉSEAU. Dans ce cas, le jeton de sortie serait 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 (ou le seul) appel, l’appelant doit finalement appeler la fonction DeleteSecurityContext sur le handle retourné, même si l’appel échoue sur une étape ultérieure de l’échange d’authentification.
Le client peut appeler à nouveau InitializeSecurityContext (Général) une fois l’opération terminée. Cela indique au package de sécurité qu’une réauthentification est souhaitée.
Les appelants en mode noyau présentent 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, case activée 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.
Lors de l’utilisation du SSP Schannel, une fois qu’une application cliente a reçu 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 .
Notes
L’en-tête sspi.h définit InitializeSecurityContext comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | sspi.h (include Security.h) |
| Bibliothèque | Secur32.lib |
| DLL | Secur32.dll |
Voir aussi
AcceptSecurityContext (Général)