Fonction CertGetNameStringW (wincrypt.h)

Article
11/20/2024

La fonction CertGetNameString obtient le nom de l’objet ou de l’émetteur à partir d’une structure de certificat CERT_CONTEXT et la convertit en chaîne de caractères null-terminated null .

Syntaxe

DWORD CertGetNameStringW(
  [in]  PCCERT_CONTEXT pCertContext,
  [in]  DWORD          dwType,
  [in]  DWORD          dwFlags,
  [in]  void           *pvTypePara,
  [out] LPWSTR         pszNameString,
  [in]  DWORD          cchNameString
);

Paramètres

[in] pCertContext

Pointeur vers un contexte de certificat CERT_CONTEXT qui inclut un nom d’objet et d’émetteur à convertir.

[in] dwType

DWORD indiquant comment le nom doit être trouvé et comment la sortie doit être mise en forme.

Valeur	Signification
CERT_NAME_EMAIL_TYPE 1	Si le certificat a une extension de nom de remplacement d’objet ou un autre nom de l’émetteur, utilise le premier choix rfc822Name. Si aucun choix rfc822Name n’est trouvé dans l’extension, utilise le champ Nom de l’objet pour l’E-mail OID. Si rfc822Name ou email OID est trouvé, utilise la chaîne. Sinon, retourne une chaîne vide (le nombre de caractères retourné est égal à 1). pvTypePara n’est pas utilisé et est défini sur NULL.
CERT_NAME_RDN_TYPE 2	Convertit l’objet BLOB du nom de l’objet en appelant CertNameToStr. pvTypePara pointe vers un DWORD contenant le dwStrType passé à CertNameToStr. Si le champ Nom de l’objet est vide et que le certificat a une extension de nom de remplacement de l’objet, utilise le premier choix de nom de répertoire de CertNameToStr.
CERT_NAME_ATTR_TYPE 3	pvTypePara pointe vers un identificateur d’objet (OID) spécifiant l’attribut de nom à renvoyer. Par exemple, si pvTypePara est szOID_COMMON_NAME, utilise le membre Nom de l’objet. Si le membre Nom de l’objet est vide et que le certificat a une extension de nom de remplacement de l’objet, utilise le premier choix directoryName.
CERT_NAME_SIMPLE_DISPLAY_TYPE 4	Effectue une itération dans la liste suivante d’attributs de nom et utilise le nom de l’objet ou l’extension de nom de l’autre objet pour la première occurrence de : szOID_COMMON_NAME, szOID_ORGANIZATIONAL_UNIT_NAME, szOID_ORGANIZATION_NAME ou szOID_RSA_emailAddr. Si l’un de ces attributs est introuvable, utilise l’extension Subject Alternative Name pour un choix rfc822Name. S’il n’y a toujours aucune correspondance, utilise le premier attribut. pvTypePara n’est pas utilisé et est défini sur NULL.
CERT_NAME_FRIENDLY_DISPLAY_TYPE 5	Vérifie le certificat d’une propriété CERT_FRIENDLY_NAME_PROP_ID. Si le certificat possède cette propriété, elle est retournée. Si le certificat n’a pas la propriété, la CERT_NAME_SIMPLE_DISPLAY_TYPE est retournée.
CERT_NAME_DNS_TYPE 6	Si le certificat a une extension de nom de remplacement d’objet pour l’émetteur, l’autre nom de l’émetteur, recherchez le premier choix DNSName. Si le choix DNSName est introuvable dans l’extension, recherchez le champ Nom de l’objet pour l’OID CN, « 2.5.4.3 ». Si dnsName ou CN OID est trouvé, retournez la chaîne. Sinon, retournez une chaîne vide.
CERT_NAME_URL_TYPE 7	Si le certificat a une extension de nom de remplacement objet pour l’émetteur, l’autre nom de l’émetteur, recherchez le premier choix d’URL. Si le choix de l’URL est trouvé, retournez la chaîne. Sinon, retournez une chaîne vide.
CERT_NAME_UPN_TYPE 8	Si le certificat a une extension de nom de remplacement d’objet, recherchez les options OtherName à la recherche d’un pszObjId == szOID_NT_PRINCIPAL_NAME, (« 1.3.6.1.4.1.311.20.2.3 »). Si l’OID UPN est trouvé, décodez l’objet BLOB en tant que X509_UNICODE_ANY_STRING et retournez la chaîne décodée. Sinon, retournez une chaîne vide.

