Fonction DecryptMessage (Schannel)

La fonction DecryptMessage (Schannel) déchiffre un message. Certains packages ne chiffrent pas et déchiffrent les messages, mais effectuent et vérifient plutôt un hachage d’intégrité.

Utilisez cette fonction avec le fournisseur de support de sécurité Schannel (SSP) pour signaler une demande d’expéditeur de message pour une renégociation (rétablissement) des attributs de connexion ou pour un arrêt de la connexion.

Syntaxe

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

Paramètres

phContext [in]

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

pMessage [in, out]

Pointeur vers une structure SecBufferDesc . Lors de l’entrée, la structure fait référence à une ou plusieurs structures SecBuffer . L’une de ces mémoires tampons peut être de type SECBUFFER_DATA. Cette mémoire tampon contient le message chiffré. La fonction déchiffre le message chiffré en place, en remplaçant le contenu d’origine de sa mémoire tampon.

Lorsque vous utilisez le SSP Schannel avec des contextes qui ne sont pas orientés vers la connexion, la structure doit contenir quatre structures SecBuffer sur l’entrée. Exactement une mémoire tampon doit être de type SECBUFFER_DATA et contenir un message chiffré, que la fonction déchiffre en 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, vous devez fournir une mémoire tampon de type SECBUFFER_DATA, comme indiqué pour les contextes non orientés connexion. En outre, vous devez fournir une deuxième mémoire tampon de type SECBUFFER_TOKEN qui contient un jeton de sécurité.

MessageSeqNo [in]

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

Lorsque vous utilisez le SSP Schannel, définissez ce paramètre sur zéro. Le 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.

Lorsque vous utilisez le SSP Schannel, n’utilisez pas ce paramètre. Définissez-le sur NULL.

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

Valeur de retour

Si la fonction vérifie que le message est reçu dans la séquence correcte, il retourne SEC_E_OK.

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

Remarques

Parfois, une application lit les données du tiers distant, tente de le déchiffrer à l’aide de DecryptMessage (Schannel) et découvre que DecryptMessage (Schannel) réussit, mais que les mémoires tampons de sortie sont vides. Ce comportement est normal et les applications doivent être en mesure de les gérer.

Lorsque vous utilisez le SSP Schannel, la fonction DecryptMessage (Général) retourne SEC_I_CONTEXT_EXPIRED lorsque l’expéditeur du message arrête la connexion. Pour plus d’informations sur le lancement ou la reconnaissance d’un arrêt, consultez Arrêter 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’elle reçoit un message de protocole TLS post-négociation autre que les données d’application. Une fois que DecryptMessage (Schannel) retourne SEC_I_RENEGOTIATE, les autres appels EncryptMessage() et DecryptMessage() échouent avec SEC_E_CONTEXT_EXPIRED. Une application gère cette situation en appelant AcceptSecurityContext (côté serveur) ou InitializeSecurityContext ( côté client) et en passant la même mémoire tampon que modifiée par DecryptMessage, en garantissant que le SecBuffer type est défini SECBUFFER_TOKENsur . Notez que DecryptMessage ne retourne pas toujours une SECBUFFER_EXTRA mémoire tampon lorsqu’elle SEC_I_RENEGOTIATE est retournée. Une fois cet appel initial retourné une valeur, procédez comme si votre application crée une connexion. Ensuite, l’application peut continuer à appeler EncryptMessage() et DecryptMessage(). Pour plus d’informations, consultez Création d’un contexte de sécurité Schannel.

Spécifications

Contenu connexe

• Fonctions SSPI
• EncryptMessage (Schannel)
• SecBuffer