КриптоПро CSP  

CPGetProvParam

Функция CPGetProvParam() получает параметры криптопровайдера.

BOOL WINAPI CPGetProvParam(
  HCRYPTPROV hProv,
  DWORD dwParam,
  BYTE * pbData,
  DWORD * pdwDataLen,
  DWORD dwFlags
);

Аргументы

hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().
dwParam
[in] Значение, определяющее тип возвращаемых данных. В настоящее время определены следующие значения параметра dwParam.
Значение dwParam Содержимое буфера pbData
PP_CACHE_SIZE Настройки кэширования контейнеров в виде структуры CRYPT_CACHE_SIZE .
PP_PASSWORD_CACHE Настройки кэширования информации аутентификации в контексте.
PP_CONTAINER Имя ключевого контейнера вида CONTAINER, если он имеет имя, в противном случае уникальное имя (см. PP_UNIQUE_CONTAINER). Строка, заканчивающаяся нулем, содержащая имя текущего ключевого контейнера. Подробнее см. Дополнительные параметры и определения .
PP_CONTAINER_VERSION Получает в переменной типа DWORD текущую версию заголовочного файла контейнера. Криптопровайдер КриптоПро CSP 5.0 может работать с версиями KEY_CARRIER_VERSION_V2, KEY_CARRIER_VERSION_V4. Для вновь созданного и еще не записанного контейнера значение не определено, то есть достоверное значение может быть получено только после первой операции, обеспечивающей запись контейнера на носитель.
PP_UNIQUE_CONTAINER Уникальное имя ключевого контейнера, которое включает тип ключевого носителя и может иметь вид: MEDIA\FOLDER, MEDIA\UNIQUE\FOLDER или MEDIA\UNIQUE. Строка, заканчивающаяся нулем, содержащая имя текущего ключевого контейнера. Подробнее см. Дополнительные параметры и определения .
PP_ENUMALGS Поддерживаемые алгоритмы. Подробнее см. CryptGetProvParam в MS CryptoAPI 2.0 World Wide Web link .
PP_ENUMALGS_EX Поддерживаемые алгоритмы. Подробнее см. CryptGetProvParam в MS CryptoAPI 2.0 World Wide Web link .
PP_ENUMCONTAINERS Имя одного из ключевых контейнеров, которые могут быть использованы криптопровайдером, возвращаемое в форме строки, заканчивающейся нулем. Прикладные программы могут вызывать функцию с данным параметром последовательно для перечисления всех ключевых контейнеров, поддерживаемых криптопровайдером. Эта функция не является многопоточной, и поэтому при использовании ее в многопоточном контексте есть вероятность, что не все поддерживаемые ключевые контейнеры будут перечислены.
PP_PROVTYPE Тип криптопровайдера. Возвращается в виде переменной типа DWORD.
PP_IMPTYPE Тип реализации криптопровайдера. Возвращается в виде переменной типа DWORD. В настоящее время определены следующие типы реализации:
  • CRYPT_IMPL_HARDWARE
  • CRYPT_IMPL_SOFTWARE
  • CRYPT_IMPL_MIXED
  • CRYPT_IMPL_UNKNOWN
  • CRYPT_IMPL_REMOVABLE
