Función CertStrToNameW (wincrypt.h)
La función CertStrToName convierte una cadena X.500 terminada en null en un nombre de certificado codificado.
Sintaxis
BOOL CertStrToNameW(
[in] DWORD dwCertEncodingType,
[in] LPCWSTR pszX500,
[in] DWORD dwStrType,
[in, optional] void *pvReserved,
[out] BYTE *pbEncoded,
[in, out] DWORD *pcbEncoded,
[out, optional] LPCWSTR *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 la palabra alta de este valor.
Este parámetro puede ser el siguiente tipo de codificación de certificado definido actualmente.
| Valor | Significado |
|---|---|
|
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 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 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 igual 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 |
|---|---|
|
Este tipo de cadena no se admite. |
|
Valida que se admite el tipo de cadena. La cadena puede ser un identificador de objeto (OID) o un nombre X.500. |
|
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 |
|---|---|
|
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 entrecomillado. |
|
El orden de las RDN en un nombre distintivo se invierte antes de la codificación. 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 CERT_RDN_PRINTABLE_STRING X.500 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 juego 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 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 Recuperación de 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 se devuelve la función, 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 juegos 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: 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 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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de