Fonction DecryptMessage (Général)

Article
06/13/2023

La fonction DecryptMessage (Général) 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é.

Le fournisseur de support de sécurité Digest fournit le chiffrement et la confidentialité du déchiffrement pour les messages échangés entre le client et le serveur en tant que mécanisme SASL uniquement.

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

Notes

EncryptMessage (Général) et DecryptMessage (Général) peuvent être appelés en même temps à partir de deux threads différents dans un seul contexte d’interface de fournisseur de prise en charge de la sécurité (SSPI) 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.

Pour plus d’informations sur l’utilisation de cette fonction avec un fournisseur de services partagé spécifique, consultez les rubriques suivantes.

Rubrique	Description
DecryptMessage (Digest)	Déchiffre un message à l’aide de Digest.
DecryptMessage (Kerberos)	Déchiffre un message à l’aide de Kerberos.
DecryptMessage (Negotiate)	Déchiffre un message à l’aide de Negotiate.
DecryptMessage (NTLM)	Déchiffre un message à l’aide de NTLM.
DecryptMessage (Schannel)	Déchiffre un message à l’aide de Schannel.

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.

Lors de l’utilisation du fournisseur de services partagé Digest, en entrée, la structure fait référence à une ou plusieurs structures SecBuffer . L’un d’eux doit être de type SECBUFFER_DATA ou SECBUFFER_STREAM, et il doit contenir le message chiffré.

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 partagés Digest, ce paramètre doit être défini sur zéro. Le fournisseur de services partagés Digest gère la numérotation des séquences en interne.

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’un des indicateurs suivants.

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.
SIGN_ONLY	Lorsque vous utilisez le fournisseur de services partagés Digest, utilisez cet indicateur lorsque le contexte de sécurité est défini pour vérifier la signature uniquement. Pour plus d’informations, consultez Qualité de la protection.

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_BUFFER_TOO_SMALL	La mémoire tampon de message est trop petite. Utilisé avec le fournisseur de services partagé Digest.
SEC_E_CRYPTO_SYSTEM_INVALID	Le chiffrement choisi pour le contexte de sécurité n’est pas pris en charge. Utilisé avec le fournisseur de services partagé Digest.
SEC_E_INCOMPLETE_MESSAGE	Les données dans la mémoire tampon d’entrée sont incomplètes. L’application doit lire d’autres données à partir du serveur et appeler à nouveau DecryptMessage (Général).
SEC_E_INVALID_HANDLE	Un handle de contexte non valide a été spécifié dans le paramètre phContext . Utilisé avec les SSP Digest et 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 les SSP Digest et Schannel.
SEC_E_OUT_OF_SEQUENCE	Le message n’a pas été reçu dans l’ordre correct.
SEC_E_QOP_NOT_SUPPORTED	Ni la confidentialité ni l’intégrité ne sont prises en charge par le contexte de sécurité. Utilisé avec le fournisseur de services partagé Digest.
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 (Général) ou InitializeSecurityContext (Général), en passant des tampons d’entrée vides. Si la fonction retourne une mémoire tampon de type SEC_BUFFER_EXTRA, celle-ci doit être transmise à la fonction AcceptSecurityContext (Général) en tant que mémoire tampon d’entrée. Utilisé avec le fournisseur SSP Schannel. La renégociation n’est pas prise en charge pour le mode noyau Schannel. L’appelant doit ignorer cette valeur de retour ou arrêter la connexion. Si la valeur est ignorée, le client ou le serveur peut arrêter la connexion en conséquence.

Remarques

Lorsque vous utilisez le SSP Schannel, la fonction DecryptMessage (General) 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.

Lorsque vous utilisez le SSP Schannel, DecryptMessage (Général) retourne SEC_I_RENEGOTIATE lorsque l’expéditeur du message souhaite renégocier la connexion (contexte de sécurité). Une application gère une renégociation demandée en appelant AcceptSecurityContext (Général) (côté serveur) ou InitializeSecurityContext (Général) (côté client) et en passant des tampons d’entrée vides. Une fois cet appel initial retourné une valeur, procédez comme si votre application créait une connexion. Pour plus d’informations, consultez [Création d’un contexte de sécurité Schannel](creating-an-schannel-security-context.md).

Pour plus d’informations sur l’interopérabilité avec GSSAPI, consultez Interopérabilité SSPI/Kerberos avec GSSAPI.

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

Fonctions SSPI
EncryptMessage (Général)
SecBuffer
SecBufferDesc