Función CertStrToNameA (wincrypt.h)
La función
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. 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 |
|---|---|
|
Especifica codificación de certificados X.509. |
[in] pszX500
Puntero a la cadena X.500 terminada en null que se va a convertir. El formato de esta cadena se especifica mediante el parámetro dwStrType.
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 entre comillas mediante dos conjuntos de comillas, por ejemplo, CN="User ""one""".
Un valor que comienza con un signo de número (#) se trata como ASCII hexadecimal 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 siguientes valores.
Las siguientes opciones también se pueden combinar con el valor anterior para especificar opciones adicionales para la cadena.
| Valor | Significado |
|---|---|
|
Solo se admite una coma (,) como separador RDN. |
|
Solo se admite un punto y coma (;) como separador RDN. |
|
Solo se admite una barra diagonal inversa r (\r) o barra diagonal inversa n (\n) como separador RDN. |
|
El signo más (+) se omite como separador y no se admiten varios valores por RDN. |
|
No se admite el comillas. |
|
El orden de las RDN en un nombre distintivo se invierte antes de codificar. Esta marca no se establece de forma predeterminada. |
|
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. |
|
El tipo de valor codificado CERT_RDN_UTF8_STRING se usa en lugar de CERT_RDN_UNICODE_STRING. |
|
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. |
|
Impide forzar la codificación de una clave X.500 CERT_RDN_PRINTABLE_STRING X.500 imprimible mediante UTF-8 (CERT_RDN_UTF8_STRING). Use para habilitar la codificación de claves X.500 como valores Unicode cuando se establece CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG. |
|
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 de IA5String. La codificación Punycode del nombre de host se realiza 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
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, el DWORD contiene el número de bytes almacenados en el búfer.
Si
[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 de pszX500 no es válida, esta función actualiza ppszError 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 no se requiere esta información, pase NULL para este parámetro.
Este parámetro se actualiza para los siguientes códigos de error devueltos de 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.
Observaciones
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.
| Llave | Cadena de identificador de objeto | Identificador de cadena | Tipos de valor RDN |
|---|---|---|---|
| CN | 2.5.4.3 | szOID_COMMON_NAME |
Imprimible T61 |
| L | 2.5.4.7 | szOID_LOCALITY_NAME |
Imprimible T61 |
| O | 2.5.4.10 | szOID_ORGANIZATION_NAME |
Imprimible T61 |
| OU | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
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 | Imprimible |
|
S C |
2.5.4.8 | szOID_STATE_OR_PROVINCE_NAME |
Imprimible T61 |
| CALLE | 2.5.4.9 | szOID_STREET_ADDRESS |
Imprimible T61 |
|
T Título |
2.5.4.12 | szOID_TITLE |
Imprimible T61 |
|
G GivenName |
2.5.4.42 | szOID_GIVEN_NAME |
Imprimible T61 |
|
Yo Iniciales |
2.5.4.43 | szOID_INITIALS |
Imprimible T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
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 con UTF8.
Ejemplos
Para obtener un ejemplo que usa esta función, vea Programa C de ejemplo: Conversión de nombres de certificados a ASN.1 y Back.
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 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 |