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 |
|---|---|
|
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 |
|---|---|
|
Ce type de chaîne n’est pas pris en charge. |
|
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. |
|
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 |
|---|---|
|
Seule une virgule (,) est prise en charge comme séparateur RDN. |
|
Seul un point-virgule (;) est pris en charge comme séparateur RDN. |
|
Seule une barre oblique inverse r (\r) ou une barre oblique inverse n (\n) est prise en charge en tant que séparateur RDN. |
|
Le signe plus (+) est ignoré en tant que séparateur et plusieurs valeurs par RDN ne sont pas prises en charge. |
|
La citation n’est pas prise en charge. |
|
L’ordre des RDN dans un nom unique est inversé avant l’encodage. Cet indicateur n’est pas défini par défaut. |
|
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. |
|
Le type de valeur encodé CERT_RDN_UTF8_STRING est utilisé à la place de CERT_RDN_UNICODE_STRING. |
|
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. |
|
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. |
|
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 |