Partager via


Fonction CryptDecodeObjectEx (wincrypt.h)

La fonction CryptDecodeObjectEx décode une structure du type indiqué par le paramètre lpszStructType . CryptDecodeObjectEx offre une amélioration significative des performances par rapport à CryptDecodeObject en prenant en charge l’allocation de mémoire avec la valeur CRYPT_DECODE_ALLOC_FLAG.

Syntaxe

BOOL CryptDecodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const BYTE         *pbEncoded,
  [in]      DWORD              cbEncoded,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_DECODE_PARA pDecodePara,
  [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 identificateur d’objet (OID) qui définit 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 les données à décoder. La structure doit être du type spécifié par lpszStructType.

[in] cbEncoded

Nombre d’octets pointés par pbEncoded. Il s’agit du nombre d’octets à décoder.

[in] dwFlags

Ce paramètre peut être un ou plusieurs des indicateurs suivants. Les indicateurs peuvent être combinés à l’aide d’une opération OR au niveau du bit.

Valeur Signification
CRYPT_DECODE_ALLOC_FLAG
La fonction de décodage appelée alloue de la mémoire à la structure décodée. Un pointeur vers la structure allouée est retourné dans pvStructInfo.

Si pDecodePara ou le membre pfnAlloc de pDecodePara a la valeur NULL, LocalAlloc est appelé pour l’allocation et LocalFree doit être appelé pour libérer la mémoire.

Si pDecodePara et le membre pfnAlloc de pDecodePara ne sont pas NULL, la fonction pointée par pfnAlloc est appelée pour l’allocation et la fonction pointée par le membre pfnFree de pDecodePara doit être appelée pour libérer la mémoire.

CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
Cet indicateur s’applique à l’activation du décodage Punycode des valeurs de chaîne Unicode. Pour plus d'informations, consultez la section Notes.

Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cet indicateur n’est pas pris en charge.

CRYPT_DECODE_NOCOPY_FLAG
Cet indicateur peut être défini pour activer une optimisation « aucune copie ». Cette optimisation met à jour les membres pvStructInfo pour qu’ils pointent vers le contenu qui réside dans pbEncoded au lieu d’effectuer une copie du contenu et de l’ajouter à pvStructInfo. L’application appelante doit allouer moins de mémoire et l’exécution est plus rapide, car aucune copie n’est effectuée. Notez que lors de l’exécution d’un décodage « aucune copie », 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.

[in] pDecodePara

Pointeur vers une structure CRYPT_DECODE_PARA qui contient des informations de paragraphe de décodage. Si pDecodePara est défini sur NULL, LocalAlloc et LocalFree sont utilisés pour allouer et libérer de la mémoire. Si pDecodePara pointe vers une structure CRYPT_DECODE_PARA , cette structure passe des fonctions de rappel pour allouer et libérer de la mémoire. Ces fonctions de rappel remplacent l’allocation de mémoire par défaut de LocalAlloc et LocalFree.

[out] pvStructInfo

Si le CRYPT_ENCODE_ALLOC_FLAG dwFlags est défini, pvStructInfo n’est pas un pointeur vers une mémoire tampon, mais l’adresse d’un pointeur vers la mémoire tampon. Étant donné que la mémoire est allouée à l’intérieur de la fonction et que le pointeur est stocké dans *pvStructInfo, pvStructInfo ne doit jamais avoir la valeur NULL.

Si CRYPT_ENCODE_ALLOC_FLAG n’est pas défini, pvStructInfo est un pointeur vers une mémoire tampon qui reçoit 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 variable DWORD qui contient la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pvStructInfo . Lorsque la fonction retourne, la valeur DWORD contient le nombre d’octets stockés dans la mémoire tampon. 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 des données auxiliaires. Cette taille est la somme de la taille requise par la structure décodée et les données auxiliaires.

Lorsque CRYPT_DECODE_ALLOC_FLAG est défini, la valeur initiale de *pcbStructInfo n’est pas utilisée par la fonction et, au retour, *pcbStructInfo contient le nombre d’octets alloués pour pvStructInfo.

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 fonction retourne une valeur différente de zéro (TRUE).

Si la fonction échoue, elle retourne zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError. Le tableau suivant présente certains codes d’erreur possibles.

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é.

Chaque constante de la liste ci-dessous a un type de structure associé qui est pointé vers le paramètre pvStructInfo . La structure pointée vers, directement ou indirectement, fait référence à une structure CERT_ALT_NAME_ENTRY .

  • X509_ALTERNATE_NAME
  • szOID_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_KEY_ID2
  • szOID_AUTHORITY_KEY_IDENTIFIER2
  • szOID_CRL_DIST_POINTS
  • X509_CRL_DIST_POINTS
  • szOID_CROSS_CERT_DIST_POINTS
  • X509_CROSS_CERT_DIST_POINTS
  • szOID_ISSUER_ALT_NAME
  • szOID_ISSUER_ALT_NAME2
  • szOID_ISSUING_DIST_POINT
  • X509_ISSUING_DIST_POINT
  • X509_NAME_CONSTRAINTS
  • szOID_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
L’indicateur CRYPT_DECODE_ENABLE_PUNYCODE_FLAG, conjointement avec la valeur du membre dwAltNameChoice de la structure CERT_ALT_NAME_ENTRY, détermine la façon dont les chaînes sont encodées.
dwAltNameChoice Résultat
CERT_ALT_NAME_DNS_NAME Si le nom d’hôte contient une chaîne IA5String encodée punycode, il est converti en équivalent Unicode.
CERT_ALT_NAME_RFC822_NAME Si la partie du nom d’hôte de l’adresse e-mail contient une chaîne IA5String encodée en Punycode, elle est convertie en son équivalent Unicode.
CERT_ALT_NAME_URL L’URI est décodé. Si le nom d’hôte du serveur de l’URI contient une chaîne IA5String encodée punycode, la chaîne de nom d’hôte est décodée en équivalent Unicode.
 

Chaque constante de la liste ci-dessous a un type de structure associé pointé vers le paramètre pvStructInfo . La structure pointée vers, directement ou indirectement, fait référence à une structure CERT_HASHED_URL .

  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
Lors du décodage de la valeur de structure CERT_HASHED_URL , l’URI est décodé. Si le nom d’hôte contient un nom d’hôte encodé Punycode, il est converti en équivalent Unicode.

Chaque X509_UNICODE_NAME constante dans la liste ci-dessous a un type de structure associé pointé vers le paramètre pvStructInfo .

  • X509_UNICODE_NAME
Si le membre pszObjId de la structure CERT_RDN_ATTR est défini sur szOID_RSA_emailAddr et que l’adresse e-mail dans le membre Value contient une chaîne encodée Punycode, elle est convertie en équivalent Unicode.

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

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

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