Fonction AcceptSecurityContext (Schannel)

La fonction AcceptSecurityContext (Schannel) permet au composant serveur d’une application de transport d’établir un contexte de sécurité entre le serveur et un client distant. Le client distant utilise la fonction InitializeSecurityContext (Schannel) pour démarrer le processus d’établissement d’un contexte de sécurité. Le serveur peut exiger un ou plusieurs jetons de réponse du client distant pour terminer l’établissement du contexte de sécurité.

Syntaxe

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

Paramètres

phCredential[in, optional]

Handle pour les informations d’identification du serveur. Le serveur appelle la fonction AcquireCredentialsHandle (Schannel) avec l’indicateur SECPKG_CRED_INBOUND ou SECPKG_CRED_BOTH défini pour récupérer ce handle.

phContext[in, out, optional]

Pointeur vers une structure CtxtHandle. Lors du premier appel à AcceptSecurityContext (Schannel), ce pointeur est NULL. Lors des appels suivants, phContext est le handle du contexte partiellement formé qui a été renvoyé dans le paramètre phNewContext par le premier appel.

pInput[in, optional]

Pointeur vers une structure SecBufferDesc générée par un appel client à InitializeSecurityContext (Schannel) qui contient le descripteur de mémoire tampon d’entrée.

Lors de l’utilisation du fournisseur de support de sécurité Schannel, la première mémoire tampon doit être de type SECBUFFER_TOKEN et contenir le jeton de sécurité reçu du client. La deuxième mémoire tampon doit être de type SECBUFFER_EMPTY.

fContextReq[in]

Indicateurs de bits qui spécifient les attributs requis par le serveur pour établir le contexte. Les indicateurs de bits peuvent être combinés à l’aide d’opérations OR au niveau du bit. Ce paramètre peut prendre l’une ou plusieurs des valeurs suivantes.

Pour connaître les indicateurs d’attribut possibles et leurs significations, consultez Conditions requises pour le contexte. Les indicateurs utilisés pour ce paramètre sont précédés par ASC_REQ, par exemple, ASC_REQ_DELEGATE.

Les attributs demandés peuvent ne pas être pris en charge par le client. Pour plus d’informations, consultez le paramètre pfContextAttr.

TargetDataRep[in]

Ce paramètre n’est pas utilisé avec Schannel. Spécifiez zéro pour ce paramètre.

phNewContext[in, out, optional]

Pointeur vers une structure CtxtHandle. Lors du premier appel à AcceptSecurityContext (Schannel), ce pointeur reçoit le nouveau handle de contexte. Lors des appels suivants, phNewContext peut être le même que le 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 le descripteur de mémoire tampon de sortie. Cette mémoire tampon est envoyée au client pour une entrée dans des appels supplémentaires à InitializeSecurityContext (Schannel). Une mémoire tampon de sortie peut être générée même si la fonction renvoie SEC_E_OK. Toute mémoire tampon générée doit être renvoyée à l’application cliente.

En sortie, cette mémoire tampon reçoit un jeton pour le contexte de sécurité. Le jeton doit être envoyé au client. La fonction peut également renvoyer une mémoire tampon de type SECBUFFER_EXTRA. En outre, l’appelant doit passer une mémoire tampon de type SECBUFFER_ALERT. En 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 qui reçoit un ensemble d’indicateurs de bits indiquant 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 par ASC_RET, par exemple, ASC_RET_DELEGATE.

Ne vérifiez pas les attributs liés à la sécurité tant que l’appel de fonction final n’a pas renvoyé une réussite. Les indicateurs d’attributs non liés à la sécurité, comme l’indicateur ASC_RET_ALLOCATED_MEMORY, peuvent être vérifiés avant le renvoi final.

ptsTimeStamp[out, optional]

Pointeur vers une structure TimeStamp qui reçoit l’heure d’expiration du contexte. Nous recommandons que le package de sécurité renvoie toujours cette valeur en heure locale.

Cela est facultatif lors de l’utilisation du SSP Schannel. Lorsque la partie distante a fourni un certificat à utiliser pour l’authentification, ce paramètre reçoit le délai d’expiration de ce certificat. Si aucun certificat n’a été fourni, une valeur de temps maximale est retournée.

Valeur de retour

Cette fonction renvoie l’une des valeurs suivantes.

Remarques

La fonction AcceptSecurityContext (Schannel) est l’équivalent serveur de la fonction InitializeSecurityContext (Schannel).

Lorsque le serveur reçoit une requête d’un client, il utilise le paramètres fContextReq pour spécifier ce qu’il exige pour la session. Ainsi, un serveur peut spécifier que les clients doivent être capables d’utiliser une session confidentielle ou une session avec son intégrité vérifiée. Il peut rejeter les clients qui ne peuvent pas répondre à cette demande. Par ailleurs, un serveur peut ne rien demander. Ce que le client requiert ou peut fournir est renvoyé dans le paramètre pfContextAttr.

Pour un package qui prend en charge l’authentification à plusieurs tronçons, comme l’authentification mutuelle, la séquence d’appels est la suivante :

1. Le client transmet un jeton au serveur.
2. Le serveur appelle AcceptSecurityContext (Schannel) la première fois, ce qui génère un jeton de réponse qui est ensuite envoyé au client.
3. Le client reçoit le jeton et le transmet à InitializeSecurityContext (Schannel). Si InitializeSecurityContext (Schannel) retourne SEC_E_OK, l’authentification mutuelle a été terminée et une session sécurisée peut commencer. Si InitializeSecurityContext (Schannel) retourne un code d’erreur, la négociation d’authentification mutuelle se termine. Sinon, le jeton de sécurité retourné par InitializeSecurityContext (Schannel) est envoyé au client, et les étapes 2 et 3 sont répétées.
4. N’utilisez pas la valeur phContext dans les appels simultanés à AcceptSecurityContext (Schannel). L’implémentation dans les fournisseurs de sécurité n’est pas thread-safe.

Les paramètres fContextReq et pfContextAttr sont des masques de bits qui représentent divers attributs de contexte. Pour obtenir une description des différents attributs, consultez Conditions requises pour le contexte.

Il est de la responsabilité de l’appelant de déterminer si les attributs de contexte finaux sont suffisants. Ainsi, si la confidentialité (chiffrement) a été demandée mais n’a pas pu être établie, certaines applications peuvent choisir de fermer la connexion immédiatement. Si le contexte de sécurité ne peut pas être établi, le serveur doit libérer le contexte partiellement créé en appelant la fonction DeleteSecurityContext. Pour en savoir plus sur le moment où appeler la fonction DeleteSecurityContext , consultez DeleteSecurityContext.

Une fois le contexte de sécurité établi, l’application serveur peut utiliser la fonction QuerySecurityContextToken pour récupérer un handle dans le compte d’utilisateur auquel le certificat client a été mappé. En outre, le serveur peut utiliser la fonction ImpersonateSecurityContext pour emprunter l’identité de l’utilisateur.

Spécifications

Voir aussi

Fonctions SSPI

DeleteSecurityContext

InitializeSecurityContext (Schannel)