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
[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 |
|---|---|
|
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. |
|
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. |
|
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é. |
|
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. |
|
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. |
|
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. |
|
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.
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 |
|---|---|
|
Une erreur s’est produite lors du décodage. |
|
Impossible de trouver une fonction de décodage pour les dwCertEncodingType et lpszStructType spécifiés. |
|
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
| 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
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
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 |