Compartir a través de

Función CertNameToStrA (wincrypt.h)

  • Artículo

La función CertNameToStr convierte un nombre codificado en una estructura de CERT_NAME_BLOB en una cadena de caracteres terminada en null.

La representación de cadena sigue las especificaciones de nombre distintivo en RFC 1779. Las excepciones a esta regla se enumeran en la sección Comentarios, a continuación.

Sintaxis

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Parámetros

[in] dwCertEncodingType

El tipo de codificación de certificado que se usó para codificar el nombre. La tipo de codificación de mensajes identificador, contenida en el alto word de este valor, esta función omite.

Este parámetro puede ser el siguiente tipo de codificación de certificado definido actualmente.

Valor Significado
X509_ASN_ENCODING
1 (0x1)
 Especifica la codificación de certificados X.509.

[in] pName

Puntero a la estructura CERT_NAME_BLOB que se va a convertir.

[in] dwStrType

Este parámetro especifica el formato de la cadena de salida. Este parámetro también especifica otras opciones para el contenido de la cadena.

Este parámetro puede ser uno de los siguientes valores.

Valor Significado
CERT_SIMPLE_NAME_STR
1
 Se descartan todos los identificadores de objeto (OID). CERT_RDN entradas están separadas por una coma seguida de un espacio (, ). Varios atributos de un CERT_RDN están separados por un signo más entre espacios ( + ), por ejemplo, Microsoft, Kim Abercrombie + Programador.
CERT_OID_NAME_STR
2
 Los identificadores de identificador de usuario se incluyen con un separador de signo igual (=) de su valor de atributo. CERT_RDN entradas están separadas por una coma seguida de un espacio (, ). Varios atributos de un CERT_RDN están separados por un signo más seguido de un espacio (+ ).
CERT_X500_NAME_STR
3
 Los OID se convierten en sus nombres de clave de X.500; de lo contrario, son iguales que CERT_OID_NAME_STR. Si un OID no tiene un nombre X.500 correspondiente, el OID se usa con un prefijo de OID.

El valor de RDN se cita si contiene espacios en blanco iniciales o finales o uno de los siguientes caracteres:

  • Coma (,)
  • Signo más (+)
  • Signo igual (=)
  • Marca de pulgada (")
  • Barra diagonal inversa seguida de la letra n (\n)
  • Menor que el signo (<)
  • Mayor que el signo (>)
  • Signo de número (#)
  • Punto y coma (;)
El carácter de comillas es una marca de pulgada ("). Si el valor rdn contiene una marca de pulgada, se incluye entre comillas ("").
 

Las siguientes opciones también se pueden combinar con el valor anterior para especificar opciones adicionales para la cadena.

Valor Significado
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Reemplace la coma seguida de un separador de espacio (, ) por un punto y coma seguido de un separador de espacio (; ) .
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Reemplace la coma seguida de un separador de espacio (, ) por una barra diagonal inversa seguida de la letra r seguida de una barra diagonal inversa seguida de la letra n (\r\n) separador.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Reemplace el separador de signo más entre espacios ( + ) por un separador de espacio único.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Deshabilite las comillas.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 El orden de las RDN de la cadena de nombre distintivo se invierte después de la descodificación. Esta marca no se establece de forma predeterminada.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 De forma predeterminada, una cadena de clave X.500 de CERT_RDN_T61_STRING se descodifica como UTF8. Si se produce un error en la descodificación de UTF8, la tecla X.500 se descodifica como un carácter de 8 bits. Use CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG para omitir el intento inicial de descodificar como UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Si el nombre al que apunta el parámetro pName contiene un RDN de correo electrónico y la parte del nombre de host de la dirección de correo electrónico contiene un código punycode codificado IA5String, el nombre se convierte en el equivalente Unicode.

Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.

[out] psz

Puntero a un búfer de caracteres que recibe la cadena devuelta. El tamaño de este búfer se especifica en el parámetro csz.

[in] csz

Tamaño, en caracteres, del búfer de psz. El tamaño debe incluir el carácter NULO de terminación.

Valor devuelto

Devuelve el número de caracteres convertidos, incluido el carácter nulo de terminación.

Si psz es NULL o csz es cero, devuelve el tamaño necesario de la cadena de destino.

Observaciones

Si psz no es NULL y csz no es cero, el psz devuelto siempre es una cadena terminada en NULL.

Se recomienda usar RDN de varios componentes (por ejemplo, CN=James+O=Microsoft) para evitar posibles problemas de ordenación cuando se produce la descodificación. En su lugar, considere la posibilidad de usar RDN con valores únicos (por ejemplo, CN=James, O=Microsoft).

La representación de cadena sigue las especificaciones de nombre distintivos de RFC 1779 excepto las desviaciones descritas en la lista siguiente.

  • Los nombres que contienen comillas se incluyen entre comillas dobles.
  • Las cadenas vacías se incluyen entre comillas dobles.
  • Las cadenas que contienen espacios consecutivos no se incluyen entre comillas.
  • Los valores relativos de nombre distintivo (RDN) de tipo CERT_RDN_ENCODED_BLOB o CERT_RDN_OCTET_STRING tienen formato hexadecimal.
  • Si un OID no tiene un nombre X.500 correspondiente, el prefijo "OID" se usa antes de OID.
  • Los valores de RDN se incluyen entre comillas dobles (en lugar de "\") si contienen espacios en blanco iniciales, espacios en blanco finales o uno de los siguientes caracteres:
    • Coma (,)
    • Signo más (+)
    • Signo igual (=)
    • Marca de pulgada (")
    • Barra diagonal inversa (/)
    • Menor que el signo (<)
    • Mayor que el signo (>)
    • Signo de número (#)
    • Punto y coma (;)
  • El nombre de clave X.500 para stateOrProvinceName (2.5.4.8) OID es "S". Este valor es diferente del nombre de clave RFC 1779 X.500 ("ST").
Además, los siguientes nombres de clave X.500 no se mencionan en RFC 1779, pero esta API puede devolverlo:
Llave Cadena de identificador de objeto
E 1.2.840.113549.1.9.1
T 2.5.4.12
G 2.5.4.42
Yo 2.5.4.43
SN 2.5.4.4
 

Ejemplos

Para obtener un ejemplo que use esta función, consulte

Programa C de ejemplo: conversión de nombres de certificados a ASN.1 y Back.

Nota

El encabezado wincrypt.h define CertNameToStr 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de wincrypt.h
biblioteca de Crypt32.lib
DLL de Crypt32.dll

Consulte también

CertRDNValueToStr

CertStrToName

funciones de conversión de datos de