Fonction InitializeSecurityContext (Negotiate)

La fonction InitializeSecurityContext (Negotiate) initie le côté client et le contexte de sécurité sortant à 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 (Negotiate) retourne un jeton que le client doit passer à l’homologue distant, que l’homologue à son tour soumet à l’implémentation de sécurité locale par le biais de l’appel de AcceptSecurityContext (Negotiate) . Le jeton généré doit être considéré comme opaque par tous les appelants.

En règle générale, la fonction InitializeSecurityContext (Negotiate) 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_        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 [ dans, facultatif]

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

phContext [ dans, facultatif]

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

pszTargetName [ dans, facultatif]

Pointeur vers une chaîne se terminant par un caractère null qui indique le nom de principal du service (SPN) ou le contexte de sécurité du serveur de destination.

Les applications doivent fournir un SPN valide pour aider à atténuer les attaques par relecture.

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_ALLOCATE_MEMORY
Le package de sécurité alloue des tampons de sortie pour vous. Lorsque vous avez fini d’utiliser les tampons de sortie, libérez-les en appelant la fonction FreeContextBuffer .
ISC_REQ_CONFIDENTIALITY
Chiffrez 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.
ISC_REQ_DELEGATE
Le serveur peut utiliser le contexte pour s’authentifier auprès d’autres serveurs en tant que client. L’indicateur de ISC_REQ_MUTUAL_AUTH doit être défini pour que cet indicateur fonctionne. Valide pour Kerberos. Ignorez cet indicateur pour la délégation avec restriction.
ISC_REQ_EXTENDED_ERROR
Lorsque des erreurs se produisent, le tiers distant est averti.
ISC_REQ_INTEGRITY
Signer des messages et vérifier des signatures à l’aide des fonctions EncryptMessage et MakeSignature .
ISC_REQ_MUTUAL_AUTH
La stratégie d’authentification mutuelle du service sera satisfaite.
[!Caution]
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 vous assurer que l’authentification mutuelle est effectuée, appelez la fonction QueryContextAttributes (Negotiate) .

ISC_REQ_NO_INTEGRITY
Si cet indicateur est défini, l’indicateur d' ISC_REQ_INTEGRITY est ignoré.
ISC_REQ_REPLAY_DETECT
Détectez les messages relus qui ont été encodés à l’aide des fonctions EncryptMessage ou MakeSignature .
ISC_REQ_SEQUENCE_DETECT
Détecte les messages reçus en dehors de la séquence.
ISC_REQ_STREAM
Prend en charge une connexion orientée flux.

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]

Ce paramètre est réservé et 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 [ dans, 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.

Reserved2 [ dans]

Ce paramètre est réservé et doit avoir la valeur zéro.

phNewContext [ in, out, facultatif]

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

pOutput [ in, out, facultatif]

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 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é.

pfContextAttr [ à]

Pointeur vers une variable qui reçoit 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, la fonction retourne l’un des codes de réussite suivants.

Code de retour Description
SEC _ E _ OK
Le contexte de sécurité a été initialisé avec succès. Il n’est pas nécessaire d’avoir un autre appel InitializeSecurityContext (Negotiate) . Si la fonction retourne un jeton de sortie, autrement dit, si le _ jeton SECBUFFER dans pOutput a une longueur différente de zéro, ce jeton doit être envoyé au serveur.
s _ j’ai _ terminé _ et je _ continue
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 (Negotiate).
s _ _ terminées _
Le client doit terminer la génération du message, puis appeler la fonction CompleteAuthToken .
SEC _ je _ continue à avoir _ besoin
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 (Negotiate). Le jeton de sortie peut être vide.

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

Code de retour Description
s _ E _ mémoire insuffisante _
La mémoire disponible est insuffisante pour terminer l’action demandée.
SEC _ E _ _ erreur interne
Une erreur qui n’a pas été mappée à un code d’erreur SSPI s’est produite.
SEC _ E _ handle non valide _
Le handle passé à la fonction n’est pas valide.
s _ E _ jeton non valide _
L’erreur est due à un jeton d’entrée incorrect, tel qu’un jeton endommagé en transit, un jeton de taille incorrecte ou un jeton passé dans la délégationconformée incorrecte. Le passage d’un jeton au mauvais package peut se produire si le client et le serveur n’ont pas négocié la délégationappropriée.
s _ _ ouverture de session _ refusée
L’ouverture de session a échoué.
s _ E _ aucune _ autorité d’authentification _
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é.
s _ E _ aucune _ information d’identification
Aucune information d’identification n’est disponible dans la délégation conpressionnelle.
_cible s _ E _ inconnu
La cible n’a pas été reconnue.
SEC _ E _ fonction non prise en charge _
Un indicateur d’attribut de contexte non valide (ISC _ req _ Delegate ou ISC _ req _ prompt _ pour _ CREDS) a été spécifié dans le paramètre fContextReq .
SEC _ E _ _ principal erroné
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 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 .

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

Pour un contexte de sécuritéà deux jambes, la séquence appelante 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, 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.
  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 (Negotiate) .
  4. AcceptSecurityContext (Negotiate) peut retourner un jeton, que le serveur envoie au client pour un deuxième appel à InitializeSecurityContext (Negotiate) si le premier appel a retourné sec _ _ _ .

Pour un contexte de sécuritéà plusieurs jambes, tel que l’authentification mutuelle, la séquence d’appel est la suivante :

  1. Le client appelle la fonction comme décrit précédemment, mais le package renvoie le code de réussite de la procédure de reprise de la SEC _ _ _ .
  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 (Negotiate) , avec phContext défini sur le descripteur retourné à partir du dernier appel. Le jeton reçu du serveur est fourni dans le paramètre pInput .

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.

Pour initialiser un contexte de sécurité, plusieurs appels à cette fonction peuvent être requis, 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. Le paramètre pfContextAttributes est valide en cas de retour réussi, mais uniquement lors du retour final réussi, vous devez examiner 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 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 . Il ne s’agit pas d’une solution générique, mais 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 aucun deuxième appel InitializeSecurityContext (Negotiate) 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 (Negotiate). 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 (Negotiate) renvoie une 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 sur un tronçon ultérieur de l’échange d’authentification.

Le client peut appeler InitializeSecurityContext (Negotiate) 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.

Configuration requise

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

Voir aussi

Fonctions SSPI

AcceptSecurityContext (Negotiate)

AcquireCredentialsHandle (Negotiate)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc