Partager via


Fonction CertStrToNameA (wincrypt.h)

La fonction CertStrToName convertit une chaîne X.500 terminée par null en nom de certificat encodé.

Syntaxe

BOOL CertStrToNameA(
  [in]            DWORD  dwCertEncodingType,
  [in]            LPCSTR pszX500,
  [in]            DWORD  dwStrType,
  [in, optional]  void   *pvReserved,
  [out]           BYTE   *pbEncoded,
  [in, out]       DWORD  *pcbEncoded,
  [out, optional] LPCSTR *ppszError
);

Paramètres

[in] dwCertEncodingType

Type d’encodage de certificat utilisé pour encoder la chaîne. L’identificateur de type d’encodage de message, contenu dans le mot élevé de cette valeur, est ignoré par cette fonction.

Ce paramètre peut être le type d’encodage de certificat actuellement défini ci-dessous.

Valeur Signification
X509_ASN_ENCODING
1 (0x1)
Spécifie l’encodage du certificat X.509 .

[in] pszX500

Pointeur vers la chaîne X.500 terminée par null à convertir. Le format de cette chaîne est spécifié par le paramètre dwStrType .

Cette chaîne doit être mise en forme comme la sortie de la fonction CertNameToStr .

[in] dwStrType

Ce paramètre spécifie le type de la chaîne. Ce paramètre spécifie également d’autres options pour le contenu de la chaîne.

Si aucun indicateur n’est combiné avec le spécificateur de type chaîne, la chaîne peut contenir une virgule (,) ou un point-virgule (;) en tant que séparateurs dans le nom unique relatif (RDN) et un signe plus (+) comme séparateur dans plusieurs valeurs RDN.

Les guillemets («  ») sont pris en charge. Un guillemet peut être inclus dans une valeur entre guillemets à l’aide de deux ensembles de guillemets, par exemple, CN="User « "one" ».

