Fonction CertNameToStrA (wincrypt.h)
La fonction CertNameToStr convertit un nom encodé dans une structure CERT_NAME_BLOB en chaîne de caractères null.
La représentation sous forme de chaîne suit les spécifications de nom unique dans RFC 1779. Les exceptions à cette règle sont répertoriées dans la section Remarques ci-dessous.
Syntaxe
DWORD CertNameToStrA(
[in] DWORD dwCertEncodingType,
[in] PCERT_NAME_BLOB pName,
[in] DWORD dwStrType,
[out] LPSTR psz,
[in] DWORD csz
);
Paramètres
[in] dwCertEncodingType
Type d’encodage de certificat utilisé pour encoder le nom. 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] pName
Pointeur vers la structure CERT_NAME_BLOB à convertir.
[in] dwStrType
Ce paramètre spécifie le format de la chaîne de sortie. Ce paramètre spécifie également d’autres options pour le contenu de la chaîne.
Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Tous les identificateurs d’objets (OID) sont ignorés. CERT_RDN entrées sont séparées par une virgule suivie d’un espace (, ). Plusieurs attributs d’un CERT_RDN sont séparés par un signe plus placé dans des espaces ( + ), par exemple Microsoft, Kim Abercrombie + Programmer. |
|
Les OID sont inclus avec un séparateur de signe égal (=) de leur valeur d’attribut. CERT_RDN entrées sont séparées par une virgule suivie d’un espace (, ). Plusieurs attributs d’un CERT_RDN sont séparés par un signe plus suivi d’un espace (+ ). |
|
Les OID sont convertis en noms de clés X.500 ; sinon, ils sont identiques à CERT_OID_NAME_STR. Si un OID n’a pas de nom X.500 correspondant, l’OID est utilisé avec un préfixe d’OID.
La valeur RDN est entre guillemets s’il contient des espaces blancs de début ou de fin ou l’un des caractères suivants :
|
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 |
|---|---|
|
Remplacez la virgule suivie d’un séparateur d’espace (, ) par un point-virgule suivi d’un séparateur d’espace (; ) . |
|
Remplacez la virgule suivie d’un séparateur d’espace (, ) par une barre oblique inverse suivie de la lettre r suivie d’une barre oblique inverse suivie du séparateur n (\r\n). |
|
Remplacez le signe plus placé dans le séparateur d’espaces ( + ) par un séparateur d’espace unique. |
|
Désactivez la citation. |
|
L’ordre des RDN dans la chaîne de nom unique est inversé après le décodage. Cet indicateur n’est pas défini par défaut. |
|
Par défaut, une chaîne de clé X.500 CERT_RDN_T61_STRING est décodée en UTF8. Si le décodage UTF8 échoue, la clé X.500 est décodée sous la forme d’un caractère 8 bits. Utilisez CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG pour ignorer la tentative initiale de décodage en UTF8. |
|
Si le nom pointé par le paramètre pName contient un rdn d’e-mail et que la partie du nom d’hôte de l’adresse e-mail contient une ia5String encodée en Punycode, le nom est converti en équivalent Unicode.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge. |
[out] psz
Pointeur vers une mémoire tampon de caractères qui reçoit la chaîne retournée. La taille de cette mémoire tampon est spécifiée dans le paramètre csz .
[in] csz
Taille, en caractères, de la mémoire tampon psz . La taille doit inclure le caractère null de fin.
Valeur retournée
Retourne le nombre de caractères convertis, y compris le caractère null de fin.
Si psz a la valeur NULL ou que csz a la valeur zéro, retourne la taille requise de la chaîne de destination.
Remarques
Si psz n’a pas la valeur NULL et que csz n’est pas zéro, le psz retourné est toujours une chaîne terminée par null.
Nous vous déconseillons d’utiliser des RDN multicomponents (par exemple, CN=James+O=Microsoft) pour éviter d’éventuels problèmes de classement lors du décodage. Au lieu de cela, envisagez d’utiliser des RDN à valeur unique (par exemple, CN=James, O=Microsoft).
La représentation sous forme de chaîne suit les spécifications de nom unique dans RFC 1779, à l’exception des écarts décrits dans la liste suivante.
- Les noms qui contiennent des guillemets sont placés entre guillemets doubles.
- Les chaînes vides sont placées entre guillemets doubles.
- Les chaînes qui contiennent des espaces consécutifs ne sont pas placées entre guillemets.
- Les valeurs RDN (Relative Distinguished Name) de type CERT_RDN_ENCODED_BLOB ou CERT_RDN_OCTET_STRING sont mises en forme hexadécimales.
- Si un OID n’a pas de nom X.500 correspondant, le préfixe « OID » est utilisé avant OID.
- Les valeurs RDN sont placées entre guillemets doubles (au lieu de « \ ») si elles contiennent des espaces blancs de début, des espaces de fin ou l’un des caractères suivants :
- Virgule (,)
- Signe plus (+)
- Le signe égal (=)
- Marque pouce (« )
- Barre oblique inverse (/)
- Inférieur au signe (<)
- Supérieur au signe (>)
- Signe numérique (#)
- Point-virgule (;)
- Le nom de clé X.500 pour l’OID stateOrProvinceName (2.5.4.8) est « S ». Cette valeur est différente du nom de clé RFC 1779 X.500 (« ST »).
| Clé : | Chaîne d’identificateur d’objet |
|---|---|
| E | 1.2.840.113549.1.9.1 |
| T | 2.5.4.12 |
| G | 2.5.4.42 |
| I | 2.5.4.43 |
| SN | 2.5.4.4 |
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 CertNameToStr 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
| 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 |