Fonction InitializeSecurityContext (General)

Article
10/20/2023

La fonction InitializeSecurityContext (General) 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 (General) retourne un jeton que le client doit transmettre à l’homologue distant, que celui-ci soumet à son tour à l’implémentation de sécurité locale via l’appel à AcceptSecurityContext (General). Le jeton généré doit être considéré comme opaque par tous les appelants.

En règle générale, la fonction InitializeSecurityContext (General) 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 SSP (Security Support Provider) spécifique, consultez les rubriques suivantes.

Rubrique	Description
InitializeSecurityContext (CredSSP)	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é CredSSP (Credential Security Support Provider).
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)	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é 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

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 (General). Ce handle est utilisé pour générer le contexte de sécurité. La fonction InitializeSecurityContext (General) nécessite au moins des informations d’identification SORTANTES.

phContext[in, optional]

Pointeur vers une structure CtxtHandle. Lors du premier appel à InitializeSecurityContext (General), ce pointeur est 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 fournisseur SSP Microsoft Digest, et peut être défini sur NULL.

En cas d’utilisation du fournisseur SSP Schannel, lors du premier appel à InitializeSecurityContext (General), spécifiez NULL. Lors des appels ultérieurs, spécifiez le jeton reçu dans le paramètre phNewContext après le premier appel à cette fonction.

Avertissement

N’utilisez pas le même handle de contexte dans des appels simultanés à InitializeSecurityContext (General). L’implémentation de l’API dans les fournisseurs de services de sécurité n’est pas thread-safe.

pTargetName[in, optional]

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

Fournisseur SSP utilisé	Signification
Digest	Chaîne terminée par un caractère 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 pouvoir être représentée par le jeu de codes ASCII US. L’encodage-pourcent peut être utilisé pour représenter des caractères en dehors du jeu de codes ASCII US.
Kerberos ou Negotiate	Nom du principal de service (SPN) ou contexte de sécurité du serveur de destination.
NTLM	Nom du principal de service (SPN) ou contexte de sécurité du serveur de destination.
Schannel/SSL	Chaîne terminée par un caractère Null qui identifie de façon 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 : - Le nom cible est identique. - L’entrée du cache n’a pas expiré. - Le processus d’application qui appelle la fonction est identique. - La session de connexion est identique. - Le handle d’informations d’identification est identique.

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 l’un ou plusieurs des indicateurs d’attributs suivants.

Valeur	Signification
ISC_REQ_ALLOCATE_MEMORY	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.
ISC_REQ_CONFIDENTIALITY	Chiffrer les messages à l’aide de la fonction EncryptMessage.
ISC_REQ_CONNECTION	Le contexte de sécurité ne gère pas les messages de mise en forme. Cette valeur est la valeur par défaut pour les délégations contraintes Kerberos, Negotiate et NTLM.
ISC_REQ_DELEGATE	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.
ISC_REQ_EXTENDED_ERROR	Lorsque des erreurs se produisent, la partie distante est avertie.
ISC_REQ_HTTP	Utiliser Digest pour HTTP. Omettez cet indicateur pour utiliser Digest comme mécanisme SASL.
ISC_REQ_INTEGRITY	Signer les messages et vérifier les signatures à l’aide des fonctions EncryptMessage et MakeSignature.
ISC_REQ_MANUAL_CRED_VALIDATION	Schannel ne doit pas authentifier automatiquement le serveur.
ISC_REQ_MUTUAL_AUTH	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 uniquement que la stratégie d’authentification du service est satisfaite. Pour être certain que l’authentification mutuelle soit effectuée, appelez la fonction QueryContextAttributes (General).
ISC_REQ_NO_INTEGRITY	Si cet indicateur est défini, l’indicateur ISC_REQ_INTEGRITY est ignoré. Cette valeur est prise en charge uniquement par les délégations contraintes Negotiate et Kerberos.
ISC_REQ_REPLAY_DETECT	Détecter les messages relus qui ont été encodés à l’aide des fonctions EncryptMessage ou MakeSignature.
ISC_REQ_SEQUENCE_DETECT	Détecter les messages reçus hors séquence.
ISC_REQ_STREAM	Prendre en charge une connexion orientée flux.
ISC_REQ_USE_SESSION_KEY	Une nouvelle clé de session doit être négociée. Cette valeur est prise en charge uniquement par la délégation contrainte Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS	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 Conditions requises pour le contexte.

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

pInput[in, optional]

Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers les mémoires tampons fournies comme entrée du package. La valeur de ce paramètre doit être NULL lors du premier appel à la fonction, sauf si le contexte client a été lancé par le serveur. 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 (General), 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.

