Fonction EncryptMessage (Général)
La fonction EncryptMessage (Général) chiffre un message pour assurer la confidentialité. EncryptMessage (Général) permet à une application de choisir parmi les algorithmes de chiffrement pris en charge par le mécanisme choisi. La fonction EncryptMessage (Général) utilise le contexte de sécurité référencé par le handle de contexte. Certains packages n’ont pas de messages à chiffrer ou à déchiffrer, mais fournissent plutôt un hachage d’intégrité qui peut être vérifié.
Lorsque vous utilisez le fournisseur de support de sécurité (SSP) Digest, cette fonction est disponible en tant que mécanisme SASL uniquement.
Lorsque vous utilisez le SSP Schannel, cette fonction chiffre les messages à l’aide d’une clé de session négociée avec la partie distante qui recevra le message. L’algorithme de chiffrement est déterminé par la [suite de chiffrement ](cipher-suites-in-schannel.md) en cours d’utilisation.
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 SSPI ( Security Support Provider Interface ) si un thread est en cours de chiffrement et 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és spécifique, consultez les rubriques suivantes.
| Rubrique | Description |
|---|---|
| EncryptMessage (Digest) | Chiffre un message pour assurer la confidentialité à l’aide de Digest. |
| EncryptMessage (Kerberos) | Chiffre un message pour assurer la confidentialité à l’aide de Kerberos. |
| EncryptMessage (Negotiate) | Chiffre un message pour assurer la confidentialité à l’aide de Negotiate. |
| EncryptMessage (NTLM) | Chiffre un message pour assurer la confidentialité à l’aide de NTLM. |
| EncryptMessage (Schannel) | Chiffre un message pour fournir la confidentialité à l’aide de Schannel. |
Syntaxe
SECURITY_STATUS SEC_Entry EncryptMessage(
_In_ PCtxtHandle phContext,
_In_ ULONG fQOP,
_Inout_ PSecBufferDesc pMessage,
_In_ ULONG MessageSeqNo
);
Paramètres
phContext [in]
Handle du contexte de sécurité à utiliser pour chiffrer le message.
fQOP [in]
Indicateurs spécifiques au package qui indiquent la qualité de la protection. Un package de sécurité peut utiliser ce paramètre pour activer la sélection d’algorithmes de chiffrement.
Lorsque vous utilisez le fournisseur de services partagés Digest, ce paramètre doit être défini sur zéro.
Ce paramètre peut être l’un des indicateurs suivants.
| Valeur | Signification |
|---|---|
|
SECQOP_WRAP_NO_ENCRYPT |
Produisez un en-tête ou une bande-annonce, mais ne chiffrez pas le message. Note: KERB_WRAP_NO_ENCRYPT a la même valeur et la même signification. |
|
Envoyer un message d’alerte Schannel. Dans ce cas, le paramètre pMessage doit contenir un code d’événement SSL/TLS standard sur deux octets. Cette valeur est prise en charge uniquement par le SSP Schannel. |
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 d’elles peut être de type SECBUFFER_DATA. Cette mémoire tampon contient le message à chiffrer. Le message est chiffré sur place, remplaçant le contenu d’origine de la structure.
La fonction ne traite pas les mémoires tampons avec l’attribut SECBUFFER_READONLY.
La longueur de la structure SecBuffer qui contient le message ne doit pas être supérieure à cbMaximumMessage, obtenue à partir de la fonction QueryContextAttributes (General) (SECPKG_ATTR_STREAM_SIZES).
Lors de l’utilisation du SSP Digest, il doit y avoir une deuxième mémoire tampon de type SECBUFFER_PADDING ou SEC_BUFFER_DATA pour contenir les informations de signature . Pour obtenir la taille de la mémoire tampon de sortie, appelez la fonction QueryContextAttributes (Général) et spécifiez SECPKG_ATTR_SIZES. La fonction retourne une structure SecPkgContext_Sizes . La taille de la mémoire tampon de sortie est la somme des valeurs dans les membres cbMaxSignature et cbBlockSize .
Les applications qui n’utilisent pas SSL doivent fournir un SecBuffer de type SECBUFFER_PADDING.
MessageSeqNo [in]
Numéro de séquence que l’application de transport a affecté au message. Si l’application de transport ne gère pas les numéros de séquence, ce paramètre doit être égal à zéro.
Lorsque vous utilisez le fournisseur de services partagés Digest, ce paramètre doit être défini sur zéro. Le SSP Digest gère la numérotation des séquences en interne.
Lorsque vous utilisez le SSP Schannel, ce paramètre doit être défini sur zéro. Le SSP Schannel n’utilise pas de numéros de séquence.
Valeur retournée
Si la fonction réussit, la fonction retourne SEC_E_OK.
Si la fonction échoue, elle retourne l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
| SEC_E_BUFFER_TOO_SMALL | La mémoire tampon de sortie est trop petite. Pour plus d'informations, consultez la section Notes. |
| SEC_E_CONTEXT_EXPIRED | L’application fait référence à un contexte qui a déjà été fermé. Une application correctement écrite ne doit pas recevoir cette erreur. |
| SEC_E_CRYPTO_SYSTEM_INVALID | Le chiffrement choisi pour le contexte de sécurité n’est pas pris en charge. |
| SEC_E_INSUFFICIENT_MEMORY | La mémoire disponible est insuffisante pour effectuer l’action demandée. |
| SEC_E_INVALID_HANDLE | Un handle de contexte non valide a été spécifié dans le paramètre phContext . |
| SEC_E_INVALID_TOKEN | Aucune mémoire tampon de type SECBUFFER_DATA n’a été trouvée. |
| SEC_E_QOP_NOT_SUPPORTED | Ni la confidentialité ni l’intégrité ne sont prises en charge par le contexte de sécurité. |
Notes
La fonction EncryptMessage (Général) chiffre un message en fonction du message et de la clé de session à partir d’un contexte de sécurité.
Si l’application de transport a créé le contexte de sécurité pour prendre en charge la détection de séquence et que l’appelant fournit un numéro de séquence, la fonction inclut ces informations avec le message chiffré. L’inclusion de ces informations protège contre la relecture, l’insertion et la suppression des messages. Le package de sécurité intègre le numéro de séquence transmis à partir de l’application de transport.
Lorsque vous utilisez le fournisseur de services partagés Digest, obtenez la taille de la mémoire tampon de sortie en appelant la fonction QueryContextAttributes (Général) et en spécifiant SECPKG_ATTR_SIZES. La fonction retourne une structure SecPkgContext_Sizes . La taille de la mémoire tampon de sortie est la somme des valeurs dans les membres cbMaxSignature et cbBlockSize .
Lorsqu’il est utilisé avec le SSP Schannel, le paramètre pMessage doit contenir une structure SecBufferDesc avec les mémoires tampons suivantes.
Notes
Ces mémoires tampons doivent être fournies dans l’ordre indiqué.
| Type de mémoire tampon | Description |
|---|---|
| SECBUFFER_STREAM_HEADER | Utilisé en interne. Aucune initialisation requise. |
| SECBUFFER_DATA | Contient le message en texte clair à chiffrer. |
| SECBUFFER_STREAM_TRAILER | Utilisé en interne. Aucune initialisation requise. |
| SECBUFFER_EMPTY | Utilisé en interne. Aucune initialisation requise. La taille peut être égale à zéro. |
Lorsque vous utilisez le fournisseur SSP Schannel, déterminez la taille maximale de chacune des mémoires tampons en appelant la fonction QueryContextAttributes (Général) et en spécifiant l’attribut SECPKG_ATTR_STREAM_SIZES. Cette fonction retourne une structure SecPkgContext_StreamSizes dont les membres contiennent les tailles maximales pour les mémoires tampons d’en-tête (membre cbHeader ), de message (membre cbMaximumMessage ) et de bande-annonce (membre cbTrailer ).
Pour des performances optimales, les structures pMessage doivent être allouées à partir de la mémoire contiguë.
Windows XP/2000 : Cette fonction était également appelée SealMessage. Les applications doivent désormais utiliser EncryptMessage (Général) uniquement.
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 |
|
| Bibliothèque |
|
| DLL |
|