Función CertGetNameStringA (wincrypt.h)

  • Artículo

La función CertGetNameString obtiene el nombre del firmante o emisor de un certificado CERT_CONTEXT estructura y lo convierte en una cadena de caracteres terminada en null.

Sintaxis

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

Parámetros

[in] pCertContext

Puntero a un contexto de certificado CERT_CONTEXT que incluye un nombre de firmante y emisor que se va a convertir.

[in] dwType

DWORD que indica cómo se va a encontrar el nombre y cómo se va a dar formato a la salida.

Value Significado
CERT_NAME_EMAIL_TYPE
1
 Si el certificado tiene una extensión de nombre alternativo del firmante o un nombre alternativo del emisor, use la primera opción rfc822Name. Si no se encuentra ninguna opción rfc822Name en la extensión, usa el campo Nombre del firmante para el OID de Email. Si se encuentra rfc822Name o el OID de Email, usa la cadena . De lo contrario, devuelve una cadena vacía (el recuento de caracteres devuelto es 1). pvTypePara no se usa y se establece en NULL.
CERT_NAME_RDN_TYPE
2
 Convierte el BLOB de nombre de sujeto llamando a CertNameToStr. pvTypePara apunta a un DWORD que contiene dwStrType pasado a CertNameToStr. Si el campo Nombre del firmante está vacío y el certificado tiene una extensión Nombre alternativo del firmante, usa la primera opción de nombre de directorio de CertNameToStr.
CERT_NAME_ATTR_TYPE
3
 pvTypePara apunta a un identificador de objeto (OID) que especifica el atributo name que se va a devolver. Por ejemplo, si pvTypePara es szOID_COMMON_NAME, usa el miembro Nombre del firmante. Si el miembro Nombre del firmante está vacío y el certificado tiene una extensión Nombre alternativo del firmante, usa la primera opción directoryName.
CERT_NAME_SIMPLE_DISPLAY_TYPE
4
 Recorre en iteración la siguiente lista de atributos de nombre y usa el Nombre del firmante o la extensión Nombre alternativo del firmante para la primera aparición de: szOID_COMMON_NAME, szOID_ORGANIZATIONAL_UNIT_NAME, szOID_ORGANIZATION_NAME o szOID_RSA_emailAddr.

Si no se encuentra uno de estos atributos, usa la extensión Nombre alternativo del firmante para una opción rfc822Name. Si todavía no hay ninguna coincidencia, usa el primer atributo.

pvTypePara no se usa y se establece en NULL.
CERT_NAME_FRIENDLY_DISPLAY_TYPE
5
 Comprueba el certificado de una propiedad CERT_FRIENDLY_NAME_PROP_ID. Si el certificado tiene esta propiedad, se devuelve. Si el certificado no tiene la propiedad , se devuelve el CERT_NAME_SIMPLE_DISPLAY_TYPE.
CERT_NAME_DNS_TYPE
6
 Si el certificado tiene una extensión de nombre alternativo del firmante para el emisor, nombre alternativo del emisor, busque la primera opción DNSName.

Si la opción DNSName no se encuentra en la extensión, busque el campo Nombre del firmante del OID CN, "2.5.4.3".

Si se encuentra DNSName o CN OID, devuelva la cadena. De lo contrario, devuelve una cadena vacía.
CERT_NAME_URL_TYPE
7
 Si el certificado tiene una extensión de nombre alternativo del firmante para el emisor, nombre alternativo del emisor, busque la primera opción de dirección URL. Si se encuentra la opción de dirección URL, devuelva la cadena. De lo contrario, devuelve una cadena vacía.
CERT_NAME_UPN_TYPE
8
 Si el certificado tiene una extensión nombre alternativo del firmante, busque las opciones OtherName que buscan un pszObjId == szOID_NT_PRINCIPAL_NAME, ("1.3.6.1.4.1.311.20.2.3").