[in] dwFlags

Indique le type de traitement nécessaire.

Valeur	Signification
CERT_NAME_ISSUER_FLAG 0x1	Acquiert le nom de l’émetteur. S’il n’est pas défini, acquiert le nom de l’objet.
CERT_NAME_DISABLE_IE4_UTF8_FLAG 0x00010000	Ignore la tentative initiale par défaut de décoder la valeur en tant qu’UTF8 et décode en tant que caractères 8 bits.
CERT_NAME_SEARCH_ALL_NAMES_FLAG 0x2	Si le paramètre dwType est défini sur CERT_NAME_DNS_TYPE, tous les noms applicables sont retournés pour la valeur DNS spécifiée. S’il n’existe aucun nom DNS, mais qu’il existe un composant CN dans l’objet, le CN est retourné à la place. S’il existe un cn et un nom DNS, seuls les noms DNS sont retournés. Cela imite la stratégie de création de chaîne SSL. Si vous définissez cet indicateur pour un type de nom autre que CERT_NAME_DNS_TYPE, cette fonction retourne une chaîne vide terminée par null. Windows 8 et Windows Server 2012 : prise en charge de cet indicateur commence.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 0x00200000	Cet indicateur permet le décodage de chaînes IA5String en valeurs de chaîne Unicode en fonction de la valeur du paramètre dwType , comme défini ci-dessous : CERT_NAME_EMAIL_TYPE : si la partie nom d’hôte de l’adresse e-mail contient un composant IA5String encodé en Punycode, il est converti en équivalent Unicode. CERT_NAME_SIMPLE_DISPLAY_TYPE : si un nom d’objet de szOID_RSA_emailAddr ou de rfc822Name à partir du nom d’alternative de l’objet est retourné à partir du certificat, et que la partie nom d’hôte de l’adresse e-mail contient un composant IA5String encodé en Punycode, il est converti en équivalent Unicode. CERT_NAME_DNS_TYPE : si le certificat a un autre nom d’émetteur, avec un choix DNSName et que la partie nom d’hôte de l’adresse e-mail contient punycode encodé composant IA5String, il est converti en équivalent Unicode. CERT_NAME_URL_TYPE : l’URI est décodé et non boucté. Si le nom d’hôte du serveur de l’URI contient un composant Punycode encodé IA5String, la chaîne de nom d’hôte est convertie en équivalent Unicode. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

[in] pvTypePara

Pointeur vers une DWORD contenant l' dwStrType ou un identificateur d’objet (OID) spécifiant l’attribut de nom. Le type pointé est déterminé par la valeur de dwType.

[out] pszNameString

Pointeur vers une mémoire tampon allouée pour recevoir la chaîne retournée. Si pszNameString n’est pas NULL et cchNameString n’est pas zéro, pszNameString est une chaînenull-terminated.

Si CERT_NAME_SEARCH_ALL_NAMES_FLAG est spécifié dans le paramètre dwFlags et CERT_NAME_DNS_TYPE est défini dans le paramètre dwType, la chaîne retournée contient tous les noms DNS qui s’appliquent. Chaque chaîne de la chaîne de sortie est terminée par null et la dernière chaîne est terminée par une valeur null double. Si aucun nom DNS n’est trouvé, une seule chaîne vide terminée par null est retournée.

[in] cchNameString

Taille, en caractères, allouée pour la chaîne retournée. La taille doit inclure la fin caractère NULL.

Valeur de retour

Retourne le nombre de caractères convertis, y compris le caractère zéro de fin. Si pszNameString est null ou cchNameString est égal à zéro, retourne la taille requise de la chaîne de destination (y compris le caractère de fin NULL). Si le type de nom spécifié est introuvable, retourne une chaîne vide null-terminated vide avec un nombre de caractères retourné de 1.

Remarques

Note

L’en-tête wincrypt.h définit CertGetNameString 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

Voir aussi

fonctions de conversion de données

Partager via