КриптоПро CSP  

CPCGetProvParam

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

DWORD CPCAPI CPCGetProvParam(
  HCRYPTMODULE hCSP,
  HCRYPTPROV hProv,
  DWORD dwParam,
  BYTE * pbData,
  DWORD * pdwDataLen,
  DWORD dwFlags
);

Аргументы

hCSP
[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().
dwParam
[in] Значение, определяющее тип возвращаемых данных. В настоящее время определены следующие значения параметра dwParam.
Значение dwParam Содержимое буфера pbData
PP_CONTAINER Имя ключевого контейнера вида CONTAINER, если он имеет имя, в противном случае уникальное имя (см. PP_UNIQUE_CONTAINER). Строка, заканчивающаяся нулем, содержащая имя текущего ключевого контейнера. Подробнее см. Дополнительные параметры и определения .
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
PP_HANDLE_COUNT Количество используемых хэндлов. Должен быть установлен параметр dwFlags. При значении dwFlags = 0 - текущее количество. При значении dwFlags = 1 - максимальное. Возвращается в виде переменной типа DWORD.
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, если этот флаг был передан в CPCAcquireContext(), или 0 в противном случае.
PP_KEYSTORAGE Возвращает DWORD со значением CRYPT_SEC_DESCR.
PP_ENUMOIDS_EX Поддерживаемые идентификаторы криптографических параметров алгоритмов. Перечисляются строковые величины - OID криптографических параметров алгоритмов.
PP_HASHOID OID текущих параметров алгоритма функции хэширования.
PP_SIGNATUREOID OID текущих параметров алгоритма подписи в зависимости от типа провайдера.
PP_DHOID OID текущих параметров алгоритма Диффи-Хеллмана в зависимости от типа провайдера..
PP_CIPHEROID OID текущих параметров алгоритма шифрования.
PP_CHECKPUBLIC Передаёт в pbData значение флага проверки открытого ключа.
PP_RANDOM Возвращает в pbData последовательность случайных чисел для установки программного ДСЧ криптопровайдера уровня ядра ОС. Если контекст криптопровайдера hProv открыт в режиме CRYPT_VERIFYCONTEXT, то предварительно будут получены случайные числа с физического или клавиатурного ДСЧ. См. описание параметра PP_USE_HARDWARE_RNG CPCSetProvParam().
PP_ENUM_HASHOID Получает перечень идентификаторов криптографических объектов, связанных с функцией хэширования.
PP_ENUM_CIPHEROID Получает перечень идентификаторов криптографических объектов, связанных с функцией шифрования.
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 . Прикладные программы могут вызывать функцию с данным параметром последовательно для перечисления всех считывателей, поддерживаемых криптопровайдером. Эта функция не является многопоточной, и поэтому при использовании ее в многопоточном контексте есть вероятность, что не все поддерживаемые считыватели будут перечислены.
PP_INFO Вовращает структуру, содержащую значение таймера криптографического модуля, для недрайвера дополнительно содержит количество ДСРФ, свободное место на файловой системе /var, количество попыток выпусть ключ УЛ, количество успешных смен карт канала "К", количество карт канала выпущенных при последней смене, количество операций подписи
PP_PIN_INFO Возвращает структуру пароля для текущего контейнера в виде структуры CRYPT_PIN_INFO
PP_PASSWD_TERM Получает термин пароль ("пароль" / "pin-code") для текущего носителя. Возвращаемое значение содержит строку текущей кодировке заканчивающуюся нулем.
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_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_EXCHANGE_KEY_FP Возвращает первые 8 байт открытого ключа обмена. Если в контейнере нет ключа обмена, функция возвращает FALSE.
PP_SIGNATURE_KEY_FP Возвращает первые 8 байт ключа проверки подписи. Если в контейнере нет ключа подписи, функция возвращает FALSE.
PP_CREATE_THREAD_CSP Инициализирует структуру HCRYPTMODULE, предназначенную для работы в многопоточном режиме, в предварительно выделенной пользователем памяти, указатель на которую передан в pbData.
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.
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). Имя контейнера возвращается в текущей кодировке. Возвращаемая строка заканчивается нулем.
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 упомянутого объекта.

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).
Коды возвратаОписание
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 .

Примечания

При указании параметра 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.

Требования:

Ядро FreeBSD: 7/8/9 или выше
Ядро Linux: ядро 2.4.x/2.6.x/3.0.х/3.2.х или выше
Ядро Solaris: 10/11 или выше.
Ядро Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше.

См. также

CPCAcquireContext() ,CPCSetProvParam() ,CPGetProvParam в MS CSP World Wide Web link ,CryptGetProvParam в MS CryptoAPI 2.0 World Wide Web link