Si se encuentra el OID de UPN, descodifique el BLOB como un X509_UNICODE_ANY_STRING y devuelva la cadena descodificada. De lo contrario, devuelve una cadena vacía.

[in] dwFlags

Indica el tipo de procesamiento necesario.

Value Significado
CERT_NAME_ISSUER_FLAG
0x1
 Adquiere el nombre del emisor. Si no se establece, adquiere el nombre del firmante.
CERT_NAME_DISABLE_IE4_UTF8_FLAG
0x00010000
 Omite el intento inicial predeterminado de descodificar el valor como UTF8 y descodifica como caracteres de 8 bits.
CERT_NAME_SEARCH_ALL_NAMES_FLAG
0x2
 Si el parámetro dwType se establece en CERT_NAME_DNS_TYPE, se devuelven todos los nombres aplicables para el valor DNS especificado. Si no hay ningún nombre DNS, pero hay un componente CN en el asunto, se devuelve el CN en su lugar. Si hay un CN y un nombre DNS, solo se devuelven los nombres DNS. Esto imita la directiva de creación de la cadena SSL. Si establece esta marca para un tipo de nombre distinto de CERT_NAME_DNS_TYPE, esta función devuelve una cadena vacía terminada en null.

Windows 8 y Windows Server 2012: Comienza la compatibilidad con esta marca.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Esta marca habilita la descodificación de cadenas IA5String en valores de cadena Unicode basados en el valor del parámetro dwType tal como se define a continuación:
  • CERT_NAME_EMAIL_TYPE: si la parte del nombre de host de la dirección de correo electrónico contiene un componente IA5String codificado punycode, se convierte en el equivalente Unicode.
  • CERT_NAME_SIMPLE_DISPLAY_TYPE: si se devuelve un nombre de sujeto de szOID_RSA_emailAddr o rfc822Name del nombre alternativo del firmante del certificado, y la parte del nombre de host de la dirección de correo electrónico contiene el componente IA5String codificado punycode, se convierte en el equivalente Unicode.
  • CERT_NAME_DNS_TYPE: si el certificado tiene un nombre alternativo del emisor, con una opción DNSName y la parte del nombre de host de la dirección de correo electrónico que contiene el componente IA5String codificado punycode, se convierte en el equivalente Unicode.
  • CERT_NAME_URL_TYPE: el URI está descodificado y sin escape. Si el nombre de host del servidor del URI contiene un componente IA5String codificado punycode, la cadena de nombre de host se convierte en el equivalente Unicode.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.

[in] pvTypePara

Puntero a un DWORD que contiene dwStrType o un identificador de objeto (OID) que especifica el atributo name. El tipo al que apunta está determinado por el valor de dwType.

[out] pszNameString

Puntero a un búfer asignado para recibir la cadena devuelta. Si pszNameString no es NULL y cchNameString no es cero, pszNameString es una cadena terminada en null.

Si CERT_NAME_SEARCH_ALL_NAMES_FLAG se especifica en el parámetro dwFlags y CERT_NAME_DNS_TYPE se establece en el parámetro dwType , la cadena devuelta contendrá todos los nombres DNS que se aplican. Cada cadena de la cadena de salida está terminada en null y la última cadena será doble terminada en null. Si no se encuentra ningún nombre DNS, se devuelve una sola cadena vacía terminada en null.

[in] cchNameString

Tamaño, en caracteres, asignado para la cadena devuelta. El tamaño debe incluir el carácter NULL de terminación.

Valor devuelto

Devuelve el número de caracteres convertidos, incluido el carácter de terminación cero. Si pszNameString es NULL o cchNameString es cero, devuelve el tamaño necesario de la cadena de destino (incluido el carácter NULL de terminación). Si no se encuentra el tipo de nombre especificado, devuelve una cadena vacía terminada en null con un recuento de caracteres devuelto de 1.

Comentarios

Nota

El encabezado wincrypt.h define CertGetNameString como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Crypt32.lib
Archivo DLL Crypt32.dll

Consulte también

Funciones de conversión de datos