Fonction DecryptMessage (Schannel)

  • Article

La fonction DecryptMessage (Schannel) déchiffre un message. Certains packages ne chiffrent pas et déchiffrent les messages, mais exécutent et case activée un hachage d’intégrité.

Cette fonction est également utilisée avec le fournisseur de support de sécurité (SSP) Schannel pour signaler une demande d’expéditeur de message pour une renégociation (redo) des attributs de connexion ou pour un arrêt de la connexion.

Notes

EncryptMessage (Schannel) et DecryptMessage (Schannel) peuvent être appelés en même temps à partir de deux threads différents dans un seul contexte SSPI ( Security Support Provider Interface ) si un thread est en cours de chiffrement et que l’autre est en cours de déchiffrement. Si plusieurs threads sont en cours de chiffrement ou si plusieurs threads sont en cours de déchiffrement, chaque thread doit obtenir un contexte unique.

Syntaxe

SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_    PCtxtHandle    phContext,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo,
  _Out_   PULONG         pfQOP
);

Paramètres

phContext [in]

Handle du contexte de sécurité à utiliser pour déchiffrer le message.

pMessage [in, out]

Pointeur vers une structure SecBufferDesc . En entrée, la structure fait référence à une ou plusieurs structures SecBuffer . L’un d’entre eux peut être de type SECBUFFER_DATA. Cette mémoire tampon contient le message chiffré. Le message chiffré est déchiffré en place, ce qui remplace le contenu d’origine de sa mémoire tampon.

Lorsque vous utilisez le fournisseur SSP Schannel avec des contextes qui ne sont pas orientés connexion, en entrée, la structure doit contenir quatre structures SecBuffer . Exactement une mémoire tampon doit être de type SECBUFFER_DATA et contenir un message chiffré, qui est déchiffré sur place. Les mémoires tampons restantes sont utilisées pour la sortie et doivent être de type SECBUFFER_EMPTY. Pour les contextes orientés connexion, une mémoire tampon de type SECBUFFER_DATA doit être fournie, comme indiqué pour les contextes non orientés connexion. En outre, une deuxième mémoire tampon de type SECBUFFER_TOKEN qui contient un jeton de sécurité doit également être fournie.

MessageSeqNo [in]

Numéro de séquence attendu par l’application de transport, le cas échéant. Si l’application de transport ne gère pas de numéros de séquence, ce paramètre doit être défini sur zéro.

Lorsque vous utilisez le fournisseur de services SSP Schannel, ce paramètre doit être défini sur zéro. Le fournisseur de services SSP Schannel n’utilise pas de numéros de séquence.

pfQOP [out]

Pointeur vers une variable de type ULONG qui reçoit des indicateurs spécifiques au package qui indiquent la qualité de la protection.

Lors de l’utilisation du fournisseur SSP Schannel, ce paramètre n’est pas utilisé et doit être défini sur NULL.

Ce paramètre peut être l’indicateur suivant.

Valeur Signification
SECQOP_WRAP_NO_ENCRYPT
 Le message n’a pas été chiffré, mais un en-tête ou une bande-annonce a été généré.
Note: KERB_WRAP_NO_ENCRYPT a la même valeur et la même signification.

Valeur retournée

Si la fonction vérifie que le message a été reçu dans l’ordre correct, la fonction retourne SEC_E_OK.

Si la fonction ne parvient pas à déchiffrer le message, elle retourne l’un des codes d’erreur suivants.

Code de retour Description
SEC_E_INVALID_HANDLE Un handle de contexte non valide a été spécifié dans le paramètre phContext . Utilisé avec le fournisseur SSP Schannel.
SEC_E_INVALID_TOKEN Les mémoires tampons sont du type incorrect ou aucune mémoire tampon de type SECBUFFER_DATA a été trouvée. Utilisé avec le fournisseur SSP Schannel.
SEC_E_MESSAGE_ALTERED Le message a été modifié. Utilisé avec le fournisseur SSP Schannel.
SEC_E_OUT_OF_SEQUENCE Le message n’a pas été reçu dans l’ordre correct.
SEC_I_CONTEXT_EXPIRED L’expéditeur du message a terminé d’utiliser la connexion et a lancé un arrêt. Pour plus d’informations sur le lancement ou la reconnaissance d’un arrêt, consultez Arrêt d’une connexion Schannel. Utilisé avec le fournisseur SSP Schannel.
SEC_I_RENEGOTIATE La partie distante nécessite une nouvelle séquence de négociation ou l’application vient de lancer un arrêt. Revenez à la boucle de négociation et appelez AcceptSecurityContext (Schannel) ou InitializeSecurityContext (Schannel), passez SECBUFFER_EXTRA retourné à partir de DecryptMessage().

Remarques

Parfois, une application lit les données de la partie distante, tente de les déchiffrer à l’aide de DecryptMessage (Schannel) et découvre que DecryptMessage (Schannel) a réussi, mais que les mémoires tampons de sortie sont vides. Il s’agit d’un comportement normal et les applications doivent être en mesure de le gérer.

Lorsque vous utilisez le fournisseur de services SSP Schannel, la fonction DecryptMessage (Général) retourne SEC_I_CONTEXT_EXPIRED lorsque l’expéditeur du message a arrêté la connexion. Pour plus d’informations sur le lancement ou la reconnaissance d’un arrêt, consultez Arrêt d’une connexion Schannel.

Si vous utilisez TLS 1.0, vous devrez peut-être appeler cette fonction plusieurs fois, en ajustant la mémoire tampon d’entrée sur chaque appel, pour déchiffrer un message entier.

La fonction DecryptMessage (Schannel) retourne SEC_I_RENEGOTIATE lorsqu’un message de protocole TLS post-négociation autre que les données d’application est reçu. Une fois que la fonction DecryptMessage (Schannel) a retourné SEC_I_RENEGOTIATE, les appels EncryptMessage() et DecryptMessage() supplémentaires échouent avec SEC_E_CONTEXT_EXPIRED. Une application gère cette situation en appelant AcceptSecurityContext (Schannel) ( côté serveur) ou InitializeSecurityContext (Schannel) ( côté client) et en transmettant SECBUFFER_EXTRA renvoyées par DecryptMessage(). Une fois cet appel initial retourné une valeur, procédez comme si votre application créait une nouvelle connexion. Ensuite, l’application peut continuer à appeler EncryptMessage() et DecryptMessage(). Pour plus d’informations, consultez Création d’un contexte de sécurité Schannel.

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

Voir aussi