Поделиться через

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

  • Статья

Функция CertStrTo Name преобразует строку X.500 в закодированное имя сертификата.

Синтаксис

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) или обратная косая черта (\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. Затем результирующий адрес электронной почты закодирован в виде строки IA5Str ing. Кодировка 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 содержит количество байтов, хранящихся в буфере.

Если pbEncodedNULL, 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
ПОДРАЗДЕЛЕНИЕ 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

УЛ

 2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Пригодный для печатания

T61
УЛИЦА 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
Я

Инициалы

 2.5.4.43 szOID_INITIALS Пригодный для печатания

T61
SN 2.5.4.4 szOID_SUR_NAME Пригодный для печатания

T61
Постоянный ток 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8
 

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

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

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

Примеры

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

Заметка

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

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [классические приложения | Приложения UWP]
минимальный поддерживаемый сервер Windows Server 2003 [классические приложения | Приложения UWP]
целевая платформа Виндоус
заголовка wincrypt.h
библиотеки Crypt32.lib
DLL Crypt32.dll

См. также

CertNameToStr

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

GetLastError

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