Partager via


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
X509_ASN_ENCODING
1 (0x1)
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
CERT_SIMPLE_NAME_STR
1
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.
CERT_OID_NAME_STR
2
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 (+ ).
CERT_X500_NAME_STR
3
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 :

  • Virgule (,)
  • Signe plus (+)
  • Le signe égal (=)
  • Marque pouce (« )
  • Barre oblique inverse suivie de la lettre n (\n)
  • Inférieur au signe (<)
  • Supérieur au signe (>)
  • Signe numérique (#)
  • Point-virgule (;)
Le caractère entre guillemets est une marque de pouce (« ). Si la valeur RDN contient une marque de pouce, elle est placée entre guillemets («  »).
 

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_SEMICOLON_FLAG
0x40000000
Remplacez la virgule suivie d’un séparateur d’espace (, ) par un point-virgule suivi d’un séparateur d’espace (; ) .
CERT_NAME_STR_CRLF_FLAG
0x08000000
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).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
Remplacez le signe plus placé dans le séparateur d’espaces ( + ) par un séparateur d’espace unique.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
Désactivez la citation.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
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.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
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.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
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 »).
En outre, les noms de clés X.500 suivants ne sont pas mentionnés dans RFC 1779, mais peuvent être retournés par cette API :
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

Voir aussi

CertRDNValueToStrStr

CertStrToName

Fonctions de conversion de données