Partager via

Fonction AcceptSecurityContext (Digest)

  • Article

La fonction AcceptSecurityContext (Digest) 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 (Digest) 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     ptsExpiry
);

Paramètres

phCredential [in, optional]

Handle pour les informations d’identification du serveur. Le serveur appelle la fonction AcquireCredentialsHandle (Digest) 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 (Digest), 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.

Avertissement

N’utilisez pas le même handle de contexte dans les appels simultanés à AcceptSecurityContext (Digest). 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 (Digest) qui contient le descripteur de mémoire tampon d’entrée.

Le tableau suivant montre la configuration de la mémoire tampon pour Digest HTTP. La première mémoire tampon doit être de type SECBUFFER_TOKEN, et le reste doit être de type SECBUFFER_PKG_PARAMS. SASL nécessite uniquement la mémoire tampon zéro.

Type de mémoire tampon #/mémoire tampon Signification
0
SECBUFFER_TOKEN		 Vide pour le premier appel et la réponse de défi reçue de la part du client pour le deuxième appel.
1
SECBUFFER_PKG_PARAMS		 Méthode. Les caractères sont au format wireline à partir de la ligne de requête. Caractères à octet unique US ASCII.
2
SECBUFFER_PKG_PARAMS		 Réservé.
3
SECBUFFER_PKG_PARAMS		 HEntity. Représentation hexadécimale de H(entity-body). Caractères à octet unique US ASCII.
4
SECBUFFER_PKG_PARAMS		 Realm (Domaine). Chaîne de domaine pour le défi. Chaîne Unicode qui doit pouvoir être représentée en US ASCII.
5
SECBUFFER_CHANNEL_BINDINGS | SECBUFFER_READONLY		 Contient la valeur du jeton de liaison de canal.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : cette valeur n’est pas prise en charge.

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.

Valeur Signification
ASC_REQ_ALLOCATE_MEMORY Digest alloue des mémoires tampons de sortie pour vous. Lorsque vous avez terminé d’utiliser les mémoires tampons de sortie, libérez-les en appelant la fonction FreeContextBuffer.
ASC_REQ_ALLOW_MISSING_BINDINGS Indique que Digest ne nécessite pas de liaisons de canal pour les canaux internes et externes. Cette valeur est utilisée à des fins de rétrocompatibilité lorsque la prise en charge de la liaison entre les canaux de point de terminaison n’est pas connue.
Cette valeur s’exclue mutuellement avec ASC_REQ_PROXY_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : cette valeur n’est pas prise en charge.
ASC_REQ_CONFIDENTIALITY Chiffrer et déchiffrer les messages.
Le SSP Digest prend uniquement en charge cet indicateur pour SASL.
ASC_REQ_PROXY_BINDINGS Indique que Digest nécessite une liaison de canal.
Cette valeur s’exclue mutuellement avec ASC_REQ_ALLOW_MISSING_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : cette valeur n’est pas prise en charge.
ASC_REQ_CONNECTION Le contexte de sécurité ne gère pas les messages de mise en forme.
ASC_REQ_EXTENDED_ERROR Lorsque des erreurs se produisent, la partie distante est avertie.
ASC_REQ_HTTP (0x10000000) Utiliser Digest pour HTTP. Omettez cet indicateur pour utiliser Digest comme mécanisme SASL.
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 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]

Représentation des données, telle que l’ordre d’octets, sur la cible. Ce paramètre peut être SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

Ce paramètre n’est pas utilisé avec Digest SSP. Lorsque vous utilisez digest SSP, spécifiez zéro pour ce paramètre.

phNewContext [in, out, optional]

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

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

Ce paramètre est défini sur une durée maximale constante. Il n’y a pas de délai d’expiration pour les contextes de sécurité ou lors de l’utilisation du SSP Digest

Remarque

Jusqu’au dernier appel de la procédure d’authentification, le délai d’expiration du contexte peut être incorrect, car des informations supplémentaires seront fournies au cours des étapes ultérieures de la négociation. Par conséquent, ptsTimeStamp doit être NULL jusqu’à ce que le dernier appel à la fonction.

Valeur retournée

Cette fonction renvoie l’une des valeurs suivantes :

Renvoie code + valeur Description
SEC_E_INSUFFICIENT_MEMORY
0x80090300L		 La fonction a échoué. La mémoire disponible est insuffisante pour terminer l’action demandée.
SEC_E_INTERNAL_ERROR
0x80090304L		 La fonction a échoué. Une erreur non mappée à un code d’erreur SSPI s’est produite.
SEC_E_INVALID_HANDLE
0x80100003L		 La fonction a échoué. Le handle transmis à la fonction n’est pas valide.
SEC_E_INVALID_TOKEN
0x80090308L		 La fonction a échoué. Le jeton transmis à la fonction n’est pas valide.
SEC_E_LOGON_DENIED
0x8009030CL		 L’ouverture de session a échoué.
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L		 La fonction a échoué. Aucune autorité n’a pu être contactée pour l’authentification. Cela peut être dû aux conditions suivantes :
-Le nom de domaine de la partie d’authentification est incorrect.
-Le domaine n’est pas disponible.
-La relation d’approbation a échoué.
SEC_E_NO_CREDENTIALS
0x8009030EL		 La fonction a échoué. Le handle des informations d’identification spécifié dans le paramètre phCredential n’est pas valide.
SEC_E_OK
0x00000000L		 La fonction a réussi. Le contexte de sécurité 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.
SEC_E_SECURITY_QOS_FAILED
0x80090332L		 La fonction a échoué. Un indicateur d’attribut de contexte qui n’est pas valide a été spécifié dans le paramètre fContextReq.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 La fonction a réussi. Le serveur doit appeler CompleteAuthToken et transmettre le jeton de sortie au client. Le serveur attend ensuite un jeton de retour du client, puis effectue un autre appel à AcceptSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED
0x00090313L		 La fonction a réussi. Le serveur doit terminer la génération du message à partir du client, puis appeler la fonction CompleteAuthToken.
SEC_I_CONTINUE_NEEDED
0x00090312L		 La fonction a réussi. Le serveur doit envoyer le jeton de sortie au client et attendre le renvoi d’un jeton. Le jeton renvoyé doit être transmis dans pInput pour un autre appel à AcceptSecurityContext (Digest).
STATUS_LOGON_FAILURE
0xC000006DL		 La fonction a échoué. La fonction AcceptSecurityContext (Digest) a été appelée après l’établissement du contexte spécifié.
SEC_E_BAD_BINDINGS
0x80090346L		 La fonction a échoué. La stratégie de liaison des canaux n’a pas été respectée.

Notes

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

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 (Digest) 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 (Digest). Si InitializeSecurityContext (Digest) renvoie SEC_E_OK, l’authentification mutuelle a été effectuée et une session sécurisée peut commencer. Si InitializeSecurityContext (Digest) renvoie un code d’erreur, la négociation d’authentification mutuelle se termine. Sinon, le jeton de sécurité renvoyé par InitializeSecurityContext (Digest) 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 (Digest). 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.

Remarque

Le paramètre pfContextAttr est valable pour tout renvoi réussi, mais ce n’est que lors du dernier renvoi réussi que 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.

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

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 (inclure Security.h)
Bibliothèque Secur32.lib
DLL Secur32.dll

Voir aussi

Fonctions SSPI

DeleteSecurityContext

InitializeSecurityContext (Digest)