Fonction CertStrToNameW (wincrypt.h)
La fonction CertStrToName convertit une chaîne X.500 terminée par null en nom de certificat encodé.
Syntaxe
BOOL CertStrToNameW(
[in] DWORD dwCertEncodingType,
[in] LPCWSTR pszX500,
[in] DWORD dwStrType,
[in, optional] void *pvReserved,
[out] BYTE *pbEncoded,
[in, out] DWORD *pcbEncoded,
[out, optional] LPCWSTR *ppszError
);
Paramètres
[in] dwCertEncodingType
Le type d’encodage de certificat utilisé pour encoder la chaîne. Le
Ce paramètre peut être le type d’encodage de certificat actuellement défini ci-dessous.
| Valeur | Signification |
|---|---|
|
Spécifie encodage de 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 est censée être mise en forme de la même façon que 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é au spécificateur de type de chaîne, la chaîne peut contenir une virgule (,) ou un point-virgule (;) comme séparateurs dans les 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 commençant par un signe numérique (#) est traitée comme ASCII hexadécimal et convertie en CERT_RDN_OCTET_STRING. L’espace blanc incorporé est ignoré. Par exemple, 1.2.3 = # AB CD 01 est identique à 1.2.3=#ABCD01.
L’espace blanc qui entoure les clés, les identificateurs d’objet et les valeurs est ignoré.
Ce paramètre peut être l’une des valeurs suivantes.
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é comme séparateur, et plusieurs valeurs par RDN ne sont pas prises en charge. |
|
Le guillemet n’est pas pris 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é au lieu 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 commençant par Windows Server 2003. |
|
Empêche l’encodage d’une clé X.500 X.500 imprimable CERT_RDN_PRINTABLE_STRING à l’aide d’UTF-8 (CERT_RDN_UTF8_STRING). Permet d’activer l’encodage de clés X.500 en tant que valeurs Unicode lorsque CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG est définie. |
|
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 nom d’hôte de l’adresse e-mail est encodée dans Punycode. L’adresse e-mail résultante est ensuite encodée en tant que chaîne IA5String. L’encodage Punycode du nom d’hôte est effectué sur une base d’é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 être 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
Ce paramètre peut être 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 des 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 est retournée, le DWORD
Si pbEncoded est 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 non 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, transmettez 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 de retour
Retourne une valeur différente de zéro si elle réussit ou zéro sinon.
Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Remarques
Le tableau suivant contient les clés X.500 prises en charge, leur chaîne d’identificateur d’objet correspondante, l’identificateur de chaîne (à partir de Wincrypt.h) et les types 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 |
| Unité d’organisation | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
Imprimable T61 |
|
E Messagerie électronique |
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 |
| RUE | 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 |
|
Je Paraphe |
2.5.4.43 | szOID_INITIALS |
Imprimable T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
Imprimable T61 |
| Courant continu | 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.
Note
L’en-tête wincrypt.h définit CertStrToName comme 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | wincrypt.h |
| bibliothèque | Crypt32.lib |
| DLL | Crypt32.dll |