Fonction InitializeSecurityContext (CredSSP)

Article
03/18/2023

La fonction InitializeSecurityContext (CredSSP) initie le contexte de sécurité sortant côté client à partir d’un handle d’informations d’identification. La fonction génère un contexte de sécurité entre l’application cliente et un homologue distant. InitializeSecurityContext (CredSSP) retourne un jeton que le client doit passer à l’homologue distant ; l’homologue envoie à son tour ce jeton à l’implémentation de sécurité locale via l’appel AcceptSecurityContext (CredSSP). Le jeton généré doit être considéré comme opaque par tous les appelants.

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

Syntaxe

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

Paramètres

phCredential[in, optional]

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

phContext[in, optional]

Pointeur vers une structure CtxtHandle . Lors du premier appel à InitializeSecurityContext (CredSSP), 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.

Lors du premier appel à InitializeSecurityContext (CredSSP), 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 les appels simultanés à InitializeSecurityContext (CredSSP). 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 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 de la cible est le même.
L’entrée du cache n’a pas expiré.
Le processus d’application qui appelle la fonction est le même.
La session d’ouverture de session est la même.
Le handle d’informations d’identification est le même.

fContextReq[in]

Indicateurs de bits qui indiquent des 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éfixés par ISC_REQ_, par exemple, ISC_REQ_DELEGATE.

Ce paramètre peut être un ou plusieurs des indicateurs d’attributs suivants.

Valeur	Signification
ISC_REQ_ALLOCATE_MEMORY `0x100`	Le package de sécurité alloue des mémoires tampons de sortie pour l’appelant. Lorsque vous avez terminé d’utiliser les mémoires tampons de sortie, libérez-les en appelant la fonction FreeContextBuffer .
ISC_REQ_CONNECTION `0x800`	Le contexte de sécurité ne gère pas la mise en forme des messages.
ISC_REQ_EXTENDED_ERROR `0x4000`	Lorsque des erreurs se produisent, la partie distante est avertie.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	Le fournisseur de support de sécurité des informations d’identification (CredSSP) ne doit pas authentifier automatiquement le serveur. Cet indicateur est toujours défini lors de l’utilisation de CredSSP.
ISC_REQ_SEQUENCE_DETECT `0x8`	Détecter les messages reçus hors séquence.
ISC_REQ_STREAM `0x8000`	Prise en charge d’une connexion orientée flux.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP ne doit pas tenter de fournir automatiquement des informations d’identification pour le client.
ISC_REQ_DELEGATE `0x1`	Indique que les informations d’identification de l’utilisateur doivent être déléguées au serveur. Si cet indicateur n’est pas spécifié, un ensemble vide d’informations d’identification est délégué au serveur. Windows Server 2008 et Windows Vista : Cet indicateur est obligatoire.
ISC_REQ_MUTUAL_AUTH `0x2`	Indique que l’authentification du serveur n’est pas nécessaire. Les stratégies de délégation sont toujours appliquées si cet indicateur n’est pas spécifié. Windows Server 2008 et Windows Vista : Cet indicateur est ignoré.

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.

Reserved1[in]

Réservé. Ce paramètre doit être défini sur zéro.

TargetDataRep[in]

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.

pInput[in, out, optional]

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.

Lors des appels à cette fonction après l’appel initial, il doit y avoir deux mémoires tampons. Le premier a le type SECBUFFER_TOKEN et contient le jeton reçu du serveur. La deuxième mémoire tampon a le type SECBUFFER_EMPTY ; définissez les deux membres pvBuffer et cbBuffer sur zéro.

Reserved2[in]

Réservé. Ce paramètre doit être défini sur zéro.

phNewContext[in, out, optional]

Pointeur vers une structure CtxtHandle . Lors du premier appel à InitializeSecurityContext (CredSSP), 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[out, optional]

Pointeur vers une structure SecBufferDesc . Cette structure contient à son tour 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é.

Si l’indicateur ISC_REQ_ALLOCATE_MEMORY est spécifié, CredSSP alloue de la mémoire pour la mémoire tampon et place les informations appropriées dans secBufferDesc.

pfContextAttr[out]

Pointeur vers 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.

Notes

Des attributs de contexte particuliers peuvent changer pendant 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 passé pour les clients de courte durée.

Valeur retournée

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

