Fonction CryptMsgOpenToDecode (wincrypt.h)

Article
08/27/2023

La fonction CryptMsgOpenToDecode ouvre un message de chiffrement pour le décodage et retourne un handle du message ouvert. Le message reste ouvert jusqu’à ce que la fonction CryptMsgClose soit appelée.

Des modifications importantes qui affectent la gestion des messages enveloppes ont été apportées à CryptoAPI pour prendre en charge l’interopérabilité des e-mails S/MIME (Secure/Multipurpose Internet Mail Extensions ). Pour plus d’informations, consultez la section Remarques de CryptMsgOpenToEncode.

Syntaxe

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Paramètres

[in] dwMsgEncodingType

Spécifie le type d’encodage utilisé. Il est toujours acceptable de spécifier les types d’encodage de certificat et de message en les combinant avec une opération OR au niveau du bit, comme illustré dans l’exemple suivant :

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Les types d’encodage actuellement définis sont les suivants :

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Ce paramètre peut être l’un des indicateurs suivants.

Valeur	Signification
CMSG_DETACHED_FLAG	Indique que le message à décoder est détaché. Si cet indicateur n’est pas défini, le message n’est pas détaché.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Si la valeur est définie, le hCryptProv passé à cette fonction est publié sur la dernière version de CryptMsgUpdate. Le handle n’est pas libéré si la fonction échoue.

[in] dwMsgType

Spécifie le type de message à décoder. Dans la plupart des cas, le type de message est déterminé à partir de l’en-tête du message et zéro est passé pour ce paramètre. Dans certains cas, notamment avec Internet Explorer 3.0, les messages n’ont pas d’en-têtes et le type de message à décoder doit être fourni dans cet appel de fonction. Si l’en-tête est manquant et que zéro est passé pour ce paramètre, la fonction échoue.

Ce paramètre peut être l’un des types de messages prédéfinis suivants.

Valeur	Signification
CMSG_DATA	Le message est des données encodées.
CMSG_ENVELOPED	Le message est un message enveloppe.
CMSG_HASHED	Le message est un message haché.
CMSG_SIGNED	Le message est un message signé.
CMSG_SIGNED_AND_ENVELOPED	Le message est un message signé et enveloppé.

[in] hCryptProv

Ce paramètre n’est pas utilisé et doit être défini sur NULL.

Windows Server 2003 et Windows XP : Spécifie un handle que le fournisseur de chiffrement doit utiliser pour le hachage du message. Pour les messages signés, hCryptProv est utilisé pour la vérification de signature. Le type de données de ce paramètre est HCRYPTPROV.

Sauf s’il existe une raison forte de passer un fournisseur de chiffrement spécifique dans hCryptProv, définissez ce paramètre sur NULL. La transmission de la valeur NULL entraîne l’acquisition du fournisseur RSA ou DSS par défaut avant d’effectuer des opérations de hachage, de vérification de signature ou de chiffrement de destinataire.

[in] pRecipientInfo

Ce paramètre est réservé à une utilisation ultérieure et doit avoir la valeur NULL.

[in, optional] pStreamInfo

Lorsque la diffusion en continu n’est pas utilisée, ce paramètre doit être défini sur NULL.

Note La diffusion en continu n’est pas utilisée avec CMSG_HASHED messages. Lorsque vous traitez des données hachées, ce paramètre doit être défini sur NULL.

Lorsque la diffusion en continu est utilisée, le paramètre pStreamInfo est un pointeur vers une structure CMSG_STREAM_INFO qui contient un pointeur vers un rappel à appeler lors de l’exécution de CryptMsgUpdate ou lorsque CryptMsgControl est exécuté lors du décodage d’un message enveloppe en continu.

Pour un message signé, le rappel se fait passer un bloc des octets décodés du contenu interne du message.

