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 |
|---|---|
|
Spécifie l’encodage des messages PKCS 7. |
|
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.
[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.
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 |
|---|---|
|
Une erreur s’est produite lors de l’encodage. |
|
Impossible de trouver une fonction d’encodage pour le dwCertEncodingType et lpszStructType spécifiés. |
|
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
| 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
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
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 |