PP_NAME Имя провайдера в форме строки, заканчивающейся нулем. Это имя соответствует "CSP Name", которое программа setup установила в Windows® Registry.
PP_VERSION Версия криптопровайдера. Возвращается в виде переменной типа DWORD. Например, версия 1.0 представляется как 0x00000100.
PP_VERSION_EX Возвращает версию ядра криптопровайдера в виде структуры PROV_PP_VERSION_EX .
PP_KEYSPEC Тип ключа (всегда либо AT_KEYEXCHANGE, либо AT_SIGNATURE, либо AT_UECSYMMETRICKEY). Возвращается в виде переменной типа DWORD.
PP_KEYX_KEYSIZE_INC Размер модуля открытого ключа обмена AT_KEYEXCHANGE. Возвращается в виде переменной типа DWORD. Размер модуля ключа равен 512 (для ГОСТ Р 34.10-2001).
PP_SIG_KEYSIZE_INC Размер модуля открытого ключа ЭП AT_SIGNATURE. Возвращается в виде переменной типа DWORD. Размер модуля ключа равен 512 (для ГОСТ Р 34.10-2001).
PP_KEYSET_SEC_DESCR Возвращает дескриптор безопасности раздела реестра Windows, где хранятся ключи пользователя.
PP_KEYSET_TYPE Определяет, является ли hProv контекстом ключа компьютера или пользователя. Возвращает DWORD со значением CRYPT_MACHINE_KEYSET, если этот флаг был передан в CPAcquireContext(), или 0 в противном случае.
PP_KEYSTORAGE Возвращает DWORD со значением CRYPT_SEC_DESCR.
PP_ENUMOIDS_EX Поддерживаемые идентификаторы криптографических параметров алгоритмов. Перечисляются строковые величины - OID криптографических параметров алгоритмов.
PP_HASHOID OID текущих параметров алгоритма функции хэширования ГОСТ Р 34.11-94.
PP_SIGNATUREOID OID текущих параметров алгоритма подписи в зависимости от типа провайдера.
PP_DHOID OID текущих параметров алгоритма Диффи-Хеллмана в зависимости от типа провайдера.
PP_CIPHEROID OID текущих параметров алгоритма шифрования ГОСТ 28147-89.
PP_CHECKPUBLIC Передаёт в pbData значение флага проверки открытого ключа.
PP_RANDOM Возвращает в pbData последовательность случайных чисел для установки программного ДСЧ криптопровайдера уровня ядра ОС. Если контекст криптопровайдера hProv открыт в режиме CRYPT_VERIFYCONTEXT, то предварительно будут получены случайные числа с физического или клавиатурного ДСЧ. См. описание параметра PP_USE_HARDWARE_RNG CPSetProvParam().
PP_ENUM_HASHOID Получает перечень идентификаторов криптографических объектов, связанных с функцией хэширования ГОСТ Р 34.11-94.
PP_ENUM_CIPHEROID Получает перечень идентификаторов криптографических объектов, связанных с функцией шифрования ГОСТ 28147-89.
PP_ENUM_SIGNATUREOID Получает перечень идентификаторов криптографических объектов, связанных с функцией цифровой подписи, в зависимости от типа провайдера.
PP_ENUM_DHOID Получает перечень идентификаторов криптографических объектов, связанных с алгоритмом Диффи-Хеллмана, в зависимости от типа провайдера.
PP_HCRYPTPROV Загружает контейнер в память и возвращает DWORD идентифицирующий контейнер.
PP_SELECT_CONTAINER Выводит диалоговое окно выбора контейнера и возвращает имя выбраного пользователем контейнера. Если dwFlags & CRYPT_FQCN, то имя контейнера возвращается в формате FQCN (см. PP_FQCN). Имя контейнера возвращается в текущей кодировке. Возвращаемая строка заканчивается нулем.
PP_FQCN Возвращает FQCN (Fully Qualified Container Name) конетйнера: \\.\<Reader>\<Name>, где <Reader> имя считывателя, на котором находится контейнер, <Name> имя контейнера в текущей кодировке. Возвращаемая строка заканчивается нулем.
PP_ENUMREADERS Информация об одном из считывателей ключевых контейнеров, которые могут быть использованы криптопровайдером. Если dwFlags не содержит специальных значений, то в виде сериализованной псевдоструктуры CRYPT_ENUMREADER_INFO . Если dwFlags & CRYPT_MEDIA, то в виде сериализованной псевдоструктуры CRYPT_ENUMREADER_INFO_MEDIA . Прикладные программы могут вызывать функцию с данным параметром последовательно для перечисления всех считывателей, поддерживаемых криптопровайдером. При вызове с CRYPT_MEDIA функция перечисляет не только считыватели, но и апплеты на считывателях: если на носителе N поддерживаемых апплетов, N последовательных вызовов функции вернут структуру с одним именем считывателя, но разными уникальными номерами. Эта функция не является многопоточной, и поэтому при использовании ее в многопоточном контексте есть вероятность, что не все поддерживаемые считыватели будут перечислены.
PP_ENUMRANDOMS Информация о датчиках случайных чисел, зарегистрированных в провайдере. Возвращает в виде сериализованной псевдоструктуры CRYPT_ENUMRANDOMS_INFO . Прикладные программы могут вызывать функцию с данным параметром последовательно для перечисления всех ДСЧ, поддерживаемых криптопровайдером. Эта функция не является многопоточной, и поэтому при использовании ее в многопоточном контексте есть вероятность, что не все поддерживаемые ДСЧ будут перечислены. При вызове с флагом CRYPT_AVAILABLE производится проверка работоспособности ДСЧ и возвращается флаг с результатом.
PP_INFO Вовращает структуру, содержащую значение таймера криптографического модуля, для недрайвера дополнительно содержит количество ДСРФ, свободное место на файловой системе /var, количество попыток выпусть ключ УЛ, количество успешных смен карт канала "К", количество карт канала выпущенных при последней смене, количество операций подписи
PP_PIN_INFO Возвращает структуру пароля для текущего контейнера в виде структуры CRYPT_PIN_INFO
PP_AUTH_INFO Возвращает описание всех аутентификаций, которые работают в контексте, в виде структуры CRYPT_AUTH_INFO .
PP_PASSWD_TERM Получает термин пароль ("пароль" / "pin-code") для текущего именованного контекста. Возвращаемое значение содержит строку в текущей кодировке, заканчивающуюся нулем. При установке флагов CRYPT_AUTH_TYPE_CONT, CRYPT_AUTH_TYPE_ADMIN, CRYPT_AUTH_TYPE_PUK, CRYPT_AUTH_TYPE_USER_PIN1, CRYPT_AUTH_TYPE_USER_PIN2 выводится термин для соответствующей аутентификации, если она есть в данном контексте, в противном случае возвращает ошибку NTE_BAD_FLAGS. При установке флагов в значение 0 выводится термин основной аутентификации.
PP_SAME_MEDIA Провека наличия носителя, соответствующего данному контейнеру, в считывателе. Возвращает TRUE, если носитель есть. FALSE и код ошибки SCARD_W_REMOVED_CARD, если отсутствует. Буфер pbData не используется.
PP_VERSION_TIMESTAMP Получение даты и времени завершения компиляции в формате "day month year" "hh:mm:ss".
PP_SECURITY_LEVEL Возвращает DWORD уровня сертификации данного криптографического модуля KC1: 1, KC2: 2, KC3: 3, KB1: 4, KB2: 5, KA1: 6
PP_FAST_CODE_FLAGS

