Функция CertStrToNameA (wincrypt.h)

Функция CertStrToName преобразует строку X.500 , завершаемую null, в закодированное имя сертификата.

Синтаксис

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
);

Параметры

[in] dwCertEncodingType

Тип кодирования сертификата, который использовался для кодирования строки. Эта функция игнорирует идентификатор типа кодирования сообщений , содержащийся в высоком значении WORD .

Этот параметр может быть следующим определенным в настоящее время типом кодирования сертификата.

Значение Значение
X509_ASN_ENCODING
1 (0x1)
Задает кодировку сертификата X.509 .

[in] pszX500

Указатель на преобразуемую строку X.500 со значением NULL. Формат этой строки определяется параметром dwStrType .

Ожидается, что эта строка будет иметь тот же формат, что и выходные данные функции CertNameToStr .

[in] dwStrType

Этот параметр указывает тип строки. Этот параметр также задает другие параметры для содержимого строки.

Если флаги не объединяются с описателем типа строки, строка может содержать запятую (,) или точку с запятой (;) в качестве разделителей в относительном различаемом имени (RDN) и знак "плюс" (+) в качестве разделителя в нескольких значениях RDN.

Поддерживаются кавычки (""). Кавычки можно включить в кавычки с помощью двух наборов кавычек, например CN="User ""one"".

Значение, начинающееся со знака числа (#), обрабатывается как шестнадцатеричное значение ASCII и преобразуется в CERT_RDN_OCTET_STRING. Внедренные пробелы игнорируются. Например, 1.2.3 = # AB CD 01 совпадает с 1.2.3=#ABCD01.

Пробелы, окружающие ключи, идентификаторы объектов и значения, игнорируются.

Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
CERT_SIMPLE_NAME_STR
1
Этот тип строки не поддерживается.
CERT_OID_NAME_STR
2
Проверяет, поддерживается ли тип строки. Строка может быть идентификатором объекта (OID) или именем X.500.
CERT_X500_NAME_STR
3
Идентично CERT_OID_NAME_STR. Проверяет, поддерживается ли тип строки. Строка может быть идентификатором объекта (OID) или именем X.500.
 

Следующие параметры также можно объединить с приведенным выше значением, чтобы указать дополнительные параметры для строки.

Значение Значение
CERT_NAME_STR_COMMA_FLAG
0x04000000
В качестве разделителя RDN поддерживается только запятая (,).
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
В качестве разделителя RDN поддерживается только точка с запятой (;)).
CERT_NAME_STR_CRLF_FLAG
0x08000000
В качестве разделителя RDN поддерживается только обратная косая черта r (\r) или обратная косая черта n (\n).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
Знак "плюс" (+) игнорируется как разделитель, и несколько значений в RDN не поддерживаются.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
Кавыкание не поддерживается.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
Порядок RDN в различаемом имени отменяется перед кодировкой. Этот флаг не установлен по умолчанию.
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
Вместо CERT_RDN_UNICODE_STRING используется закодированный тип значения CERT_RDN_T61_STRING. Этот флаг можно использовать, если все символы Юникода меньше или равны 0xFF.
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
Вместо CERT_RDN_UNICODE_STRING используется закодированный тип значения CERT_RDN_UTF8_STRING.
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
Принудительно кодирует ключ X.500 как строку UTF-8 (CERT_RDN_UTF8_STRING), а не как печатаемую строку Юникода (CERT_RDN_PRINTABLE_STRING). Это значение по умолчанию для центров сертификации Майкрософт, начиная с Windows Server 2003.
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
Предотвращает принудительное кодирование печатного ключа Юникода (CERT_RDN_PRINTABLE_STRING) X.500 с помощью UTF-8 (CERT_RDN_UTF8_STRING). Используйте , чтобы включить кодировку ключей X.500 в качестве значений Юникода при CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
Если строка содержит значение RDN электронной почты, а адрес электронной почты содержит символы Юникода за пределами набора символов ASCII, часть адреса электронной почты с именем узла кодируется в Punycode. Затем результирующий адрес электронной почты кодируется как строка IA5String . Кодировка Punycode имени узла выполняется по меткам.

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.

[in, optional] pvReserved

Зарезервировано для использования в будущем и должно иметь значение NULL.

[out] pbEncoded

Указатель на буфер, который получает закодированную структуру.

Размер этого буфера указывается в параметре pcbEncoded .

Этот параметр может иметь значение NULL , чтобы получить требуемый размер буфера для целей выделения памяти. Дополнительные сведения см. в разделе Извлечение данных неизвестной длины.

[in, out] pcbEncoded

Указатель на DWORD , который перед вызовом функции содержит размер (в байтах) буфера, на который указывает параметр pbEncoded . При возврате функции DWORD содержит количество байтов, хранящихся в буфере.

Если pbEncoded имеет значение NULL, DWORD получает размер в байтах, необходимый для буфера.

[out, optional] ppszError

Указатель на строковый указатель, получающий дополнительные сведения об ошибке о недопустимой входной строке.

Если строка pszX500 недопустимая, функция ppszError обновляется так, чтобы она указывала на начало недопустимой последовательности символов. Если во входной строке ошибки не обнаружены, параметру ppszError присваивается значение NULL.

Если эти сведения не требуются, передайте значение NULL для этого параметра.

Этот параметр обновляется для следующих кодов ошибок, возвращаемых из GetLastError.

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

Возвращаемое значение

Возвращает ненулевое значение в случае успешного выполнения или ноль в противном случае.

Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError.

Комментарии

В следующей таблице содержатся поддерживаемые ключи X.500, соответствующая строка идентификатора объекта, идентификатор строки (из Wincrypt.h) и типы значений.

Ключ Строка идентификатора объекта Строковый идентификатор Типы значений RDN
CN 2.5.4.3 szOID_COMMON_NAME Печатные символы

T61

L 2.5.4.7 szOID_LOCALITY_NAME Печатные символы

T61

O 2.5.4.10 szOID_ORGANIZATION_NAME Печатные символы

T61

OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME Печатные символы

T61

E

Адрес электронной почты

1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME Печатные символы
S

ST

2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Печатные символы

T61

STREET 2.5.4.9 szOID_STREET_ADDRESS Печатные символы

T61

T

Заголовок

2.5.4.12 szOID_TITLE Печатные символы

T61

G

GivenName

2.5.4.42 szOID_GIVEN_NAME Печатные символы

T61

I

Инициалы

2.5.4.43 szOID_INITIALS Печатные символы

T61

SN 2.5.4.4 szOID_SUR_NAME Печатные символы

T61

DC 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8

 

Если в качестве типа значения RDN для ключа разрешено использовать printable или T61, функция Printable автоматически выбирается, если компонент строки имени является членом следующих наборов символов:

  • A, B, ..., Z
  • a, b, ..., z
  • 0, 1, ..., 9
  • (пробел) ' ( ) + , - . / : = ?

Типы T61 имеют кодировку UTF8.

Примеры

Пример использования этой функции см. в разделе Пример программы C. Преобразование имен из сертификатов в ASN.1 и Обратно.

Примечание

Заголовок wincrypt.h определяет CertStrToName в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header wincrypt.h
Библиотека Crypt32.lib
DLL Crypt32.dll

См. также раздел

CertNameToStr

Функции преобразования данных

Getlasterror

Получение данных неизвестной длины