Fonction CryptMsgGetParam (wincrypt.h)
La fonction CryptMsgGetParam acquiert un paramètre de message une fois qu’un message de chiffrement a été encodé ou décodé. Cette fonction est appelée après l’appel CryptMsgUpdate final.
Syntaxe
BOOL CryptMsgGetParam(
[in] HCRYPTMSG hCryptMsg,
[in] DWORD dwParamType,
[in] DWORD dwIndex,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Paramètres
[in] hCryptMsg
Handle d’un message de chiffrement.
[in] dwParamType
Indique les types de paramètres de données à récupérer. Le type de données à récupérer détermine le type de structure à utiliser pour pvData.
Pour un message encodé, seuls les CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM et CMSG_COMPUTED_HASH_PARAM dwParamTypesont valides.
| Valeur | Signification |
|---|---|
|
type de données pvData : pointeur vers un DWORD
Retourne le nombre de certificats d’attribut dans un message SIGNED ou ENVELOPED. |
|
Type de données pvData : pointeur vers un tableau BYTE Récupère un certificat d’attribut. Pour obtenir tous les certificats d’attribut, appelez CryptMsgGetParam variable dwIndex défini sur 0 le nombre d’attributs moins un. |
|
Type de données pvData : pointeur vers un tableau BYTE Récupère le contenu encodé d’un message de chiffrement encodé, sans la couche externe de la structure CONTENT_INFO. Autrement dit, seul l’encodage du champ ContentInfo.content défini par PKCS #7 est retourné. |
|
Type de données pvData : pointeur vers DWORD
Retourne le nombre de certificats dans un message SIGNÉ ou ENVELOPED reçu. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne le certificat d’un signataire. Pour obtenir tous les certificats du signataire, appelez CryptMsgGetParam, en variant dwIndex de 0 au nombre de certificats disponibles moins un. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne le hachage calculé des données dans le message. Ce type s’applique à la fois à l’encodage et au décodage. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne l’intégralité du message PKCS #7 à partir d’un message ouvert pour l’encodage. Récupère le contenu interne d’un message ouvert pour décoder. Si le message est enveloppé, que le type interne est des données et que CryptMsgControl a été appelé pour déchiffrer le message, le contenu déchiffré est retourné. Si le type interne n’est pas des données, l’objet BLOB encodé qui nécessite un décodage supplémentaire est retourné. Si le message n’est pas enveloppé et que le contenu interne est DATA, les données retournées sont les octets du contenu interne. Ce type s’applique à la fois à l’encodage et au décodage. Pour le décodage, si le type est CMSG_DATA, les octets du contenu sont retournés ; sinon, le contenu interne encodé est retourné. |
|
Type de données pvData : pointeur vers DWORD
Retourne le nombre de listes de révocation de certificats dans un message reçu, SIGNÉ ou ENVELOPED. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne une liste de révocation de certificats. Pour obtenir toutes les listes de révocation de certificats, appelez CryptMsgGetParam, en variant dwIndex de 0 au nombre de listes de révocation de certificats disponibles moins un. |
|
Type de données pvData : pointeur vers un tableau BYTE Modifie le contenu d’un message déjà encodé. Le message doit d’abord être décodé avec un appel à CryptMsgOpenToDecode. Ensuite, la modification apportée au message est effectuée par le biais d’un appel à CryptMsgControl, CryptMsgCountersign ou CryptMsgCountersignEncoded. Le message est ensuite réencodé avec un appel à CryptMsgGetParam, en spécifiant CMSG_ENCODED_MESSAGE pour obtenir un nouvel encodage qui reflète les modifications apportées. Cela peut être utilisé, pour instance, pour ajouter un attribut d’horodatage à un message. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne les informations de signataire encodées CMSG_SIGNER_INFO pour un signataire de message. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne le hachage chiffré d’une signature. Généralement utilisé pour effectuer l’horodatage. |
|
Type de données pvData : pointeur vers un tableau BYTE pour une structure CRYPT_ALGORITHM_IDENTIFIER .
Retourne l’algorithme de chiffrement utilisé pour chiffrer le message. |
|
Type de données pvData : pointeur vers un tableau BYTE pour une structure CRYPT_ALGORITHM_IDENTIFIER .
Retourne l’algorithme de chiffrement utilisé pour chiffrer un message ENVELOPED. |
|
Type de données pvData : pointeur vers un tableau BYTE pour une structure CRYPT_ALGORITHM_IDENTIFIER .
Retourne l’algorithme de hachage utilisé pour hacher le message lors de sa création. |
|
Type de données pvData : pointeur vers un tableau BYTE Retourne la valeur de hachage stockée dans le message lors de sa création. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une chaîne d’identificateur d’objet (OID) terminée par null.
Retourne le type de contenu interne d’un message reçu. Ce type n’est pas applicable aux messages de type DATA. |
|
type de données pvData : pointeur vers un DWORD
Retourne le nombre de destinataires de transport de clé d’un message ENVELOPED reçu. |
|
Type de données pvData : pointeur vers DWORD
Retourne le nombre total de destinataires de tous les messages, y compris les destinataires du contrat de clé et de la liste de messages. |
|
type de données pvData : pointeur vers un DWORD
Retourne l’index du destinataire de transport de clé utilisé pour déchiffrer un message ENVELOPED. Cette valeur n’est disponible qu’une fois qu’un message a été déchiffré. |
|
type de données pvData : pointeur vers un DWORD
Retourne l’index du destinataire du transport de clé, de l’accord de clé ou de la liste de courrier utilisé pour déchiffrer un message ENVELOPED. |
|
type de données pvData : pointeur vers un DWORD
Retourne l’index de la clé chiffrée d’un destinataire de contrat de clé utilisé pour déchiffrer un message ENVELOPED. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CERT_INFO .
Retourne des informations de certificat sur le destinataire d’un message de transport de clé. Pour obtenir des informations de certificat sur tous les destinataires du message de transport de clé, appelez de façon répétée CryptMsgGetParam, en variant dwIndex de 0 au nombre de destinataires moins un. Seuls les membres Issuer, SerialNumber et PublicKeyAlgorithm de la structure CERT_INFO retournée sont disponibles et valides. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CMSG_CMS_RECIPIENT_INFO .
Retourne des informations sur un transport de clé, un accord de clé ou un destinataire de liste de courrier. Il n’est pas limité aux destinataires de messages de transport de clé. Pour obtenir des informations sur tous les destinataires d’un message, appelez de façon répétée CryptMsgGetParam, en variant dwIndex de 0 au nombre de destinataires moins un. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CRYPT_ATTRIBUTES .
Retourne les attributs authentifiés d’un signataire de message. Pour récupérer les attributs authentifiés pour un signataire spécifié, appelez CryptMsgGetParam avec dwIndex égal à l’index de ce signataire. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir la structure CERT_INFO .
Retourne les informations sur un signataire de message nécessaire pour identifier le certificat du signataire. L’émetteur et le numéro série d’un certificat peuvent être utilisés pour identifier de manière unique un certificat à des fins d’extraction. Pour récupérer des informations pour tous les signataires, appelez de façon répétée CryptMsgGetParam variant dwIndex de 0 au nombre de signataires moins un. Seuls les champs Issuer et SerialNumber de la structure CERT_INFO retournée contiennent des données disponibles et valides. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CERT_ID .
Retourne les informations sur un signataire de message nécessaire pour identifier la clé publique du signataire. Il peut s’agir de l’émetteur et du numéro série d’un certificat, d’un KeyID ou d’un hashId. Pour récupérer des informations pour tous les signataires, appelez CryptMsgGetParam variant dwIndex de 0 au nombre de signataires moins un. |
|
type de données pvData : pointeur vers un DWORD
Retourne le nombre de signataires d’un message SIGNÉ reçu. |
|
type de données pvData : pointeur vers un tableau BYTE pour recevoir la structure CRYPT_ALGORITHM_IDENTIFIER .
Retourne l’algorithme de hachage utilisé par un signataire du message. Pour obtenir l’algorithme de hachage d’un signataire spécifié, appelez CryptMsgGetParam avec dwIndex égal à l’index de ce signataire. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CMSG_SIGNER_INFO .
Retourne des informations sur un signataire de message. Cela inclut l’émetteur et le numéro de série du certificat du signataire, ainsi que les attributs authentifiés et non authentifiés du certificat du signataire. Pour récupérer les informations de signataire sur tous les signataires d’un message, appelez CryptMsgGetParam variant dwIndex de 0 au nombre de signataires moins un. |
|
type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CMSG_CMS_SIGNER_INFO .
Retourne des informations sur un signataire de message. Cela inclut un signerId et des attributs authentifiés et non authentifiés. Pour récupérer les informations de signataire sur tous les signataires d’un message, appelez CryptMsgGetParam variant dwIndex de 0 au nombre de signataires moins un. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CRYPT_ATTRIBUTES .
Retourne les attributs non authentifiés d’un signataire de message. Pour récupérer les attributs non authentifiés d’un signataire spécifié, appelez CryptMsgGetParam avec dwIndex égal à l’index de ce signataire. |
|
type de données pvData : pointeur vers un DWORD
Retourne le type de message d’un message décodé de type inconnu. Le type de message récupéré peut être comparé aux types pris en charge pour déterminer si le traitement peut se poursuivre. Pour les types de messages pris en charge, consultez le paramètre dwMessageType de CryptMsgOpenToDecode. |
|
Type de données pvData : pointeur vers un tableau BYTE pour recevoir une structure CMSG_ATTR .
Retourne les attributs non protégés dans un message enveloppé. |
|
type de données pvData : pointeur vers un DWORD
Retourne la version du message décodé. Pour plus d’informations, consultez le tableau dans la section Remarques. |
[in] dwIndex
Index du paramètre en cours de récupération, le cas échéant. Lorsqu’un paramètre n’est pas récupéré, ce paramètre est ignoré et est défini sur zéro.
[out] pvData
Pointeur vers une mémoire tampon qui reçoit les données récupérées. La forme de ces données varie en fonction de la valeur du paramètre dwParamType .
Ce paramètre peut être NULL pour définir la taille de ces informations à des fins d’allocation de mémoire. Pour plus d’informations, consultez Récupération de données de longueur inconnue.
Lors du traitement des données retournées dans cette mémoire tampon, les applications doivent utiliser la taille réelle des données retournées. La taille réelle peut être légèrement inférieure à la taille de la mémoire tampon spécifiée lors de l’entrée. (Lors de l’entrée, les tailles de mémoire tampon sont généralement spécifiées suffisamment grandes pour garantir que les données de sortie les plus volumineuses possibles tiennent dans la mémoire tampon.) En sortie, la variable pointée par ce paramètre est mise à jour pour refléter la taille réelle des données copiées dans la mémoire tampon.
[in, out] pcbData
Pointeur vers une variable qui spécifie la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pvData . Lorsque la fonction retourne, la variable pointée vers par le paramètre pcbData contient le nombre d’octets stockés dans la mémoire tampon.
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).
Si la fonction échoue, la valeur de retour est zéro (FALSE). 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 .
| Code de retour | Description |
|---|---|
|
Le message ne contient pas les attributs demandés. |
|
Valeur d’index non valide. |
|
Le type de message n'est pas valide. |
|
Le contenu du message n’a pas encore été déchiffré. |
|
L’identificateur d’objet est mal mis en forme. |
|
Le message n’est pas encodé comme prévu. |
|
Un ou plusieurs arguments ne sont pas valides. |
|
La mémoire tampon spécifiée n’est pas assez grande pour contenir les données retournées. |
Pour les CMSG_COMPUTED_HASH_PARAM dwParamType , une erreur peut être propagée à partir de CryptGetHashParam.
Si la fonction échoue, GetLastError peut renvoyer une erreur d’encodage/décodage ASN.1 ( Abstract Syntax Notation One ). Pour plus d’informations sur ces erreurs, consultez Valeurs de retour d’encodage/décodage ASN.1.
Remarques
Les numéros de version suivants sont retournés par les appels à CryptMsgGetParam avec dwParamType défini sur CMSG_VERSION_PARAM sont définis :
- CMSG_SIGNED_DATA_V1
- CMSG_SIGNED_DATA_V3
- CMSG_SIGNED_DATA_PKCS_1_5_VERSION
- CMSG_SIGNED_DATA_CMS_VERSION
- CMSG_SIGNER_INFO_V1
- CMSG_SIGNER_INFO_V3
- CMSG_SIGNER_INFO_PKCS_1_5_VERSION
- CMSG_SIGNER_INFO_CMS_VERSION
- CMSG_HASHED_DATA_V0
- CMSG_HASHED_DATA_V2
- CMSG_HASHED_DATA_PKCS_1_5_VERSION
- CMSG_HASHED_DATA_CMS_VERSION
- CMSG_ENVELOPED_DATA_V0
- CMSG_ENVELOPED_DATA_V2
- CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
- CMSG_ENVELOPED_DATA_CMS_VERSION
Exemples
Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : signature, encodage, décodage et vérification d’un message, Code de remplacement pour l’encodage d’un message enveloppé, Exemple de programme C : encodage d’un message enveloppé, signé et exemple de programme C : encodage et décodage d’un message haché.
Configuration requise
| 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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour