Fonction InitializeSecurityContext (CredSSP)
La fonction InitializeSecurityContext (CredSSP) initie le contexte de sécurité côté client et sortant à 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 à son tour soumet ce jeton à l’implémentation de sécurité locale par le biais de 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 [ dans, facultatif]
-
Handle des informations d’identification retournées par AcquireCredentialsHandle (CredSSP). Ce descripteur est utilisé pour générer le contexte de sécurité. La fonction InitializeSecurityContext (CredSSP) requiert au moins des informations d’identification sortantes.
-
phContext [ dans, facultatif]
-
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.
-
pTargetName [ dans, facultatif]
-
Pointeur vers une chaîne se terminant par un caractère null qui identifie de façon unique le serveur cible. Schannel utilise cette valeur pour vérifier le certificat du serveur. Schannel utilise également cette valeur pour localiser la session dans le cache de session lors de la 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 [ dans]
-
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 de la _ demande ISC _ , par exemple, ISC _ req _ Delegate.
Ce paramètre peut être un ou plusieurs des indicateurs d’attributs suivants.
Valeur Signification - ISC _ REQ _ allouer la _ mémoire
- 0x100
Le package de sécurité alloue des tampons de sortie pour l’appelant. Lorsque vous avez fini d’utiliser les tampons de sortie, libérez-les en appelant la fonction FreeContextBuffer . - ISC _ DEMANDE de _ connexion
- 0x800
Le contexte de sécurité ne gère pas les messages de mise en forme. - ISC _ _ _ Erreur étendue de la req
- 0x4000
Lorsque des erreurs se produisent, le tiers distant est averti. - ISC _ DEMANDE _ de _ _ validation d’cred manuel
- 0x80000
Le fournisseur de support de sécurité des informations d’identification (CredSSP) ne doit pas authentifier le serveur automatiquement. Cet indicateur est toujours défini lors de l’utilisation de CredSSP. - ISC _ _ _ Détection de séquence de demandes
- 0x8
Détecte les messages reçus en dehors de la séquence. - ISC _ _Flux de demande
- 0x8000
Prend en charge une connexion orientée flux. - ISC _ Demandes d’identification _ _ fournies _ par la req
CredSSP ne doit pas tenter de fournir automatiquement des informations d’identification pour le client. - ISC _ _Délégué req
- 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 jeu d’informations d’identification vide est délégué au serveur.
Windows Server 2008 et Windows Vista : Cet indicateur est obligatoire.- ISC _ DEMANDE _ d' _ authentification mutuelle
- 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 ne sont peut-être pas pris en charge par le client. Pour plus d’informations, consultez le paramètre pfContextAttr .
Pour plus d’informations sur les différents attributs, consultez spécifications de contexte.
-
Reserved1 [ dans]
-
Réservé. Ce paramètre doit avoir la valeur zéro.
-
TargetDataRep [ dans]
-
Représentation des données, telle que l’ordonnancement des octets, sur la cible. Ce paramètre peut être Security _ native _ DREP ou Security _ Network _ DREP.
-
pInput [ in, out, facultatif]
-
Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers les mémoires tampons fournies comme entrée au package. À moins que le contexte client n’ait été initié par le serveur, la valeur de ce paramètre doit être null lors du premier appel à la fonction. Lors des appels suivants à la fonction ou lorsque le contexte client a été initié 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.
Sur les 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. Le deuxième tampon a le type SECBUFFER _ vide; affectez la valeur zéro aux membres pvBuffer et cbBuffer .
-
Reserved2 [ dans]
-
Réservé. Ce paramètre doit avoir la valeur zéro.
-
phNewContext [ in, out, facultatif]
-
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 le même que le handle spécifié dans le paramètre phContext .
Sur les appels après le premier appel, transmettez le handle retourné ici en tant que paramètre phContext et spécifiez null pour phNewContext.
-
pOutput [ out, facultatif]
-
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 s _ ReadWrite dans l’entrée, elle y figurera à la sortie. Le système alloue une mémoire tampon pour le jeton de sécurité si elle est demandée (par le biais de la _ demande ISC _ allocate _ Memory) et remplit l’adresse dans le descripteur de mémoire tampon du jeton de sécurité.
Si l’indicateur de _ demande d’allocation de _ _ mémoire d’ISC est spécifié, CredSSP alloue de la mémoire pour la mémoire tampon et place les informations appropriées dans le SecBufferDesc.
-
pfContextAttr [ à]
-
Pointeur vers un jeu d’indicateurs binaires qui indiquent les attributs du contexte établi. Pour obtenir une description des différents attributs, consultez spécifications de contexte.
Les indicateurs utilisés pour ce paramètre sont préfixés par 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é jusqu’à ce que l’appel de fonction final soit retourné avec succès. Les indicateurs d’attribut qui ne sont pas liés à la sécurité, tels que l’indicateur ASC _ RET _ allouée la _ mémoire , 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, facultatif]
-
Pointeur vers une structure d' horodatage 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 la valeur null doit être transmise pour les clients à courte durée de vie.
Valeur de retour
Si la fonction réussit, elle retourne l’un des codes de réussite suivants.
| Code de retour | Description |
|---|---|
|
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 _ manquant. 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 aboutisse. Même si ce nombre n’est pas toujours exact, son utilisation peut aider à améliorer les performances en évitant les appels multiples à cette fonction. |
|
Le contexte de sécurité a été initialisé avec succès. Il n’est pas nécessaire d’avoir un autre appel InitializeSecurityContext (CredSSP) . Si la fonction retourne un jeton de sortie, c’est-à-dire si le _ jeton SECBUFFER dans pOutput est d’une longueur différente de zéro, ce jeton doit être envoyé au serveur. |
|
Le client doit appeler CompleteAuthToken , puis transmettre la sortie au serveur. Le client attend ensuite un jeton retourné et le passe, dans un autre appel, à InitializeSecurityContext (CredSSP). |
|
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 client passe le jeton retourné dans un autre appel à InitializeSecurityContext (CredSSP). Le jeton de sortie peut être vide. |
|
Le serveur a demandé l’authentification du client, mais 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. |
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 terminer 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. |
|
Le jeton d’entrée est incorrect. Les causes possibles incluent un jeton endommagé en transit, un jeton de taille incorrecte et un jeton passé dans le mauvais package de sécurité. Cette dernière condition peut se produire si le client et le serveur n’ont pas négocié le package de sécurité approprié. |
|
L’ouverture de session a échoué. |
|
Aucune autorité n’a pu être contactée pour l’authentification. Le nom de domaine du tiers d’authentification 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. |
|
La valeur du paramètre fContextReq n’est pas valide. Soit un indicateur obligatoire n’a pas été spécifié, soit un indicateur qui n’est pas pris en charge par CredSSP a été spécifié. |
|
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. |
|
La stratégie ne prend pas en charge la délégation des informations d’identification au serveur cible. |
|
La délégation des informations d’identification au serveur cible n’est pas autorisée lorsque l’authentification mutuelle n’est pas effectuée. |
|
L’authentification du serveur a échoué lorsque l' _ _ indicateur d’authentification mutuelle d’ISC req _ 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 immédiatement la connexion.
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 jambes, la séquence appelante 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 de jeton dans le tableau de mémoires tampons. Si le paramètre fContextReq comprend l’indicateur ISC _ req _ allocate _ Memory , le package de sécurité alloue la mémoire et retourne le pointeur dans l’élément de jeton.
- 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 (CredSSP) .
- AcceptSecurityContext (CredSSP) peut retourner un jeton. Le serveur envoie ce jeton au client par le biais d’un deuxième appel de InitializeSecurityContext (CredSSP) si le premier appel a retourné sec _ que je _ continue _.
Si le serveur a répondu, 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 _ Completed _, ou sec _ i _ Completed _ et _ continue, les étapes 2 et 3 sont répétées.
L’initialisation d’un 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 masques qui représentent différents attributs de contexte. Pour obtenir une description des différents attributs, consultez spécifications de contexte. Tandis que le paramètre pfContextAttributes est valide en cas de retour correct, 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 _ allouée _ Memory .
Si l’indicateur d’identification des informations d’identification _ _ _ _ fournies par l’ISC est défini, le package de sécurité doit rechercher un type de 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 un appariement renforcé du package de sécurité et de l’application, le cas échéant.
Si la _ demande ISC _ allocate _ Memory a été spécifiée, 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 local. Dans ce cas, le jeton de sortie est la réponse chiffrée NTLM à la stimulation.
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 d’appel de deuxième InitializeSecurityContext (CredSSP) et aucune réponse du serveur ne sera attendue. Si le code de retour est sec, _ je _ continue _ nécessaire, le client attend un jeton en réponse du serveur et le transmet dans un deuxième appel à InitializeSecurityContext (CredSSP). Le code de retour de sec _ I _ _ requis indique que le client doit terminer la génération du message et appeler la fonction CompleteAuthToken . Les secondes _ que j’ai _ effectuées _ et qui _ poursuivent le code incorporent ces deux actions.
Si InitializeSecurityContext (CredSSP) retourne une réussite sur le premier appel (ou uniquement), l’appelant doit finir par appeler la fonction DeleteSecurityContext sur le handle retourné, même si l’appel échoue sur une branche 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 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.
Si la fonction retourne les _ _ _ informations d’identification s I incomplètes, vérifiez que les informations d’identification r transmises à la fonction AcquireCredentialsHandle (CredSSP) spécifiaient 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 une liste des autorités de certification approuvées par le serveur, appelez la fonction QueryContextAttributes (CredSSP) avec la liste d' _ émetteurs SECPKG attr _ _ _ ex Attribute.
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 CredSSP (AcquireCredentialsHandle) , puis l’appel de 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 [Applications de bureau Vista uniquement] |
| Serveur minimal pris en charge |
Windows Serveur 2008 [ applications de bureau uniquement] |
| En-tête |
|
| Bibliothèque |
|
| DLL |
|