Compartir a través de

Función CertStrToNameA (wincrypt.h)

  • Artículo

La función CertStrToName convierte una cadena X.500 terminada en null en un nombre de certificado codificado.

Sintaxis

BOOL CertStrToNameA(
  [in]            DWORD  dwCertEncodingType,
  [in]            LPCSTR pszX500,
  [in]            DWORD  dwStrType,
  [in, optional]  void   *pvReserved,
  [out]           BYTE   *pbEncoded,
  [in, out]       DWORD  *pcbEncoded,
  [out, optional] LPCSTR *ppszError
);

Parámetros

[in] dwCertEncodingType

Tipo de codificación de certificado que se usó para codificar la cadena. Esta función omite el identificador de tipo de codificación de mensaje , contenido en el alto WORD de este valor.

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] pszX500

Puntero a la cadena X.500 terminada en null que se va a convertir. El parámetro dwStrType especifica el formato de esta cadena.

Se espera que esta cadena tenga el mismo formato que la salida de la función CertNameToStr .

[in] dwStrType

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

Si no se combinan marcas con el especificador de tipo de cadena, la cadena puede contener una coma (,) o un punto y coma (;) como separadores en el nombre distintivo relativo (RDN) y un signo más (+) como separador en varios valores de RDN.

Se admiten comillas (""). Una comilla se puede incluir en un valor entrecomillado mediante dos conjuntos de comillas, por ejemplo, CN="User ""one""".

Un valor que comienza con un signo de número (#) se trata como hexadecimal ASCII y se convierte en un CERT_RDN_OCTET_STRING. Se omite el espacio en blanco incrustado. Por ejemplo, 1.2.3 = # AB CD 01 es el mismo que 1.2.3=#ABCD01.

Se omite el espacio en blanco que rodea las claves, los identificadores de objeto y los valores.

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

Valor Significado
CERT_SIMPLE_NAME_STR
1
 Este tipo de cadena no se admite.
CERT_OID_NAME_STR
2
 Valida que se admite el tipo de cadena. La cadena puede ser un identificador de objeto (OID) o un nombre X.500.
CERT_X500_NAME_STR
3
 Idéntico a CERT_OID_NAME_STR. Valida que se admite el tipo de cadena. La cadena puede ser un identificador de objeto (OID) o un nombre X.500.
 

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

Valor Significado
CERT_NAME_STR_COMMA_FLAG
0x04000000
 Solo se admite una coma (,) como separador de RDN.
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Solo se admite un punto y coma (;) como separador de RDN.
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Solo se admite una barra diagonal inversa r (\r) o barra diagonal inversa n (\n) como separador RDN.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 El signo más (+) se omite como separador y no se admiten varios valores por RDN.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 No se admite el entrecomillado.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 El orden de los RDN en un nombre distintivo se invierte antes de la codificación. Esta marca no se establece de forma predeterminada.
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
 El tipo de valor codificado CERT_RDN_T61_STRING se usa en lugar de CERT_RDN_UNICODE_STRING. Esta marca se puede usar si todos los caracteres Unicode son menores o iguales que 0xFF.
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
 El tipo de valor codificado CERT_RDN_UTF8_STRING se usa en lugar de CERT_RDN_UNICODE_STRING.
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
 Obliga a codificar la clave X.500 como una cadena UTF-8 (CERT_RDN_UTF8_STRING) en lugar de como una cadena Unicode imprimible (CERT_RDN_PRINTABLE_STRING). Este es el valor predeterminado para las entidades de certificación de Microsoft a partir de Windows Server 2003.
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
 Impide forzar la codificación de una clave X.500 X.500 imprimible mediante UTF-8 CERT_RDN_PRINTABLE_STRING (CERT_RDN_UTF8_STRING). Se usa para habilitar la codificación de claves X.500 como valores Unicode cuando se establece CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Si la cadena contiene un valor RDN de correo electrónico y la dirección de correo electrónico contiene caracteres Unicode fuera del conjunto de caracteres ASCII, la parte del nombre de host de la dirección de correo electrónico se codifica en Punycode. A continuación, la dirección de correo electrónico resultante se codifica como una cadena IA5String . La codificación punycode del nombre de host se realiza con una etiqueta por etiqueta.

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

[in, optional] pvReserved

Reservado para uso futuro y debe ser NULL.

[out] pbEncoded

Puntero a un búfer que recibe la estructura codificada.

El tamaño de este búfer se especifica en el parámetro pcbEncoded .

Este parámetro puede ser NULL para obtener el tamaño necesario del búfer con fines de asignación de memoria. Para obtener más información, vea Recuperar datos de longitud desconocida.

[in, out] pcbEncoded

Puntero a un DWORD que, antes de llamar a la función, contiene el tamaño, en bytes, del búfer al que apunta el parámetro pbEncoded . Cuando la función devuelve, DWORD contiene el número de bytes almacenados en el búfer.

Si pbEncoded es NULL, DWORD recibe el tamaño, en bytes, necesario para el búfer.

[out, optional] ppszError

Puntero a un puntero de cadena que recibe información de error adicional sobre una cadena de entrada que no es válida.

Si la cadena pszX500 no es válida, ppszError se actualiza mediante esta función para que apunte al principio de la secuencia de caracteres que no es válida. Si no se detecta ningún error en la cadena de entrada, ppszError se establece en NULL.

Si esta información no es necesaria, pase NULL para este parámetro.

Este parámetro se actualiza para los siguientes códigos de error devueltos desde GetLastError.

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

Valor devuelto

Devuelve un valor distinto de cero si es correcto o cero de lo contrario.

Para obtener información de error extendida, llame a GetLastError.

Comentarios

La tabla siguiente contiene las claves X.500 admitidas, su cadena de identificador de objeto correspondiente, el identificador de cadena (de Wincrypt.h) y los tipos de valor.

Clave Cadena de identificador de objeto Identificador de cadena Tipos de valor RDN
CN 2.5.4.3 szOID_COMMON_NAME Carácter imprimible

T61
L 2.5.4.7 szOID_LOCALITY_NAME Carácter imprimible

T61
O 2.5.4.10 szOID_ORGANIZATION_NAME Carácter imprimible

T61
OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME Carácter imprimible

T61
E

Correo electrónico

 1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME Carácter imprimible
S

ST

 2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Carácter imprimible

T61
STREET 2.5.4.9 szOID_STREET_ADDRESS Carácter imprimible

T61
T

Título

 2.5.4.12 szOID_TITLE Carácter imprimible

T61
G

GivenName

 2.5.4.42 szOID_GIVEN_NAME Carácter imprimible

T61
I

Initials

 2.5.4.43 szOID_INITIALS Carácter imprimible

T61
SN 2.5.4.4 szOID_SUR_NAME Carácter imprimible

T61
DC 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8
 

Si se permite Imprimir o T61 como tipo de valor RDN para la clave, Printable se selecciona automáticamente si el componente de cadena de nombre es miembro de los siguientes conjuntos de caracteres:

  • A, B, ..., Z
  • a, b, ..., z
  • 0, 1, ..., 9
  • (espacio) ' ( ) + , - . / : = ?

Los tipos T61 están codificados en UTF8.

Ejemplos

Para ver un ejemplo que usa esta función, vea Programa C de ejemplo: Convertir nombres de certificados a ASN.1 y Atrás.

Nota

El encabezado wincrypt.h define CertStrToName 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

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

CertNameToStr

Funciones de conversión de datos

Obtener último error

Recuperar datos de longitud desconocida