Partager via


Fonction CryptMsgControl (wincrypt.h)

La fonction CryptMsgControl effectue une opération de contrôle après qu’un message a été décodé par un appel final à la fonction CryptMsgUpdate . Les opérations de contrôle fournies par cette fonction sont utilisées pour le déchiffrement, la vérification de signature et de hachage, ainsi que l’ajout et la suppression de certificats, de listes de révocation de certificats (CRL), de signataires et d’attributs non authentifiés.

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 remarques relatives à la fonction CryptMsgOpenToEncode .

Syntaxe

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Paramètres

[in] hCryptMsg

Handle d’un message de chiffrement pour lequel un contrôle doit être appliqué.

[in] dwFlags

La valeur suivante est définie lorsque le paramètre dwCtrlType est l’un des éléments suivants :

  • CMSG_CTRL_DECRYPT
  • CMSG_CTRL_KEY_TRANS_DECRYPT
  • CMSG_CTRL_KEY_AGREE_DECRYPT
  • CMSG_CTRL_MAIL_LIST_DECRYPT
Valeur Signification
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
Le handle du fournisseur de chiffrement est libéré lors de l’appel final à la fonction CryptMsgClose . Ce handle n’est pas libéré si la fonction CryptMsgControl échoue.
 

Si le paramètre dwCtrlType ne spécifie pas d’opération de déchiffrement, définissez cette valeur sur zéro.

[in] dwCtrlType

Type d’opération à effectuer. Les types de contrôle de message actuellement définis et le type de structure qui doit être passé au paramètre pvCtrlPara sont indiqués dans le tableau suivant.

Valeur Signification
CMSG_CTRL_ADD_ATTR_CERT
14 (0xE)
Objet BLOB qui contient les octets encodés du certificat d’attribut.
CMSG_CTRL_ADD_CERT
10 (0xA)
Une structure CRYPT_INTEGER_BLOB qui contient les octets encodés du certificat à ajouter au message.
CMSG_CTRL_ADD_CMS_SIGNER_INFO
20 (0x14)
Structure de CMSG_CMS_SIGNER_INFO qui contient des informations de signataire. Cette opération diffère de CMSG_CTRL_ADD_SIGNER , car les informations du signataire contiennent la signature.
CMSG_CTRL_ADD_CRL
12 (0xC)
Objet BLOB qui contient les octets encodés de la liste de révocation de certificats à ajouter au message.
CMSG_CTRL_ADD_SIGNER
6 (0x6)
Une structure CMSG_SIGNER_ENCODE_INFO qui contient les informations du signataire à ajouter au message.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR
8 (0x8)
Une structure CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA qui contient l’index du signataire et un objet BLOB qui contient les informations d’attribut non authentifiées à ajouter au message.
CMSG_CTRL_DECRYPT
2 (0x2)
Une structure CMSG_CTRL_DECRYPT_PARA utilisée pour déchiffrer le message pour le destinataire de transport de clé spécifié. Cette valeur s’applique aux destinataires RSA. Cette opération spécifie que la fonction CryptMsgControl effectue une recherche dans l’index du destinataire pour obtenir les informations du destinataire de transport de clé. Si la fonction échoue, GetLastError retourne CRYPT_E_INVALID_INDEX si aucun destinataire de transport de clé n’est trouvé.
CMSG_CTRL_DEL_ATTR_CERT
15 (0xF)
Index du certificat d’attribut à supprimer.
CMSG_CTRL_DEL_CERT
11 (0xB)
Index du certificat à supprimer du message.
CMSG_CTRL_DEL_CRL
13 (0xD)
Index de la liste de révocation de certificats à supprimer du message.
CMSG_CTRL_DEL_SIGNER
7 (0x7)
Index du signataire à supprimer.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
9 (0x9)
Une structure CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA qui contient un index qui spécifie le signataire et l’index qui spécifie l’attribut non authentifié du signataire à supprimer.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE
21 (0x15)
Structure CERT_STRONG_SIGN_PARA utilisée pour effectuer une vérification de signature forte.

Pour case activée pour une signature forte, spécifiez ce type de contrôle avant d’appeler CryptMsgGetAndVerifySigner ou avant d’appeler CryptMsgControl avec les types de contrôle suivants définis :

  • CMSG_CTRL_VERIFY_SIGNATURE
  • CMSG_CTRL_VERIFY_SIGNATURE_EX
Une fois la signature vérifiée, cette fonction recherche une signature forte. Si la signature n’est pas forte, l’opération échoue et la valeur GetLastError est définie sur NTE_BAD_ALGID.
CMSG_CTRL_KEY_AGREE_DECRYPT
17 (0x11)
Une structure CMSG_CTRL_KEY_AGREE_DECRYPT_PARA utilisée pour déchiffrer le message pour la clé de session d’accord de clé spécifiée. L’accord de clé est utilisé avec Diffie-Hellman chiffrement/déchiffrement.
CMSG_CTRL_KEY_TRANS_DECRYPT
16 (0x10)
Structure CMSG_CTRL_KEY_TRANS_DECRYPT_PARA utilisée pour déchiffrer le message pour le destinataire de transport de clé spécifié. Le transport de clé est utilisé avec le chiffrement/déchiffrement RSA.
CMSG_CTRL_MAIL_LIST_DECRYPT
18 (0x12)
Structure CMSG_CTRL_MAIL_LIST_DECRYPT_PARA utilisée pour déchiffrer le message pour le destinataire spécifié à l’aide d’une clé de chiffrement de clé (KEK) précédemment distribuée.
CMSG_CTRL_VERIFY_HASH
5 (0x5)
Cette valeur n'est pas utilisée.
CMSG_CTRL_VERIFY_SIGNATURE
1 (0x1)
Une structure CERT_INFO qui identifie le signataire du message dont la signature doit être vérifiée.
CMSG_CTRL_VERIFY_SIGNATURE_EX
19 (0x13)
Une structure CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA qui spécifie l’index du signataire et la clé publique pour vérifier la signature du message. La clé publique du signataire peut être une structure CERT_PUBLIC_KEY_INFO , un contexte de certificat ou un contexte de chaîne de certificats.

