Fonction CryptMsgGetParam (wincrypt.h)

Article
08/27/2023

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
CMSG_ATTR_CERT_COUNT_PARAM	type de données pvData : pointeur vers un DWORD Retourne le nombre de certificats d’attribut dans un message SIGNED ou ENVELOPED.
CMSG_ATTR_CERT_PARAM	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.
CMSG_BARE_CONTENT_PARAM	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é.
CMSG_CERT_COUNT_PARAM	Type de données pvData : pointeur vers DWORD Retourne le nombre de certificats dans un message SIGNÉ ou ENVELOPED reçu.
CMSG_CERT_PARAM	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.
CMSG_COMPUTED_HASH_PARAM	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.
CMSG_CONTENT_PARAM	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é.
CMSG_CRL_COUNT_PARAM	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.
CMSG_CRL_PARAM	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.
CMSG_ENCODED_MESSAGE	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.
CMSG_ENCODED_SIGNER	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.
CMSG_ENCRYPTED_DIGEST	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.
CMSG_ENCRYPT_PARAM	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.
CMSG_ENVELOPE_ALGORITHM_PARAM	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.
CMSG_HASH_ALGORITHM_PARAM	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.
CMSG_HASH_DATA_PARAM	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.
CMSG_INNER_CONTENT_TYPE_PARAM	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.
CMSG_RECIPIENT_COUNT_PARAM	type de données pvData : pointeur vers un DWORD Retourne le nombre de destinataires de transport de clé d’un message ENVELOPED reçu.
CMSG_CMS_RECIPIENT_COUNT_PARAM	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.
CMSG_RECIPIENT_INDEX_PARAM	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é.
CMSG_CMS_RECIPIENT_INDEX_PARAM	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.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	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.
CMSG_RECIPIENT_INFO_PARAM	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.
CMSG_CMS_RECIPIENT_INFO_PARAM	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.
CMSG_SIGNER_AUTH_ATTR_PARAM	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.
CMSG_SIGNER_CERT_INFO_PARAM	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.
CMSG_SIGNER_CERT_ID_PARAM	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.
CMSG_SIGNER_COUNT_PARAM	type de données pvData : pointeur vers un DWORD Retourne le nombre de signataires d’un message SIGNÉ reçu.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	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.
CMSG_SIGNER_INFO_PARAM	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.
CMSG_CMS_SIGNER_INFO_PARAM	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.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	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.
CMSG_TYPE_PARAM	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.
CMSG_UNPROTECTED_ATTR_PARAM	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é.
CMSG_VERSION_PARAM	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
CRYPT_E_ATTRIBUTES_MISSING	Le message ne contient pas les attributs demandés.
CRYPT_E_INVALID_INDEX	Valeur d’index non valide.
CRYPT_E_INVALID_MSG_TYPE	Le type de message n'est pas valide.
CRYPT_E_NOT_DECRYPTED	Le contenu du message n’a pas encore été déchiffré.
CRYPT_E_OID_FORMAT	L’identificateur d’objet est mal mis en forme.
CRYPT_E_UNEXPECTED_ENCODING	Le message n’est pas encodé comme prévu.
E_INVALIDARG	Un ou plusieurs arguments ne sont pas valides.
ERROR_MORE_DATA	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