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

  • Статья

Функция CertNameToStr преобразует закодированное имя в структуре CERT_NAME_BLOB в символьную строку, завершаемую null.

Строковое представление соответствует спецификациям различающегося имени в RFC 1779. Исключения из этого правила перечислены в разделе Примечания ниже.

Синтаксис

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Параметры

[in] dwCertEncodingType

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

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

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

[in] pName

Указатель на структуру CERT_NAME_BLOB для преобразования.

[in] dwStrType

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

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

Значение Значение
CERT_SIMPLE_NAME_STR
1
 Все идентификаторы объектов (OID) отклоняются. CERT_RDN записи разделяются запятой, за которой следует пробел (, ). Несколько атрибутов в CERT_RDN разделяются знаком "плюс", заключенным в пробелы ( + ), например Microsoft, Ким Аберкромби + Программист.
CERT_OID_NAME_STR
2
 OID включаются с разделителем знака равенства (=) от значения атрибута. CERT_RDN записи разделяются запятой, за которой следует пробел (, ). Несколько атрибутов в CERT_RDN разделяются знаком "плюс", за которым следует пробел (+).
CERT_X500_NAME_STR
3
 Идентификаторы OID преобразуются в имена ключей X.500 ; В противном случае они совпадают с CERT_OID_NAME_STR. Если OID не имеет соответствующего имени X.500, он используется с префиксом OID.

Значение RDN включается в кавычки, если оно содержит начальные или конечные пробелы или один из следующих символов:

  • Запятая (,)
  • Знак "плюс" (+)
  • Знак равенства (=)
  • Дюйм (")
  • Обратная косая черта, за которой следует буква n (\n)
  • Знак меньше (<)
  • Знак "Больше" (>)
  • Знак номера (#)
  • Точка с запятой (;)
Символ кавычек — это знак дюйма ("). Если значение RDN содержит знак дюйма, оно заключено в кавычки ("").
 

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

Значение Значение
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Замените запятую, за которой следует разделитель пробела (, ), точкой с запятой и разделителем пробела (; ).
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Замените запятую, за которой следует пробел (, ), на обратную косую черту, за которой следует буква r, за которой следует обратная косая черта, за которой следует разделитель буквы n (\r\n).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Замените знак "плюс", заключенный в разделитель пробелов ( + ), одним разделителем пробелов.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Отключить кавыкание.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 Порядок RDN в строке различающегося имени после декодирования отменяется. Этот флаг не установлен по умолчанию.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 По умолчанию строка ключа CERT_RDN_T61_STRING X.500 декодируется как UTF8. Если декодирование UTF8 завершается сбоем, ключ X.500 декодируется как 8-разрядный символ. Используйте CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG, чтобы пропустить начальную попытку декодировать как UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Если имя, на которое указывает параметр pName, содержит RDN электронной почты, а часть имени узла адреса электронной почты содержит IA5String в кодировке Punycode, имя преобразуется в эквивалент Юникода.

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

[out] psz

Указатель на буфер символов, получающий возвращаемую строку. Размер этого буфера указывается в параметре csz .

[in] csz

Размер буфера psz (в символах). Размер должен включать завершающий символ NULL.

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

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

Если psz имеет значение NULL или csz равно нулю, возвращает требуемый размер строки назначения.

Комментарии

Если psz не имеет значение NULL , а csz не равен нулю, возвращаемый psz всегда является строкой, заканчивающейся null.

Рекомендуется не использовать многокомпонентные RDN (например, CN=James+O=Microsoft), чтобы избежать возможных проблем с упорядочением при декодировании. Вместо этого рассмотрите возможность использования однозначных RDN (например, CN=James, O=Microsoft).

Строковое представление соответствует спецификациям различающихся имен в RFC 1779 , за исключением отклонений, описанных в следующем списке.

  • Имена, содержащие кавычки, заключаются в двойные кавычки.
  • Пустые строки заключаются в двойные кавычки.
  • Строки, содержащие последовательные пробелы, не заключаются в кавычки.
  • Значения относительного различающегося имени (RDN) типа CERT_RDN_ENCODED_BLOB или CERT_RDN_OCTET_STRING форматируются в шестнадцатеричном формате.
  • Если OID не имеет соответствующего имени X.500, префикс "OID" используется перед OID.
  • Значения RDN заключаются в двойные кавычки (вместо "\"), если они содержат начальные пробелы, конечные пробелы или один из следующих символов:
    • Запятая (,)
    • Знак "плюс" (+)
    • Знак равенства (=)
    • Дюйм (")
    • Обратная косая черта (/)
    • Знак меньше (<)
    • Знак "Больше" (>)
    • Знак номера (#)
    • Точка с запятой (;)
  • Имя ключа X.500 для OID stateOrProvinceName (2.5.4.8) — "S". Это значение отличается от имени ключа X.500 RFC 1779 (ST).
Кроме того, следующие имена ключей X.500 не упоминаются в RFC 1779, но могут быть возвращены этим API:
Ключ Строка идентификатора объекта
E 1.2.840.113549.1.9.1
T 2.5.4.12
G 2.5.4.42
I 2.5.4.43
SN 2.5.4.4
 

Примеры

Пример использования этой функции см. в разделе

Пример программы C. Преобразование имен из сертификатов в ASN.1 и обратно.

Примечание

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

Требования

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

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

CertRDNValueToStr

CertStrToName

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