pOutput[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 comme SEC_READWRITE dans l’entrée, elle sera là lors de la sortie. Le système allouera une mémoire tampon pour le jeton de sécurité si cela est demandé (via ISC_REQ_ALLOCATE_MEMORY) et renseignera l’adresse dans le descripteur de mémoire tampon pour le jeton de sécurité.

Lors de l’utilisation du fournisseur SSP Microsoft Digest, ce paramètre reçoit la réponse au défi qui doit être envoyée au serveur.

Lors de l’utilisation du fournisseur SSP Schannel, si l’indicateur ISC_REQ_ALLOCATE_MEMORY est spécifié, le fournisseur 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 transmettre 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.

pfContextAttr[out]

Pointeur vers une variable devant 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, par exemple 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 retourné une réussite. Les indicateurs d’attributs 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.

Remarque

Des attributs de contexte particuliers peuvent changer lors de la négociation avec un homologue distant.

ptsExpiry[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 en heure locale. Ce paramètre est facultatif, et NULL doit être transmis pour les clients à courte durée de vie.

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

Valeur retournée

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

Code de retour	Description
SEC_I_COMPLETE_AND_CONTINUE	Le client doit appeler CompleteAuthToken, puis transmettre la sortie au serveur. Le client attend ensuite un jeton retourné et le transmet, dans un autre appel, à InitializeSecurityContext (General).
SEC_I_COMPLETE_NEEDED	Le client doit terminer la génération du message, puis appeler la fonction CompleteAuthToken.
SEC_I_CONTINUE_NEEDED	Le client doit envoyer le jeton de sortie au serveur et attendre un jeton de retour. Le jeton retourné est ensuite transmis dans un autre appel à InitializeSecurityContext (General). Le jeton de sortie peut être vide.
SEC_I_INCOMPLETE_CREDENTIALS	Utilisé avec Schannel. Le serveur a demandé l’authentification du client, et soit les informations d’identification fournies n’incluent pas de certificat, soit 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.
SEC_E_INCOMPLETE_MESSAGE	Utilisé avec Schannel. Les données du message entier n’ont pas été lues sur le câble. Lorsque cette valeur est retournée, la mémoire tampon pInput contient une structure SecBuffer avec un membre BufferType égal à 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 les appels multiples à cette fonction.
SEC_E_OK	Le contexte de sécurité a été initialisé avec succès. Un autre appel àInitializeSecurityContext (General) n’est pas nécessaire. Si la fonction retourne un jeton de sortie, autrement dit si SECBUFFER_TOKEN dans pOutput a une longueur différente de zéro, ce jeton doit être envoyé au serveur.

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

Code de retour	Description
SEC_E_INSUFFICIENT_MEMORY	La mémoire disponible est insuffisante pour terminer l’action demandée.
SEC_E_INTERNAL_ERROR	Une erreur non mappée à un code d’erreur SSPI s’est produite.
SEC_E_INVALID_HANDLE	Le handle transmis à la fonction n’est pas valide.
SEC_E_INVALID_TOKEN	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 transmis dans le package de sécurité incorrect. La transmission d’un jeton au package incorrect peut se produire si le client et le serveur n’ont pas négocié le package de sécurité approprié.
SEC_E_LOGON_DENIED	L’ouverture de session a échoué.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Aucune autorité n’a pu être contactée pour l’authentification. Le nom de domaine de la partie d’authentification est peut-être incorrect, le domaine est peut-être inaccessible, ou il peut y avoir eu un échec de relation d’approbation.
SEC_E_NO_CREDENTIALS	Aucune information d’identification n’est disponible dans le package de sécurité.
SEC_E_TARGET_UNKNOWN	La cible n’a pas été reconnue.
SEC_E_UNSUPPORTED_FUNCTION	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.
SEC_E_WRONG_PRINCIPAL	Le principal qui a reçu la demande d’authentification n’est pas le même que celui transmis dans le paramètre pszTargetName. Cela indique un échec lors de l’authentification mutuelle.

Notes

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 de rompre 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 (General) est utilisée par un client pour initialiser un contexte sortant.

Pour un contexte de sécurité à deux phases, la séquence d’appels 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, 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.
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 (General).
AcceptSecurityContext (General) peut retourner un jeton, que le serveur envoie au client pour un deuxième appel à InitializeSecurityContext (General) si le premier appel a retourné SEC_I_CONTINUE_NEEDED.

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

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.
Lors de la réception de la réponse du serveur, le client appelle à nouveau InitializeSecurityContext (General), avec phContext défini sur le handle retourné lors du dernier appel. Le jeton reçu du serveur est fourni dans le paramètre pInput.
N’utilisez pas la valeur phContext dans des appels simultanés à InitializeSecurityContext (General). 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 lors de n’importe quel retour avec réussite, mais ce n’est que lors du dernier retour avec réussite que vous devez examiner les indicateurs relatifs 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 autorise 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 pourrait être le défi d’un LAN Manager. Dans ce cas, le jeton de sortie serait la réponse au défi chiffrée par NTLM.

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 a pas de deuxième appel InitializeSecurityContext (General) 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 (General). 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 (General) retourne avec succès lors du premier (ou unique) appel, l’appelant doit au final appeler la fonction DeleteSecurityContext sur le handle retourné, même si l’appel échoue durant une phase ultérieure de l’échange d’authentification.

Le client peut appeler InitializeSecurityContext (General) une nouvelle fois après la réussite. 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 dans la mémoire virtuelle à l’aide de VirtualAlloc ; elle ne doit pas être allouée à partir du pool. Les mémoires tampons transmises et fournies dans pInput et pOutput doivent être dans la mémoire virtuelle, et non dans le pool.

Lorsque vous utilisez le fournisseur 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 (General). 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 (General) et spécifiez l’attribut SECPKG_ATTR_ISSUER_LIST_EX.

Lorsque vous utilisez le fournisseur SSP Schannel, après 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 (General), puis en appelant à nouveau InitializeSecurityContext (General), en spécifiant les nouvelles informations d’identification dans le paramètre phCredential.

Spécifications

Condition requise	Value
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
En-tête	Sspi.h (inclure Security.h)
Bibliothèque	Secur32.lib
DLL	Secur32.dll
Noms Unicode et ANSI	InitializeSecurityContextW (Unicode) et InitializeSecurityContextA (ANSI)