Функция 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 .
Этот параметр может быть следующим определенным в настоящее время типом кодирования сертификата.
| Значение | Значение |
|---|---|
|
Задает кодировку сертификата 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.
Пробелы, окружающие ключи, идентификаторы объектов и значения, игнорируются.
Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Этот тип строки не поддерживается. |
|
Проверяет, поддерживается ли тип строки. Строка может быть идентификатором объекта (OID) или именем X.500. |
|
Идентично CERT_OID_NAME_STR. Проверяет, поддерживается ли тип строки. Строка может быть идентификатором объекта (OID) или именем X.500. |
Следующие параметры также можно объединить с приведенным выше значением, чтобы указать дополнительные параметры для строки.
| Значение | Значение |
|---|---|
|
В качестве разделителя RDN поддерживается только запятая (,). |
|
В качестве разделителя RDN поддерживается только точка с запятой (;)). |
|
В качестве разделителя RDN поддерживается только обратная косая черта r (\r) или обратная косая черта n (\n). |
|
Знак "плюс" (+) игнорируется как разделитель, и несколько значений в RDN не поддерживаются. |
|
Кавыкание не поддерживается. |
|
Порядок RDN в различаемом имени отменяется перед кодировкой. Этот флаг не установлен по умолчанию. |
|
Вместо CERT_RDN_UNICODE_STRING используется закодированный тип значения CERT_RDN_T61_STRING. Этот флаг можно использовать, если все символы Юникода меньше или равны 0xFF. |
|
Вместо CERT_RDN_UNICODE_STRING используется закодированный тип значения CERT_RDN_UTF8_STRING. |
|
Принудительно кодирует ключ X.500 как строку UTF-8 (CERT_RDN_UTF8_STRING), а не как печатаемую строку Юникода (CERT_RDN_PRINTABLE_STRING). Это значение по умолчанию для центров сертификации Майкрософт, начиная с Windows Server 2003. |
|
Предотвращает принудительное кодирование печатного ключа Юникода (CERT_RDN_PRINTABLE_STRING) X.500 с помощью UTF-8 (CERT_RDN_UTF8_STRING). Используйте , чтобы включить кодировку ключей X.500 в качестве значений Юникода при CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG. |
|
Если строка содержит значение 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 |