Función CertGetNameStringW (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 CertGetNameStringW(
  [in]  PCCERT_CONTEXT pCertContext,
  [in]  DWORD          dwType,
  [in]  DWORD          dwFlags,
  [in]  void           *pvTypePara,
  [out] LPWSTR         pszNameString,
  [in]  DWORD          cchNameString
);

Parámetros

[in] pCertContext

Puntero a un contexto de certificado de 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.

Valor 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 del firmante 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 de nombre 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 la extensión Nombre del firmante o 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 no se encuentra la opción DNSName en la extensión, busque el campo Nombre del firmante del OID CN, "2.5.4.3".

Si se encuentra el OID DNSName o CN, 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 de 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.

Valor 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 cadenas 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 permite descodificar 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 al 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 con 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 se apunta viene 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 termina en null y la última cadena finalizará doblemente 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 cero de terminación. 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
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