Partager via


Fonction CryptEncodeObjectEx (wincrypt.h)

La fonction CryptEncodeObjectEx encode une structure du type indiqué par la valeur du paramètre lpszStructType . Cette fonction offre une amélioration significative des performances par rapport à CryptEncodeObject en prenant en charge l’allocation de mémoire avec la valeur CRYPT_ENCODE_ALLOC_FLAG .

Syntaxe

BOOL CryptEncodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const void         *pvStructInfo,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_ENCODE_PARA pEncodePara,
  [out]     void               *pvEncoded,
  [in, out] DWORD              *pcbEncoded
);

Paramètres

[in] dwCertEncodingType

Type d’encodage de certificat et type d’encodage de message à utiliser pour encoder l’objet. Ce paramètre peut être une combinaison d’une ou plusieurs des valeurs suivantes.

Valeur Signification
PKCS_7_ASN_ENCODING
65536 (0x10000)
Spécifie l’encodage des messages PKCS 7.
X509_ASN_ENCODING
1 (0x1)
Spécifie l’encodage du certificat X.509.

[in] lpszStructType

Pointeur vers un identificateur d’objet (OID) qui définit le type de structure. Si le mot d’ordre élevé du paramètre lpszStructType est égal à zéro, le mot d’ordre inférieur spécifie un identificateur entier pour le type de la structure spécifiée. Sinon, ce paramètre est un pointeur vers une chaîne terminée par null qui contient la représentation sous forme de chaîne de l’OID.

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] pvStructInfo

Pointeur vers la structure à encoder. La structure doit être du type spécifié par lpszStructType.

[in] dwFlags

Spécifie les options pour l’encodage. Ce paramètre peut être zéro ou une combinaison d’une ou plusieurs des valeurs suivantes.

Valeur Signification
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
La fonction d’encodage appelée alloue de la mémoire pour les octets encodés. Un pointeur vers les octets alloués est retourné dans pvEncoded.
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
Cet indicateur s’applique à l’activation de l’encodage 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_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG
1073741824 (0x40000000)
Cet indicateur s’applique lors de l’encodage X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE ou X509_UNICODE_ANY_STRING. Si cet indicateur est défini, les caractères ne sont pas vérifiés pour déterminer s’ils sont valides pour le type de valeur spécifié.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG
2147483648 (0x80000000)
Cet indicateur s’applique lors de l’encodage X509_UNICODE_NAME. Si cet indicateur est défini et que tous les caractères Unicode sont <= 0xFF, le CERT_RDN_T61_STRING est sélectionné au lieu de la CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG
536870912 (0x20000000)
Cet indicateur s’applique lors de l’encodage d’un X509_UNICODE_NAME. Lorsqu’il est défini, CERT_RDN_UTF8_STRING est sélectionné au lieu de CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_FORCE_UTF8_UNICODE_FLAG
268435456 (0x10000000)
Cet indicateur s’applique lors de l’encodage d’un X509_UNICODE_NAME. Lorsqu’il est défini, CERT_RDN_UTF8_STRING est sélectionné au lieu de CERT_RDN_PRINTABLE_STRING pour les types de chaînes de répertoires. En outre, cet indicateur active CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG.

[in] pEncodePara

Pointeur vers une structure CRYPT_ENCODE_PARA qui contient des informations d’encodage. Ce paramètre peut être NULL.

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

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

[out] pvEncoded

Pointeur vers une mémoire tampon pour recevoir la structure encodée. La taille de cette mémoire tampon est spécifiée dans le paramètre pcbEncoded . Lorsque la mémoire tampon spécifiée n’est pas assez 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 pcbEncoded.

Ce paramètre peut avoir la valeur NULL pour récupérer la taille de la mémoire tampon à des fins d’allocation de mémoire. Pour plus d’informations, consultez Récupération de données de longueur inconnue.

Si dwFlags contient l’indicateur CRYPT_ENCODE_ALLOC_FLAG , pvEncoded 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 pvEncoded, pvEncoded ne peut pas avoir la valeur NULL.

[in, out] pcbEncoded

Pointeur vers une variable DWORD qui contient la taille, en octets, de la mémoire tampon pointée par le paramètre pvEncoded . Lorsque la fonction retourne, la variable pointée vers par le paramètre pcbEncoded contient le nombre d’octets alloués et encodés stockés dans la mémoire tampon.

