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 |
|---|---|
|
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 |
|---|---|
|
Objet BLOB qui contient les octets encodés du certificat d’attribut. |
|
Une structure CRYPT_INTEGER_BLOB qui contient les octets encodés du certificat à ajouter au message. |
|
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. |
|
Objet BLOB qui contient les octets encodés de la liste de révocation de certificats à ajouter au message. |
|
Une structure CMSG_SIGNER_ENCODE_INFO qui contient les informations du signataire à ajouter au message. |
|
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. |
|
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é. |
|
Index du certificat d’attribut à supprimer. |
|
Index du certificat à supprimer du message. |
|
Index de la liste de révocation de certificats à supprimer du message. |
|
Index du signataire à supprimer. |
|
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. |
|
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 :
|
|
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. |
|
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. |
|
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. |
|
Cette valeur n'est pas utilisée. |
|
Une structure CERT_INFO qui identifie le signataire du message dont la signature doit être vérifiée. |
|
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 |
|---|---|
|
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 .
|
|
Le hachage calculé à partir du contenu du message est comparé au hachage contenu dans le message. |
|
pvCtrlPara pointe vers une structure CMSG_SIGNER_ENCODE_INFO qui contient les informations du signataire à ajouter au message. |
|
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 . |
|
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 . |
|
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 . |
|
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 :
- CryptCreateHash
- CryptDecrypt
- CryptGetHashParam
- CryptGetUserKey
- CryptHashData
- CryptImportKey
- CryptSignHash
- CryptVerifySignature
Les codes d’erreur suivants sont le plus souvent retournés.
| Code de retour | Description |
|---|---|
|
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. |
|
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. |
|
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. |
|
Le type de contrôle n’est pas valide. |
|
La valeur de hachage est incorrecte. |
|
La valeur de l’index n’est pas valide. |
|
Le type de message n'est pas valide. |
|
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. |
|
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. |
|
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. |
|
L’algorithme de chiffrement est inconnu. |
|
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. |
|
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. |
|
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 |