Fonction AcceptSecurityContext (NTLM)
La fonction AcceptSecurityContext (NTLM) 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 (NTLM) 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 (NTLM) 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 (NTLM), ce pointeur est NULL. Lors des appels suivants, phContext est le handle du contexte partiellement formé qui a été retourné dans le paramètre phNewContext par le premier appel.
Avertissement
N’utilisez pas le même handle de contexte dans les appels simultanés à AcceptSecurityContext (NTLM). L’implémentation de l’API dans les fournisseurs de services de sécurité n’est pas thread-safe.
pInput[in, optional]
Pointeur vers une structure SecBufferDesc générée par un appel client à InitializeSecurityContext (NTLM) qui contient le descripteur de mémoire tampon d’entrée.
Les informations de liaison de canal peuvent être spécifiées en passant une structure SecBuffer de type SECBUFFER_CHANNEL_BINDINGS en plus des mémoires tampons générées par l’appel à la fonction InitializeSecurityContext (Général). Les informations de liaison de canal pour la mémoire tampon de liaison de canal peuvent être obtenues en appelant la fonction QueryContextAttributes (Schannel) sur le contexte Schannel utilisé par le client pour l’authentification.
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 être une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
| ASC_REQ_CONFIDENTIALITY | Chiffrer et déchiffrer les messages. |
| ASC_REQ_CONNECTION | Le contexte de sécurité ne gère pas la mise en forme des messages. |
| ASC_REQ_EXTENDED_ERROR | Lorsque des erreurs se produisent, la partie distante est avertie. |
| ASC_REQ_INTEGRITY | Signer des messages et vérifier les signatures. |
| ASC_REQ_REPLAY_DETECT | Détecter les paquets relus. |
| ASC_REQ_SEQUENCE_DETECT | Détecter les messages reçus hors séquence. |
Pour connaître les indicateurs d’attribut possibles et leurs significations, consultez Exigences de contexte. Les indicateurs utilisés pour ce paramètre sont préfixé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]
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.
phNewContext[in, out, optional]
Pointeur vers une structure CtxtHandle . Lors du premier appel à AcceptSecurityContext (NTLM), ce pointeur reçoit le nouveau handle de contexte. Lors des appels suivants, 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 le descripteur de mémoire tampon de sortie. Cette mémoire tampon est envoyée au client pour entrée dans des appels supplémentaires à InitializeSecurityContext (NTLM). Une mémoire tampon de sortie peut être générée même si la fonction retourne SEC_E_OK. Toute mémoire tampon générée doit être renvoyée à l’application cliente.
pfContextAttr[out]
Pointeur vers une variable qui reçoit 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éfixés par ASC_RET, par exemple, ASC_RET_DELEGATE.
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 non liés à la sécurité, tels que l’indicateur ASC_RET_ALLOCATED_MEMORY, peuvent être vérifiés avant le retour 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é retourne toujours cette valeur en heure locale.
Notes
Jusqu’au dernier appel du processus d’authentification, le délai d’expiration du contexte peut être incorrect, car des informations supplémentaires seront fournies lors des étapes ultérieures de la négociation. Par conséquent, ptsTimeStamp doit être NULL jusqu’au dernier appel à la fonction.
Valeur retournée
Cette fonction retourne l’une des valeurs suivantes.
| Code/valeur de retour | Description |
|---|---|
| Échec de la fonction. La mémoire disponible est insuffisante pour effectuer l’action demandée. |
| Échec de la fonction. Une erreur qui n’a pas été mappée à un code d’erreur SSPI s’est produite. |
| Échec de la fonction. Le handle passé à la fonction n’est pas valide. |
| Échec de la fonction. Le jeton passé à la fonction n’est pas valide. |
| Échec de l’ouverture de session. |
| Échec de la fonction. Aucune autorité n’a pu être contactée pour l’authentification. Cela peut être dû aux conditions suivantes :
|
| La fonction a réussi. [*contexte de sécurité*](.. /secgloss/s-gly.md) reçu du client a été accepté. Si un jeton de sortie a été généré par la fonction, il doit être envoyé au processus client. |
| La fonction a réussi. Le serveur doit appeler [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) et passer le jeton de sortie au client. Le serveur attend ensuite un jeton de retour à partir du client, puis effectue un autre appel à [AcceptSecurityContext (NTLM)](acceptsecuritycontext--ntlm.md). |
| La fonction a réussi. Le serveur doit terminer la génération du message à partir du client, puis appeler la fonction [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken). |
| La fonction a réussi. Le serveur doit envoyer le jeton de sortie au client et attendre un jeton retourné. Le jeton retourné doit être passé dans pInput pour un autre appel à [AcceptSecurityContext (NTLM)](acceptsecuritycontext--ntlm.md). |
Remarques
La fonction AcceptSecurityContext (NTLM) est l’équivalent du serveur de la fonction InitializeSecurityContext (NTLM).
Lorsque le serveur reçoit une requête d’un client, celui-ci utilise le paramètre fContextReq pour spécifier ce qu’il requiert de la session. De cette façon, un serveur peut spécifier que les clients doivent être capables d’utiliser une session confidentielle ou vérifiée par l’intégrité, et il peut rejeter les clients qui ne peuvent pas répondre à cette demande. Un serveur peut également ne rien exiger, et tout ce que le client peut fournir ou requiert est retourné dans le paramètre pfContextAttr .
Pour un package qui prend en charge l’authentification à plusieurs étapes, comme l’authentification mutuelle, la séquence d’appel est la suivante :
- Le client transmet un jeton au serveur.
- Le serveur appelle AcceptSecurityContext (NTLM) la première fois, ce qui génère un jeton de réponse qui est ensuite envoyé au client.
- Le client reçoit le jeton et le transmet à InitializeSecurityContext (NTLM). Si InitializeSecurityContext (NTLM) retourne SEC_E_OK, l’authentification mutuelle a été terminée et une session sécurisée peut commencer. Si InitializeSecurityContext (NTLM) retourne un code d’erreur, la négociation d’authentification mutuelle se termine. Sinon, le jeton de sécurité retourné par InitializeSecurityContext (NTLM) est envoyé au client et les étapes 2 et 3 sont répétées.
- N’utilisez pas la valeur phContext dans les appels simultanés à AcceptSecurityContext (NTLM). 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 différents attributs de contexte. Pour obtenir une description des différents attributs, consultez Configuration requise du contexte.
Notes
Le paramètre pfContextAttr est valide sur tout retour réussi, mais uniquement sur le retour final réussi si 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.
L’appelant est chargé de déterminer si les attributs de contexte finaux sont suffisants. Si, par exemple, la confidentialité (chiffrement) a été demandée, mais n’a pas pu être établie, certaines applications peuvent choisir d’arrêter 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 plus d’informations sur le moment d’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 vers 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 (include Security.h) |
| Bibliothèque | Secur32.lib |
| DLL | Secur32.dll |