Une valeur qui commence par un signe numérique (#) est traitée comme hexadécimale ASCII et convertie en CERT_RDN_OCTET_STRING. Les espaces blancs incorporés sont ignorés. Par exemple, 1.2.3 = # AB CD 01 est identique à 1.2.3=#ABCD01.

Les espaces blancs qui entourent les clés, les identificateurs d’objet et les valeurs sont ignorés.

Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
CERT_SIMPLE_NAME_STR
1
Ce type de chaîne n’est pas pris en charge.
CERT_OID_NAME_STR
2
Valide que le type de chaîne est pris en charge. La chaîne peut être un identificateur d’objet (OID) ou un nom X.500.
CERT_X500_NAME_STR
3
Identique à CERT_OID_NAME_STR. Valide que le type de chaîne est pris en charge. La chaîne peut être un identificateur d’objet (OID) ou un nom X.500.
 

Les options suivantes peuvent également être combinées avec la valeur ci-dessus pour spécifier des options supplémentaires pour la chaîne.

Valeur Signification
CERT_NAME_STR_COMMA_FLAG
0x04000000
Seule une virgule (,) est prise en charge comme séparateur RDN.
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
Seul un point-virgule (;) est pris en charge comme séparateur RDN.
CERT_NAME_STR_CRLF_FLAG
0x08000000
Seule une barre oblique inverse r (\r) ou une barre oblique inverse n (\n) est prise en charge en tant que séparateur RDN.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
Le signe plus (+) est ignoré en tant que séparateur et plusieurs valeurs par RDN ne sont pas prises en charge.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
La citation n’est pas prise en charge.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
L’ordre des RDN dans un nom unique est inversé avant l’encodage. Cet indicateur n’est pas défini par défaut.
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
Le type de valeur encodé CERT_RDN_T61_STRING est utilisé au lieu de CERT_RDN_UNICODE_STRING. Cet indicateur peut être utilisé si tous les caractères Unicode sont inférieurs ou égaux à 0xFF.
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
Le type de valeur encodé CERT_RDN_UTF8_STRING est utilisé à la place de CERT_RDN_UNICODE_STRING.
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
Force la clé X.500 à être encodée en tant que chaîne UTF-8 (CERT_RDN_UTF8_STRING) plutôt qu’en tant que chaîne Unicode imprimable (CERT_RDN_PRINTABLE_STRING). Il s’agit de la valeur par défaut pour les autorités de certification Microsoft à compter de Windows Server 2003.
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
Empêche l’encodage forcé d’une clé X.500 Unicode (CERT_RDN_PRINTABLE_STRING) imprimable à l’aide d’UTF-8 (CERT_RDN_UTF8_STRING). Permet d’activer l’encodage des clés X.500 en tant que valeurs Unicode lorsque CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG est défini.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
Si la chaîne contient une valeur RDN d’e-mail et que 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 dans Punycode. L’adresse e-mail résultante est ensuite encodée sous la forme d’une chaîne IA5String . L’encodage Punycode du nom d’hôte est effectué sur une base étiquette par étiquette.

Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

[in, optional] pvReserved

Réservé pour une utilisation ultérieure et doit avoir la valeur NULL.

[out] pbEncoded

Pointeur vers une mémoire tampon qui reçoit la structure encodée.

La taille de cette mémoire tampon est spécifiée dans le paramètre pcbEncoded .

Ce paramètre peut avoir la valeur NULL pour obtenir la taille requise 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.

[in, out] pcbEncoded

Pointeur vers un DWORD qui, avant d’appeler la fonction, contient la taille, en octets, de la mémoire tampon pointée par le paramètre pbEncoded . Lorsque la fonction retourne, le DWORD contient le nombre d’octets stockés dans la mémoire tampon.

Si pbEncoded a la valeur NULL, le DWORD reçoit la taille, en octets, requise pour la mémoire tampon.

[out, optional] ppszError

Pointeur vers un pointeur de chaîne qui reçoit des informations d’erreur supplémentaires sur une chaîne d’entrée non valide.

Si la chaîne pszX500 n’est pas valide, ppszError est mis à jour par cette fonction pour pointer vers le début de la séquence de caractères qui n’est pas valide. Si aucune erreur n’est détectée dans la chaîne d’entrée, ppszError a la valeur NULL.

Si ces informations ne sont pas requises, passez la valeur NULL pour ce paramètre.

Ce paramètre est mis à jour pour les codes d’erreur suivants retournés par GetLastError.

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

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.

Remarques

Le tableau suivant contient les clés X.500 prises en charge, la chaîne d’identificateur d’objet correspondante, l’identificateur de chaîne (à partir de Wincrypt.h) et les types de valeur.

Clé : Chaîne d’identificateur d’objet Identificateur de chaîne Types de valeurs RDN
CN 2.5.4.3 szOID_COMMON_NAME Imprimable

T61

L 2.5.4.7 szOID_LOCALITY_NAME Imprimable

T61

O 2.5.4.10 szOID_ORGANIZATION_NAME Imprimable

T61

OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME Imprimable

T61

E

Courrier

1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME Imprimable
S

ST

2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Imprimable

T61

STREET 2.5.4.9 szOID_STREET_ADDRESS Imprimable

T61

T

Titre

2.5.4.12 szOID_TITLE Imprimable

T61

G

GivenName

2.5.4.42 szOID_GIVEN_NAME Imprimable

T61

I

Initials

2.5.4.43 szOID_INITIALS Imprimable

T61

SN 2.5.4.4 szOID_SUR_NAME Imprimable

T61

DC 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8

 

Si Printable ou T61 est autorisé comme type de valeur RDN pour la clé, Printable est automatiquement sélectionné si le composant de chaîne de nom est membre des jeux de caractères suivants :

  • A, B, ..., Z
  • a, b, ..., z
  • 0, 1, ..., 9
  • (espace) ' ( ) + , - . / : = ?

Les types T61 sont encodés en UTF8.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : conversion de noms de certificats en ASN.1 et Retour.

Notes

L’en-tête wincrypt.h définit CertStrToName comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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

CertNameToStr

Fonctions de conversion de données

Obtenir la dernière erreur

Récupération de données de longueur inconnue