Параметр предназначен для определения, какой код - быстрый или медленный - используется в провайдере на компьютерах, оснащенных процессором Intel Pentium 4. В pbData возвращается DWORD с флагами CSP_FAST_CODE_*. Параметр dwFlags должен содержать хотя бы один из флагов, указанных ниже.

Флаги для определения списка проверяемых функций.
CRYPT_FAST_CODE_ALL_KERNEL_FUNCTIONS - запрос кода функций провайдера уровня ядра ОС.
CRYPT_FAST_CODE_ALL_USER_FUNCTIONS - запрос кода функций провайдера уровня пользователя.
CRYPT_FAST_CODE_ALL_FUNCTIONS - запрос кода всех функций провайдера.
CRYPT_FAST_CODE_GET_SETFN - запроса результата работы функции определения процессора.

PP_ENUM_CONTAINER_EXTENSION Имя одного из расширений ключевого контейнера, возвращаемое в форме структуры CONTAINER_EXTENSION. Прикладные программы могут вызывать функцию с данным параметром последовательно для перечисления всех расширений ключевого контейнера. Эта функция не является многопоточной, и поэтому при использовании ее в многопоточном контексте есть вероятность, что не все поддерживаемые считыватели будут перечислены.
PP_PASSWORD_CACHE Месторасположение кодируется следующим образом: Аутентификационная информация не сохраняется в памяти, а сразу передается носителю. Соответствует значению 1. Аутентификационная информация сохраняется в контексте контейнера. Соответствует значению 2. Аутентификационная информация сохраняется в глобальном кэше аутентификационной информации. Соответствует значению 3. Результат передается в переменной типа DWORD. Младшая (0) hex-цифра (биты 0..3) содержит значение, соответствующее расположению аутентификации контейнера (CONT). Следующая (1) hex-цифра (биты 4..7) содержит значение, соответствующее расположению аутентификации администратора (ADMIN). Следующая (2) hex-цифра (биты 8..11) содержит значение, соответствующее расположению аутентификации разблокирования (PUK). Следующая (3) hex-цифра (биты 12..15) содержит значение, соответствующее расположению пользовательской аутентификации (USER_PIN1). Следующая (4) hex-цифра (биты 16..19) содержит значение, соответствующее расположению пользовательской аутентификации (USER_PIN2).
PP_SELFTEST [TODO:XX] Документация предварительная. [TODO:XX] Вызывает функцию самотестирования и контроля целостности. Для dwFlags равного нулю, тестируется оконечное СКЗИ. Результат возвращается в виде структуры PROV_PP_SELFTEST . При установке флага CP_CRYPT_SET_TESTER_STATUS устанавливается статус самотестирования. При установке флага CP_CRYPT_SELFTEST_FORCE_FAIL форсируется ошибка. При установке флага CP_CRYPT_SELFTEST_FORCE_SUCCESS форсируется успех.
PP_LICENSE Возвращает серийный номер клиентской лицензии на CSP. Если лицензия не установлена или недействительна, функция возвращает FALSE. Серийный номер возвращается в виде строки символов типа char, заканчивающейся нулём и не содержащей разделителей.
PP_WND_ENUM_READERS Служебный параметр. Перечисляет считыватели. Предназначен для использования в окне выбора считывателя.
PP_WND_READER_ICON Служебный параметр. Возвращает внутреннее представление иконки считывателя. Предназначен для использования в окне выбора считывателя.
PP_CARRIER_TYPES Параметр, предназначенный для установления и получения допустимых режимов работы носителей (CSP, ФКН, ФКН с SM).
PP_CARRIER_FREE_SPACE Параметр для получения количества свободного места на носителе в байтах.
PP_MEDIA_TYPE Параметр, предназначенный для установки и получения строки медиа-типа текущего провайдера.
PP_UNIQUE_FILTER Параметр, предназначенный для установки и получения регулярного выражения, по которому фильтруются допустимые уники носителей.
PP_CARRIER_FLAGS Параметр, предназначенный для получения свойств носителя, соответствующего открытому контексту.
PP_HARDWARE_STORE_FLAGS Параметр, предназначенный для получения специфических флагов считывателя/носителя.
PP_EXTERNAL_CONTAINER_LINK Параметр получает из разделенного по схеме NK контейнера открытую информацию, для создания копии этого контейнера.
PP_EXCHANGE_KEY_FP Возвращает первые 8 байт открытого ключа обмена. Если в контейнере нет ключа обмена, функция возвращает FALSE.
PP_SIGNATURE_KEY_FP Возвращает первые 8 байт ключа проверки подписи. Если в контейнере нет ключа подписи, функция возвращает FALSE.
PP_CPU_USAGE Возвращает в pbData загрузку ЦП в виде структуры CPU_INFO . Параметр dwFlags должен содержать один из следующих флагов: CPU_USAGE, CPU_USAGE_BY_PROC.
PP_MEMORY_USAGE Возвращает в pbData DWORD, содержащий объём используемой памяти в KB. Параметр dwFlags должен содержать один из следующих флагов: VIRTUAL_MEMORY_TOTAL, VIRTUAL_MEMORY_USED, VIRTUAL_MEMORY_USED_BY_CURRENT_PROC, PHYSICAL_MEMORY_TOTAL, PHYSICAL_MEMORY_USED, PHYSICAL_MEMORY_USED_BY_CURRENT_PROC.
PP_CONTAINER_STATUS Будучи вызван без флагов, возвращает в pbData DWORD, который содержит S_OK, если контейнер находится в рабочем состоянии; флаг CONTAINER_INVALID_HEADER - если в контейнере поврежден заголовочный файл, флаг CONTAINER_INVALID_UNKNOWN - в случае каких-то иных повреждений. Если параметр dwFlags равен CRYPT_KEYSET_ENUM_FLAG, то возвращается структура CRYPT_KEYSET_ENUM , перечисляющая лежащие в контейнере ключи. Использование этого параметра не требует аутентификации, что позволяет гарантированно получить информацию о ключах в контейнере, не вводя пароль.
pbData
[out] Указатель на буфер, содержащий данные параметра. Функция копирует соответствующие параметру данные в буфер. Формат этих данных зависит от значения dwParam. Если аргумент функции - NULL, то данные не копируются. Требуемый размер буфера в байтах возвращается в pdwDataLen. Подробнее см. Возвращение данных неопределенной длины. Как отмечено в CryptGetProvParam в MS CryptoAPI 2.0 World Wide Web link , когда читается один из параметров перечисления, возвращенное в pdwDataLen значение будет равно размеру самого большого элемента в списке перечисления.
pdwDataLen
[in/out] Указатель на буфер, содержащий длину данных параметра. При вызове функции указанный аргумент содержит размер передаваемого буфера pbData в байтах. После возврата из неё pbData содержит число байтов данных параметра, скопированных в буфер pbData. Если буфер, соответствующий pbData, недостаточно велик, чтобы в него копировать запрошенные данные, через функцию GetLastError будет возвращён код ошибки ERROR_MORE_DATA. В этом случае требуемый размер буфера возвращается в pdwDataLen. Если эта функция завершается с кодом ошибки, отличным от ERROR_MORE_DATA, в этом аргументе возвращается ноль.
dwFlags
[in] Значения флагов. В настоящее время определены следующие значения флагов:
Значение dwFlags Описание
CRYPT_FIRST Используется совместно с параметром перечисления (например, PP_ENUMALGS, PP_ENUMALGS_EX или PP_ENUMCONTAINERS). При использовании этого флага возвращается первый элемент в списке перечисления, в противном случае возвращается следующий элемент в списке. Если флаг используется совместно с параметром, не являющимся параметром перечисления, то возвращается код ошибки NTE_BAD_FLAGS.
CRYPT_UNIQUE Используется совместно с параметром PP_ENUMCONTAINERS. При использовании этого флага первыми по приоритету перед обычными именами возвращаются уникальные имена контейнеров. Если под уникальный номер выделено достаточно памяти, после уникального номера копируется обычное имя контейнера.
CRYPT_FQCN Используется совместно с параметрами PP_ENUMCONTAINERS, PP_SELECT_CONTAINER. При использовании этого флага имя контейнера возвращается в формате FQCN (см. PP_FQCN). Имя контейнера возвращается в текущей кодировке. Возвращаемая строка заканчивается нулем.
CRYPT_FILTER_PROVIDER_TYPE Используется совместно с параметрами PP_ENUMCONTAINERS, PP_SELECT_CONTAINER. При использовании этого флага при перечислении выбираются только контейнеры с ключами, совпадающими с типом криптопровайдера.
CRYPT_FILTER_EXPORTABLE Используется совместно с параметрами PP_ENUMCONTAINERS, PP_SELECT_CONTAINER. При использовании этого флага при перечислении выбираются только контейнеры с экспортируемыми ключами.
CRYPT_PROPERTIES Используется совместно с параметром PP_ENUMCONTAINERS. При использовании этого флага появляется возможность получения свойств контейнера из перечисления через поле property_flags.
SECURITY_INFORMATION Если dwParam установлен в PP_KEYSET_SEC_DESCR, будет возвращен дескриптор безопасности раздела реестра, содержащего ключевой контейнер. В этом случае dwFlags используется, чтобы передать битовые флаги, объединяемые поразрядной операцией OR. Указатель на дескриптор безопасности возвращается в аргументе pbData, длина дескриптора безопасности возвращается в аргументе pcbData. Для получения дополнительной информации, см. RegGetKeySecurity и RegSetKeySecurity. Следующий список содержит определённые битовые маски, используемые для возврата требуемой информации.
  • OWNER_SECURITY_INFORMATION - Указывает идентификатор владельца упомянутого объекта.
  • GROUP_SECURITY_INFORMATION - Указывает идентификатор первичный группы упомянутого объекта.
  • DACL_SECURITY_INFORMATION - Указывает идентификатор дискреционного ACL упомянутого объекта.
  • SACL_SECURITY_INFORMATION - Указывает идентификатор системного ACL упомянутого объекта.

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError.
Коды возвратаОписание
ERROR_INVALID_PARAMETERОдин из параметров содержит некорректное значение. Чаще всего это некорректный указатель.
ERROR_MORE_DATAРазмер буфера pbData недостаточен для копирования затребованных данных.
ERROR_NO_MORE_ITEMSДостигнут конец списка перечисления. Данные в буфере pbData непригодны. Данный тип ошибки может возвращаться, только если dwParam имеет значение PP_ENUMALGS, PP_ENUMALGS_EX, PP_ENUMCONTAINERS, PP_ENUMOIDS_EX, PP_ENUM_HASHOID, PP_ENUM_CIPHEROID, PP_ENUM_SIGNATUREOID, PP_ENUM_DHOID, или PP_ENUMREADERS.
NTE_BAD_FLAGSПараметр dwFlags имеет некорректное значение.
NTE_BAD_TYPEdwParam определяет неизвестный параметр.
SCARD_W_CANCELLED_BY_USERПользователь прервал операцию нажатием клавиши Cancel.
SCARD_W_WRONG_CHVПользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam, неправильный.
SCARD_E_INVALID_CHVПользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam, имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы.
SCARD_W_CHV_BLOCKEDВвод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток, разрешенное картой для ввода.
NTE_SILENT_CONTEXTОперация не может быть выполнена без пользовательского интерфейса.
SCARD_W_REMOVED_CARDНоситель контейнера был удален из считывателя.
NTE_BAD_SIGNATUREВстроенный тест и/или контроль целостности СКЗИ выдал ошибку. Результаты находятся по адресу pbData, в виде структуры PROV_PP_SELFTEST .
SCARD_E_NO_KEY_CONTAINERКонтекст открыт с флагом CRYPT_DEFAULT_CONTAINER_OPTIONAL, и не связан ни с одним контейнером, поэтому выполнение данной операции недоступно.