Lorsque dwFlags contient l’indicateur CRYPT_ENCODE_ALLOC_FLAG , pcbEncoded est l’adresse d’un pointeur vers la valeur DWORD mise à jour.

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. (En 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 s’intègrent 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

Retourne une valeur différente de zéro en cas de réussite ou de zéro dans le cas contraire.

Pour obtenir des informations d’erreur étendues, appelez GetLastError. Le tableau suivant présente certains codes d’erreur possibles qui peuvent être retournés par GetLastError en cas d’échec de CryptEncodeObjectEx .

Code de retour Description
CRYPT_E_BAD_ENCODE
Une erreur s’est produite lors de l’encodage.
ERROR_FILE_NOT_FOUND
Impossible de trouver une fonction d’encodage pour le dwCertEncodingType et lpszStructType spécifiés.
ERROR_MORE_DATA
Si la mémoire tampon spécifiée par le paramètre pvEncoded 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 pcbEncoded.
 

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 par défaut, le caractère NULL de fin n’est pas conservé.

CryptEncodeObjectEx recherche d’abord une fonction d’encodage étendue installable. Si aucune fonction d’encodage étendue n’est trouvée, l’ancienne fonction installable nonextended se trouve.

Lorsque l’encodage IA5String direct de l’objet n’est pas possible, vous pouvez spécifier l’encodage Punycode en définissant le paramètre dwFlag sur la valeur CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG . La définition de l’indicateur CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG a des effets différents en fonction du type de structure encodé comme spécifié par la valeur du paramètre lpszStructType .

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_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
  • szOID_NAME_CONSTRAINTS
  • X509_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
L’indicateur CRYPT_ENCODE_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 des caractères Unicode en dehors du jeu de caractères ASCII, le nom d’hôte est d’abord encodé en Punycode, puis encodé en tant que chaîne IA5String .
CERT_ALT_NAME_RFC822_NAME Si la partie du nom d’hôte de l’adresse e-mail contient des caractères Unicode en dehors du jeu de caractères ASCII, la partie du nom d’hôte de l’adresse e-mail est encodée en Punycode. L’adresse e-mail résultante est ensuite encodée sous la forme d’une chaîne IA5String .
CERT_ALT_NAME_URL Si le nom d’hôte du serveur de l’URI contient des caractères Unicode en dehors du jeu de caractères ASCII, la partie du nom d’hôte de l’URI est encodée en Punycode. Ensuite, l’URI résultant est placé dans une séquence d’échappement et l’URL est ensuite encodée en tant que chaîne IA5String .
 

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_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
Lors de l’encodage de la valeur de structure CERT_HASHED_URL , si le nom d’hôte du serveur de l’URI contient des caractères Unicode en dehors du jeu de caractères ASCII et que le CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG est défini, la partie du nom d’hôte de l’URI est encodée dans Punycode. Ensuite, l’URI résultant est placé dans une séquence d’échappement et l’URL est ensuite encodée en tant que chaîne IA5String .

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 du membre Value contient des caractères Unicode en dehors du jeu de caractères ASCII, la partie du nom d’hôte de l’adresse e-mail est encodée en Punycode. Ensuite, l’adresse e-mail résultante est encodée sous la forme d’une chaîne IA5String .

Dans tous les cas, l’encodage Punycode du nom d’hôte est effectué sur une base étiquette par étiquette.

Exemples

L’exemple suivant montre l’initialisation et l’encodage d’une structure X509_NAME à l’aide de CryptEncodeObjectEx. Pour obtenir un exemple qui inclut le contexte complet de cet exemple, consultez Exemple de programme C : encodage et décodage ASN.1.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")


#define MY_TYPE (X509_ASN_ENCODING)

void main()
{

//#define moved

//--------------------------------------------------------------------
//   Declare and initialize local variables.

char *Cert_Sub_Name ="Test User Name";

//--------------------------------------------------------------------
// Initialize a single RDN structure.

CERT_RDN_ATTR rgNameAttr = 
{
   "2.5.4.3",                      // The OID
   CERT_RDN_PRINTABLE_STRING,      // Type of string
   (DWORD)strlen(Cert_Sub_Name)+1, // String length including
                                   //  the terminating null character
   (BYTE *)Cert_Sub_Name           // Pointer to the string 
};
//--------------------------------------------------------------------
// Declare and initialize a structure to include
// the array of RDN structures.

CERT_RDN rgRDN[] = 
{
   1,               // The number of elements in the array
   &rgNameAttr      // Pointer to the array
};

//--------------------------------------------------------------------
//  Declare and initialize a CERT_NAME_INFO 
//  structure that includes a CERT_RND.

CERT_NAME_INFO CertName = 
{
    1,          // The number of elements in the CERT_RND's array
    rgRDN
};

//--------------------------------------------------------------------
//  Declare additional variables.

DWORD cbEncoded;              // Variable to hold the
                              //  length of the encoded string
BYTE *pbEncoded;              // Variable to hold a pointer to the 
                              //  encoded buffer
//--------------------------------------------------------------------
// Call CrypteEncodeObjectEx to get 
// length to allocate for pbEncoded.

if( CryptEncodeObjectEx(
     MY_TYPE,        // The encoding/decoding type
     X509_NAME,    
     &CertName,
     0,                 
     NULL, 
     NULL,
     &cbEncoded))    // Fill in the length needed for
                     // the encoded buffer.
{
     printf("The number of bytes needed is %d \n",cbEncoded);
}
else
{
     printf("The first call to the function failed.\n");
     exit(1);
}

if( pbEncoded = (BYTE*)malloc(cbEncoded))
{
     printf("Memory for pvEncoded has been allocated.\n");
}
else
{
    printf("Memory allocation failed.\n");
    exit(1);
}

if(CryptEncodeObjectEx(
     MY_TYPE,
     X509_NAME,
     &CertName,
     0,
     NULL, 
     pbEncoded,
     &cbEncoded))
{
     printf("The structure has been encoded.\n");
}
else
{
     printf("Encoding failed.");
     exit(1);
}
// Free allocated memory when done.
// ...
if(pbEncoded)
{
    free(pbEncoded);
}


Configuration requise

Condition requise Valeur
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

CryptDecodeObjectEx

CryptEncodeObject

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