Code de retour	Description
SEC_E_INCOMPLETE_MESSAGE	Les données de l’ensemble du message n’ont pas été lues à partir du câble. Lorsque cette valeur est retournée, la mémoire tampon pInput contient une structure SecBuffer avec un membre BufferType de SECBUFFER_MISSING. Le membre cbBuffer de SecBuffer spécifie 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.
SEC_E_OK	Le contexte de sécurité a été initialisé avec succès. Un autre appel InitializeSecurityContext (CredSSP) n’est pas nécessaire. 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.
SEC_I_COMPLETE_AND_CONTINUE	Le client doit appeler CompleteAuthToken , puis passer la sortie au serveur. Le client attend ensuite un jeton retourné et le passe, dans un autre appel, à InitializeSecurityContext (CredSSP).
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 client transmet le jeton retourné dans un autre appel à InitializeSecurityContext (CredSSP). Le jeton de sortie peut être vide.
SEC_I_INCOMPLETE_CREDENTIALS	Le serveur a demandé l’authentification du client, mais 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.

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

Code de retour	Description
SEC_E_INSUFFICIENT_MEMORY	La mémoire disponible est insuffisante pour effectuer l’action demandée.
SEC_E_INTERNAL_ERROR	Une erreur s’est produite qui n’a pas été mappée à un code d’erreur SSPI.
SEC_E_INVALID_HANDLE	Le handle passé à la fonction n’est pas valide.
SEC_E_INVALID_TOKEN	Le jeton d’entrée est mal formé. Les causes possibles incluent un jeton endommagé en transit, un jeton de taille incorrecte et un jeton passé dans le package de sécurité incorrect. Cette dernière condition peut se produire si le client et le serveur n’ont pas négocié le package de sécurité approprié.
SEC_E_LOGON_DENIED	Échec de l’ouverture de session.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Aucune autorité n’a pu être contactée pour l’authentification. Le nom de domaine de la partie authentifiante peut être incorrect, le domaine peut être inaccessible ou une relation d’approbation a peut-être échoué.
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	La valeur du paramètre fContextReq n’est pas valide. Un indicateur obligatoire n’a pas été spécifié ou un indicateur qui n’est pas pris en charge par CredSSP a été spécifié.
SEC_E_WRONG_PRINCIPAL	Le principal qui a reçu la demande d’authentification n’est pas le même que celui passé dans le paramètre pszTargetName . Cette erreur indique un échec de l’authentification mutuelle.
SEC_E_DELEGATION_POLICY	La stratégie ne prend pas en charge la délégation des informations d’identification au serveur cible.
SEC_E_POLICY_NLTM_ONLY	La délégation d’informations d’identification au serveur cible n’est pas autorisée lorsque l’authentification mutuelle n’est pas obtenue.
SEC_E_MUTUAL_AUTH_FAILED	L’authentification du serveur a échoué lorsque l’indicateur ISC_REQ_MUTUAL_AUTH est spécifié dans le paramètre fContextReq .

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 .

Le client appelle la fonction InitializeSecurityContext (CredSSP) pour initialiser un contexte sortant.

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

Le client appelle la fonction avec phContext défini NULL sur 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 comme argument d’entrée dans un appel à la fonction AcceptSecurityContext (CredSSP).
AcceptSecurityContext (CredSSP) peut retourner un jeton. Le serveur envoie ce jeton au client par le biais d’un deuxième appel InitializeSecurityContext (CredSSP) si le premier appel a retourné SEC_I_CONTINUE_NEEDED.

Si le serveur a répondu avec succès, 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.

L’initialisation du contexte de sécurité peut nécessiter plusieurs appels à cette fonction, 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 Configuration requise du contexte. Bien que le paramètre pfContextAttributes soit valide sur tout retour réussi, vous devez examiner les indicateurs qui se rapportent aux aspects de sécurité du contexte uniquement sur le retour final réussi. 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 . Bien qu’il ne s’agit pas d’une solution générique, elle permet une association forte 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 du 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 (CredSSP) 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 passe dans un deuxième appel à InitializeSecurityContext (CredSSP). 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 incorpore ces deux actions.

Si InitializeSecurityContext (CredSSP) retourne la réussite du premier (ou seul) appel, l’appelant doit 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 InitializeSecurityContext (CredSSP) une fois qu’il s’est terminé avec succès. 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.

Si la fonction retourne SEC_I_INCOMPLETE_CREDENTIALS, case activée que les informations d’identification r passées à la fonction AcquireCredentialsHandle (CredSSP) ont spécifié un certificat valide et approuvé 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 (CredSSP) avec l’attribut SECPKG_ATTR_ISSUER_LIST_EX .

Après avoir reçu un certificat d’authentification d’une autorité de certification approuvée par le serveur, l’application cliente crée de nouvelles informations d’identification. Pour ce faire, il appelle la fonction AcquireCredentialsHandle (CredSSP), puis appelle à nouveau InitializeSecurityContext (CredSSP), en spécifiant les nouvelles informations d’identification dans le paramètre phCredential .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
En-tête	Sspi.h (include Security.h)
Bibliothèque	Secur32.lib
DLL	Secur32.dll