Pour un message enveloppé, après chaque appel à CryptMsgUpdate, vous devez case activée pour déterminer si la propriété CMSG_ENVELOPE_ALGORITHM_PARAM est disponible en appelant la fonction CryptMsgGetParam. CryptMsgGetParam échoue et GetLastError retourne CRYPT_E_STREAM_MSG_NOT_READY jusqu’à ce que CryptMsgUpdate ait suffisamment traité le message pour rendre la propriété CMSG_ENVELOPE_ALGORITHM_PARAM disponible. Lorsque la propriété CMSG_ENVELOPE_ALGORITHM_PARAM est disponible, vous pouvez itérer à travers les destinataires, en récupérant une structure CERT_INFO pour chaque destinataire à l’aide de la fonction CryptMsgGetParam pour récupérer la propriété CMSG_RECIPIENT_INFO_PARAM. Pour empêcher une attaque par déni de service à partir d’un message enveloppé qui a un bloc d’en-tête artificiellement volumineux, vous devez suivre la quantité de mémoire qui a été passée à la fonction CryptMsgUpdate pendant ce processus. Si la quantité de données dépasse une limite définie par l’application avant que la propriété CMSG_ENVELOPE_ALGORITHM_PARAM soit disponible, vous devez arrêter le traitement du message et appeler la fonction CryptMsgClose pour que le système d’exploitation libère toute mémoire allouée pour le message. Une limite suggérée est la taille maximale autorisée d’un message. Par exemple, si la taille maximale du message est de 10 Mo, la limite de ce test doit être de 10 Mo.

La structure CERT_INFO est utilisée pour rechercher un certificat correspondant dans un magasin de certificats précédemment ouvert à l’aide de la fonction CertGetSubjectCertificateFromStore . Lorsque le certificat correct est trouvé, la fonction CertGetCertificateContextProperty avec un paramètre CERT_KEY_PROV_INFO_PROP_ID est appelée pour récupérer une structure CRYPT_KEY_PROV_INFO . La structure contient les informations nécessaires pour acquérir la clé privée du destinataire en appelant CryptAcquireContext, à l’aide des membres pwszContainerName, pwszProvName, dwProvType et dwFlags de la structure CRYPT_KEY_PROV_INFO . Le hCryptProv acquis et le membre dwKeySpec de la structure CRYPT_KEY_PROV_INFO sont passés à la structure CryptMsgControl en tant que membre de la structure CMSG_CTRL_DECRYPT_PARA pour permettre le début du déchiffrement du contenu interne. Le code de streaming effectue ensuite le déchiffrement au fur et à mesure que les données sont entrées. Les blocs de texte en clair résultant sont passés à la fonction de rappel spécifiée par le membre pfnStreamOutput de la structure CMSG_STREAM_INFO pour gérer la sortie du message déchiffré.

Note Le décodage en continu d’un message enveloppé met en file d’attente le texte de chiffrement en mémoire jusqu’à ce que CryptMsgControl soit appelé pour démarrer le déchiffrement. L’application doit lancer le déchiffrement en temps opportun afin que les données puissent être enregistrées sur le disque ou acheminées ailleurs avant que le texte de chiffrement accumulé ne devienne trop volumineux et que le système manque de mémoire.

Dans le cas d’un message signé placé dans un message enveloppe, la sortie en texte clair du décodage en continu du message enveloppe peut être transmise dans un autre décodage de streaming pour traiter le message signé.

Valeur retournée

Si la fonction réussit, la fonction retourne le handle du message ouvert.

Si la fonction échoue, elle retourne NULL. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Le tableau suivant répertorie les codes d’erreur les plus couramment retournés par la fonction GetLastError .

Valeur	Description
E_INVALIDARG	Un ou plusieurs arguments ne sont pas valides.
E_OUTOFMEMORY	Un échec d’allocation de mémoire s’est produit.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Crypt32.lib
DLL	Crypt32.dll

Voir aussi

Fonctions de message de bas niveau

Fonctions de message simplifiées