Примечания

При указании параметра PP_SIGNATUREOID или PP_DHOID выбирается параметр, соответствующий типу провайдера. При указании параметра PP_ENUM_SIGNATUREOID или PP_ENUM_DHOID выбор соответствующего перечня идентификаторов производится аналогично.

PP_CIPHEROID для PROV_GOST_2001_DH по умолчанию равен "1.2.643.2.2.31.1", вариант "Верба-О"; для PROV_GOST_2012_256 или PROV_GOST_2012_512 равен "1.2.643.7.1.2.5.1.1", вариант ТК26 Z.

Требования:

AIX: 6/7.
FreeBSD: 11/12, pfSense 2.x.
Linux: LSB 4.x (RHEL 5/6/7/8, SuSE 11SP4/12/15, Oracle Linux 5/6/7/8, CentOS 6/7/8, Ubuntu 14.04/16.04/18.04/19.10, Linux Mint 18/19, Fedora 28/29/30/31, Debian 8/9/10 и др.).
Solaris: 10/11.
Mac OS X: 10.9/10.10/10.11/10.12/10.13/10.14/10.15.
iOS: 8/9/10/11/12/13.
Sailfish: 2/3.
Windows: 7/8/8.1/10, Server 2008/2008R2/2012/2012R2/2016/2019.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCGetProvParam .

См. также

CPAcquireContext() ,CPSetProvParam() ,CPGetProvParam в MS CSP World Wide Web link ,CryptGetProvParam в MS CryptoAPI 2.0 World Wide Web link