Fonction CryptDecodeObject (wincrypt.h)

  • Article

La fonction CryptDecodeObject décode une structure du type indiqué par le paramètre lpszStructType . L’utilisation de CryptDecodeObjectEx est recommandée en tant qu’API qui exécute la même fonction avec des améliorations significatives des performances.

Syntaxe

BOOL CryptDecodeObject(
  [in]      DWORD      dwCertEncodingType,
  [in]      LPCSTR     lpszStructType,
  [in]      const BYTE *pbEncoded,
  [in]      DWORD      cbEncoded,
  [in]      DWORD      dwFlags,
  [out]     void       *pvStructInfo,
  [in, out] DWORD      *pcbStructInfo
);

Paramètres

[in] dwCertEncodingType

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
Note Un type d’encodage de certificat ou de message est requis. X509_ASN_ENCODING est la valeur par défaut. Si ce type est indiqué, il est utilisé. Sinon, si le type PKCS7_ASN_ENCODING est indiqué, il est utilisé.
 

[in] lpszStructType

Pointeur vers un OID définissant le type de structure. Si le mot d’ordre supérieur du paramètre lpszStructType est égal à zéro, le mot d’ordre inférieur spécifie l’identificateur entier pour le type de la structure spécifiée. Sinon, ce paramètre est un pointeur long vers une chaîne terminée par null.

Pour plus d’informations sur les chaînes d’identificateur d’objet, leurs constantes prédéfinies et les structures correspondantes, consultez Constantes pour CryptEncodeObject et CryptDecodeObject.

[in] pbEncoded

Pointeur vers la structure encodée à décoder.

[in] cbEncoded

Nombre d’octets pointés par pbEncoded.

[in] dwFlags

Les indicateurs suivants sont définis. Ils peuvent être combinés avec une opération OR au niveau du bit.

Valeur Signification
CRYPT_DECODE_NOCOPY_FLAG
 Cet indicateur peut être défini pour indiquer que l’optimisation « aucune copie » est activée. Cette optimisation, le cas échéant, met à jour le paramètre pvStructInfo pour qu’il pointe vers le contenu résidant dans pbEncoded au lieu d’effectuer une copie du contenu et de l’ajouter à pvStructInfo. Dans les cas applicables, moins de mémoire doit être allouée par l’application appelante et l’exécution est plus rapide, car aucune copie n’est effectuée. Notez que le compromis lors de l’exécution d’un décodage « sans copie » est que pbEncoded ne peut pas être libéré tant que pvStructInfo n’est pas libéré.
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 Cet indicateur s’applique au décodage X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE ou X509_UNICODE_ANY_STRING. Par défaut, CERT_RDN_T61_STRING valeurs encodées sont initialement décodées en UTF8. Si le décodage UTF8 échoue, la valeur est décodée en caractères de huit bits. Si cet indicateur est défini, il ignore la tentative initiale de décoder la valeur en UTF8 et décode la valeur en caractères de huit bits.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 Par défaut, le contenu de la mémoire tampon pointée vers pbEncoded incluait le contenu signé et la signature. Si cet indicateur est défini, la mémoire tampon inclut uniquement le contenu « à signer ». Cet indicateur s’applique aux objets X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED et X509_KEYGEN_REQUEST_TO_BE_SIGNED.
CRYPT_DECODE_SHARE_OID_STRING_FLAG
 Lorsque cet indicateur est défini, les chaînes OID sont allouées dans Crypt32.dll et partagées au lieu d’être copiées dans la structure de données retournée. Cet indicateur peut être défini si Crypt32.dll n’est pas déchargé avant le déchargement de l’appelant.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG
 Par défaut, les octets de signature sont inversés. Si cet indicateur est défini, cette inversion d’octets est inhibée.

[out] pvStructInfo

Pointeur vers une mémoire tampon pour recevoir la structure décodée. Lorsque la mémoire tampon spécifiée n’est pas suffisamment grande pour recevoir la structure décodée, la fonction définit le code ERROR_MORE_DATA et stocke la taille de mémoire tampon requise, en octets, dans la variable pointée par pcbStructInfo.

Ce paramètre peut être NULL pour récupérer 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.

[in, out] pcbStructInfo

Pointeur vers une valeur DWORD spécifiant la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pvStructInfo . Lorsque la fonction retourne, cette valeur DWORD contient la taille des données décodées copiées dans pvStructInfo. La taille contenue dans la variable pointée par pcbStructInfo peut indiquer une taille supérieure à la structure décodée, car la structure décodée peut inclure des pointeurs vers d’autres structures. Cette taille est la somme de la taille nécessaire à la structure décodée et aux autres structures pointées.

Note Lors du traitement des données retournées dans la 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.
 

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. Certains codes d’erreur possibles sont répertoriés dans le tableau suivant.

Code de retour Description
CRYPT_E_BAD_ENCODE
 Une erreur s’est produite lors du décodage.
ERROR_FILE_NOT_FOUND
 Impossible de trouver une fonction de décodage pour les dwCertEncodingType et lpszStructType spécifiés
ERROR_MORE_DATA
 Si la mémoire tampon spécifiée par le paramètre pvStructInfo n’est pas assez grande pour contenir les données retournées, la fonction définit le code ERROR_MORE_DATA et stocke la taille de mémoire tampon requise, en octets, dans la variable pointée par pcbStructInfo.
 

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

Lors de l’encodage d’un objet de chiffrement à l’aide de la fonction CryptEncodeObjectEx par défaut, le caractère NULL de fin est inclus. Lors du décodage, à l’aide de la fonction CryptDecodeObjectEx préférée, le caractère NULL de fin n’est pas conservé.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : encodage et décodage ASN.1.

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

CryptDecodeObjectEx

CryptEncodeObject

Fonctions d’encodage et de décodage d’objet