[in] pvCtrlPara

Pointeur vers une structure déterminée par la valeur de dwCtrlType.

valeur dwCtrlType Signification
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT ou CMSG_CTRL_MAIL_LIST_DECRYPT, et le message en continu est décodé
Le décodage s’effectue comme si le contenu diffusé en continu était déchiffré. Si un contenu en streaming chiffré s’est accumulé avant cet appel, tout ou partie du texte en clair résultant du déchiffrement du texte de chiffrement est renvoyé à l’application par le biais de la fonction de rappel spécifiée dans l’appel à la fonction CryptMsgOpenToDecode .
Note Lors de la diffusion en continu d’un message enveloppé, la fonction CryptMsgControl n’est pas appelée tant que l’interrogation de la disponibilité du CMSG_ENVELOPE_ALGORITHM_PARAM n’a pas réussi. Si l’interrogation échoue, une erreur s’affiche. Pour obtenir une description de cette interrogation, consultez la fonction CryptMsgOpenToDecode .
 
CMSG_CTRL_VERIFY_HASH
Le hachage calculé à partir du contenu du message est comparé au hachage contenu dans le message.
CMSG_CTRL_ADD_SIGNER
pvCtrlPara pointe vers une structure CMSG_SIGNER_ENCODE_INFO qui contient les informations du signataire à ajouter au message.
CMSG_CTRL_DEL_SIGNER
Une fois la suppression effectuée, tous les autres index de signataire utilisés pour ce message ne sont plus valides et doivent être réacquis en appelant la fonction CryptMsgGetParam .
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
Une fois la suppression effectuée, tous les autres index d’attribut non authentifiés utilisés pour ce signataire ne sont plus valides et doivent être réacquis en appelant la fonction CryptMsgGetParam .
CMSG_CTRL_DEL_CERT
Une fois la suppression effectuée, tous les autres index de certificat utilisés pour ce message ne sont plus valides et doivent être réacquis en appelant la fonction CryptMsgGetParam .
CMSG_CTRL_DEL_CRL
Une fois la suppression effectuée, tous les autres index CRL utilisés pour ce message ne sont plus valides et devront être réacquis en appelant la fonction CryptMsgGetParam .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro et la fonction GetLastError renvoie une erreur d’encodage /décodage de notation de syntaxe abstraite 1 (ASN.1). Pour plus d’informations sur ces erreurs, consultez Valeurs de retour d’encodage/décodage ASN.1.

Lorsqu’un message en continu et enveloppé est en cours de décodage, des erreurs se produisent dans la fonction de rappel définie par l’application spécifiée par le paramètre pStreamInfo du
La fonction CryptMsgOpenToDecode peut être propagée à la fonction CryptMsgControl . Si cela se produit, la fonction SetLastError n’est pas appelée par la fonction CryptMsgControl après le retour de la fonction de rappel. Cela conserve toutes les erreurs rencontrées sous le contrôle de l’application. Il incombe à la fonction de rappel (ou à l’une des API qu’elle appelle) d’appeler la fonction SetLastError si une erreur se produit pendant que l’application traite les données en continu.

Des erreurs propagées peuvent être rencontrées à partir des fonctions suivantes :

Les codes d’erreur suivants sont le plus souvent retournés.

Code de retour Description
CRYPT_E_ALREADY_DECRYPTED
Le contenu du message a déjà été déchiffré. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_DECRYPT.
CRYPT_E_AUTH_ATTR_MISSING
Le message ne contient pas d’attribut authentifié attendu. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_BAD_ENCODE
Une erreur s’est produite lors de l’encodage ou du décodage. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_CONTROL_TYPE
Le type de contrôle n’est pas valide.
CRYPT_E_HASH_VALUE
La valeur de hachage est incorrecte.
CRYPT_E_INVALID_INDEX
La valeur de l’index n’est pas valide.
CRYPT_E_INVALID_MSG_TYPE
Le type de message n'est pas valide.
CRYPT_E_OID_FORMAT
L’identificateur d’objet est mal mis en forme. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_ADD_SIGNER.
CRYPT_E_RECIPIENT_NOT_FOUND
Le message de données enveloppe ne contient pas le destinataire spécifié. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_DECRYPT.
CRYPT_E_SIGNER_NOT_FOUND
Le signataire spécifié pour le message est introuvable. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_UNKNOWN_ALGO
L’algorithme de chiffrement est inconnu.
CRYPT_E_UNEXPECTED_ENCODING
Le message n’est pas encodé comme prévu. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_VERIFY_SIGNATURE.
E_INVALIDARG
Un ou plusieurs arguments ne sont pas valides. Cette erreur peut être retournée si le paramètre dwCtrlType est défini sur CMSG_CTRL_DECRYPT.
E_OUTOFMEMORY
La mémoire disponible n’était pas suffisante pour terminer l’opération.

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