BOOL WINAPI CPSetProvParam( HCRYPTPROV hProv, DWORD dwParam, BYTE * pbData, DWORD dwFlags );
Значение dwParam | Содержимое буфера pbData |
---|---|
PP_CACHE_SIZE | Устанавливает настройки кэширования контейнеров. В pbData структура типа CRYPT_CACHE_SIZE . |
PP_ENCRYPTION_CARRIER | Установить носитель как ключ шифрования контейнеров. Параметр pbData не используется. |
PP_KEYSET_SEC_DESCR | Устанавливает дескриптор безопасности раздела реестра Windows, где хранятся ключи пользователя. Значение дескриптора передаётся в pbData. |
PP_HASHOID | Устанавливает идентификатор алгоритма функции хэширования ГОСТ Р 34.11-94. |
PP_CIPHEROID | Устанавливает идентификатор алгоритма шифрования ГОСТ 28147-89. |
PP_SIGNATUREOID | Устанавливает идентификатор алгоритма подписи в зависимости от типа провайдера. |
PP_DHOID | Устанавливает идентификатор алгоритма Диффи-Хеллмана в зависимости от типа провайдера. |
PP_KEYEXCHANGE_PIN | Задаёт пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Если пароль не задан этой функцией или задан этой функцией неверно, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPAcquireContext()). Если pbData - NULL, то существующий пароль для этого контейнера забывается и для доступа к ключу потребуется повторный ввод пароля. В "КриптоПро CSP 5.0" используется единый пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Параметры PP_KEYEXCHANGE_PIN и PP_SIGNATURE_PIN эквивалентны. При вызове с флагом CP_CRYPT_SAVE_PASSWORD пароль будет сохранен в системе. |
PP_SIGNATURE_PIN | Задаёт пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Если пароль не задан этой функцией или задан этой функцией неверно, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPAcquireContext()). Если pbData - NULL, то запомненный ранее пароль для этого контейнера забывается и для доступа к ключу потребуется повторный ввод пароля. В "КриптоПро CSP 5.0" используется единый пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Параметры PP_KEYEXCHANGE_PIN и PP_SIGNATURE_PIN эквивалентны. При вызове с флагом CP_CRYPT_SAVE_PASSWORD пароль будет сохранен в системе. |
PP_CHANGE_PIN | Задаёт новый пароль для контейнера hProv. |
PP_PASSWORD_CACHE | Устанавливает месторасположение аутентификационной информации разных типов. Не вносит изменений в месторасположение аутентификационной информации в уже открытом именованном контексте, а определяет только глобальные настройки. Криптопровайдер может изменить значение месторасположения аутентификационной информации для конкретного контекста в следующих случаях: 1. Для неотчуждаемых носителей аутентификационная информация контейнера и носителя не может хранится в глобальном кэше. Вместо глобального будет использован локальный кэш. 2. В контексте, созданном с флагом CRYPT_MACHINE_KEYSET, на отчуждаемых носителях кэширование будет выключено. 3. В контексте, созданном с флагом CRYPT_LOCAL_PASSWORD_CACHE, аутентификационная информация будет сохраняться в локальном кэше вместо глобального. 4. Основная аутентификация не может не кэшироваться. Месторасположение кодируется следующим образом: Установка значения по умолчанию для данного типа аутентификации, определенного в криптопровайдере, соответствует значению 0. Аутентификационная информация не сохраняется в памяти, а сразу передаваться носителю. Соответствует значению 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). По умолчанию месторасположение аутентификационной информации контейнера - локальный кэш. По умолчанию месторасположение аутентификационной информации носителя - глобальный кэш. По умолчанию аутентификационная информация администратора (PUK) не сохраняется в памяти. Значение расположения аутентификационной информации администратора нельзя установить в 3 (глобальный кэш). Значение расположения аутентификационной информации контейнера нельзя установить в 1 (не сохраняется в памяти). |
PP_SET_PIN | Устанавливает пароль на контейнер hProv в случае зашифрования его на другом контейнере или на нескольких контейнерах для схемы n из k. Этот пароль будет использован при последующем открытии контейнера hProv на чтение. Если контейнер hProv был создан при помощи функции CPAcquireContext() с флагом CRYPT_NEWKEYSET, то пароль, устанавливаемый на него, также будет установлен на доступ к ключу этого контейнера. Если функция CPSetProvParam() не вызывалась, то при доступе к ключу выдается UI (если не был установлен флаг CRYPT_SILENT, см. CPAcquireContext()). При открытии контейнера в SILENT-режиме возвращается ошибка. При вызове с флагом CP_CRYPT_SAVE_PASSWORD пароль будет сохранен в системе. |
PP_USE_HARDWARE_RNG | Инициирует добавление к ДСЧ контекста криптопровайдера hProv значения с физического или БиоДСЧ. В случае, если в данной системе поддерживается только БиоДСЧ, то выдаётся UI для ввода событий мыши и/или клавиатуры (если не был установлен флаг CRYPT_SILENT, см. CPAcquireContext()). При вызове функции CPSetProvParam() с параметром PP_USE_HARDWARE_RNG параметр pbData не используется. Обычно, при отсуствии в системе физического ДСЧ, данные с БиоДСЧ добавляются в обязательном порядке к контексту криптопровайдера (в контейнер ключевой информации) только при создании постоянных ключей AT_KEYEXCHANGE или AT_SIGNAUTURE функцией CPGenKey(). |
PP_RANDOM | Устанавливает в pbData ключевой блоб типа SIMPLEBLOB (см. CRYPT_SIMPLEBLOB ), содержащий последовательность случайных чисел, необходимую для установки программного ДСЧ уровня ядра ОС. См. описание параметра PP_RANDOM функции CPGetProvParam(). |
PP_CHECKPUBLIC | Получает из pbData значение флага проверки открытого ключа. Если значение pbData типа DWORD равно 1, при импорте открытого ключа проверяется его корректность, если 0, проверка производится, если флаг установлен по параметру PP_ADMIN_CHECKPUBLIC. Открытый ключ, соответствующий ГОСТ 34.10-2001, проверяется всегда. |
PP_ADMIN_CHECKPUBLIC | Получает из pbData значение флага проверки открытого ключа и устанавливает его в реестр. Если значение установленного в реестре флага равно 1, при импорте открытого ключа проверяется его корректность независимо от установки пользователя по параметру PP_CHECKPUBLIC, если значение установленного в реестре флага равно 0, проверка производится в зависимости от установки по параметру PP_CHECKPUBLIC. Открытый ключ, соответствующий ГОСТ 34.10-2001, проверяется всегда. |
PP_FAST_CODE_FUNCS | Параметр предназначен для управления подключением быстрых функций на на процессорах с архитектурой ia32/amd64. Применяется для установки функций захвата и освобождения регистров расширений MMX/SSE2/SSSE3/AVX. Определён только в KC1 без сервиса хранения ключей. Для управления в остальных режимах см. CPC_FAST_CODE . В многопоточном окружении следует учитывать, что изменяет настройки всего СКЗИ (HCRYPTMODULE) и должна выполнятся, в общем случае, при том условии, что нет открытых контекстов ключей и/или ключей. В режиме ядра, при установке CPC_FAST_CODE_USER и нулевых указателях на функции захвата/освобождения FPU, они не изменяются. В pbData структура типа CPC_FAST_CODE . |
PP_NK_SYNC | Производит запись одной из частей контейнера разделенного по схеме K из N. В качестве pbData должен быть передан DWORD полученный функцией GetProvParam с параметром PP_HCRYPTPROV. Функция используется для создания контейнера разделенного на части без выдачи окон. |
PP_CONTAINER_VERSION | Устанавливает версию заголовочного файла контейнера. В качестве pbData должен быть передан DWORD со значением версии. Допустимые значения в КриптоПро CSP 5.0: KEY_CARRIER_VERSION_V2, KEY_CARRIER_VERSION_V4. По умолчанию для контейнеров с извлекаемыми ключами отечественных алгоритмов устанавливается версия KEY_CARRIER_VERSION_V2. Для контейнеров с неизвлекаемыми ключами и для контейнеров с ключами иностранных алгоритмов устанавливается версия KEY_CARRIER_VERSION_V4. Старые контейнеры от криптопрвайдеров версии 2.0 и предыдущих имеют версию KEY_CARRIER_VERSION_V1. Новые версии криптопровайдера не работают с этой версией контейнера. Изменить версию заголовочного файла контейнера можно для контейнеров с извлекаемыми ключами отечественных алгоритмов, причем только на KEY_CARRIER_VERSION_V2 или KEY_CARRIER_VERSION_V4. |
PP_SET_AUTH | Устанавливает пароль в заданной аутентификации в контексте. Принимает в pbData аутентификационную информацию в виде структуры CRYPT_CHANGE_AUTH , в которой лежат тип устанавливаемой аутентификации, предполагаемое действие (можно установить пароль, можно сбросить аутентификацию, можно вывести окно ввода пароля), и, в случае, если оно нужно, предъявляемое значение пароля (предъявляемая аутентификация описывается в структуре в полях с префиксом verfy_). |
PP_CHANGE_AUTH | Меняет пароль в заданной аутентификации в контексте. Принимает в pbData аутентификационную информацию в виде структуры CRYPT_CHANGE_AUTH , в которой лежат тип аутентификации, предполагаемое действие (можно сменить пароль на переданный в структуре, можно вывести окно смены пароля, можно сбросить количество ошибок аутентификации), и, в случае, если оно нужно, новое значение пароля (изменяемая аутентификация описывается в структуре в полях с префиксом changed_). Если для смены аутентификации требуется предварительное предъявление другой (или той же) аутентификации, то предъявляемая аутентификация описывается в структуре в полях с префиксом verfy_. |
PP_DELETE_KEYSET | Удаляет текущий контейнер с носителя. Функция используется для удаления контейнеров, требующих для очистки пароля, в SILENT режиме. Контейнер после успешного завершения данной операции больше не может быть использован ни в одной функции провайдера, исключая CPReleaseContext (CryptReleaseContext). |
PP_EXTERNAL_CONTAINER_LINK | Параметр устанавливает в только что созданный контейнер открытые данные от контейнера, разделенного по схеме NK. В качестве данных принимается BLOB, содержащий массив байт, полученный с помощью этого же параметра из разделенного контейнера, и длину этого массива. |
PP_DELETE_SAVED_PASSWD | Удаляет сохраненные на диске пароли для текущего контейнера. Если контекст открыт с флагом CRYPT_VERIFYCONTEXT, то будут удалены сохраненные пароли на все контейнеры. |
PP_CONTAINER_EXTENSION | Устанавливает extension для контейнера. Если extension уже был задан в контейнере, то функция заменяет этот extension в контейнере. В качестве pbData должен быть передан extension в формате CERT_EXTENSION. |
PP_CONTAINER_EXTENSION_DEL | Удаляет из контейнера extension, заданный строковым представлением OID. |
PP_SAVE_PASSWORD_POLICY | Управление сохранением пароля в реестре. Если передана 0 типа DWORD, то в данном контейнере будет запрещено сохранение пароля в реестре (и, соответственно, считывание его из реестра). Если передано ненулевое значение, то функция завершится успехом, если разрешено сохранение пароля в реестре, и завершится неудачей с возвращением ошибки NTE_PERM, если запрещено сохранение пароля в реестре. |
PP_CONTAINER_DEFAULT | Устанавливает текущий контейнер - контейнером по умолчанию на текущем носителе. |
PP_DELETE_SHORTCUT | Удаляет сохраненные на диске shortcut для заданного параметром контейнера или для всех контейнеров. Если в качестве pbData передан NULL, то функция производит удаление всех сохраненных shortcut. Если в качестве pbData передано имя контейнера, то функция удаляет сохраненный shortcut для этого контейнера. Имя контейнера должно быть задано в текущей кодировке и заканчиваться нулем. В качестве имени нельзя передавать уникальное имя контейнера и имя в формате FQCN (Fully Qualified Container Name). |
PP_HARDWARE_STORE_FLAGS | Параметр, предназначенный для установки специфических флагов считывателя/носителя. |
Значение dwFlags | Описание |
---|---|
SECURITY_INFORMATION | Флаг устанавливается, если dwParam установлен в дескриптор безопасности раздела реестра PP_KEYSET_SEC_DESCR,содержащего ключевой контейнер. Указатель на дескриптор безопасности передаётся в аргументе pbData, его длина передаётся в аргументе pcbData. Используются следующие битовые флаги:
|
Коды возврата | Описание |
---|---|
ERROR_INVALID_PARAMETER | Один из параметров содержит некорректное значение. Чаще всего это некорректный указатель. |
NTE_BAD_DATA | Длина идентификатора главного ключа пользователя превышает максимально допустимую. Если функция вызывалась с PP_FAST_CODE_FUNCS, ошибка в заданном размере буфера для сохранения регистров. |
NTE_BAD_FLAGS | Величина dwFlags имеет ненулевое значение. |
NTE_BAD_TYPE | dwParam определяет неизвестный параметр. |
NTE_KEYSET_ENTRY_BAD | Нарушение целостности ключей в ОЗУ. |
NTE_FAIL | Ошибка при считывании данных из системного реестра. |
SCARD_W_CANCELLED_BY_USER | Пользователь прервал операцию нажатием клавиши Cancel |
SCARD_W_WRONG_CHV | Пользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam, неправильный |
SCARD_E_INVALID_CHV | Пользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы. |
SCARD_W_CHV_BLOCKED | Ввод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток разрешенное картой для ввода. |
NTE_TOKEN_KEYSET_STORAGE_FULL | Недостаточно места на носителе для сохранения информации. |
NTE_SILENT_CONTEXT | Операция не может быть выполнена без пользовательского интерфейса. |
SCARD_W_REMOVED_CARD | Носитель контейнера был удален из считывателя |
SCARD_E_NO_KEY_CONTAINER | Контекст открыт с флагом CRYPT_DEFAULT_CONTAINER_OPTIONAL, и не связан ни с одним контейнером, поэтому выполнение данной операции недоступно. |
При указании параметра PP_SIGNATUREOID или PP_DHOID выбирается параметр, соответствующий типу провайдера.
Устанавливаемые с помощью PP_DHOID/PP_SIGNATUREOID идентификаторы параметров закрытых ключей определяют данные параметры только для долговременных ключей и эфемерных ключей, тип которых соответствует типу провайдера. Для эфемерных ключей, тип которых не соответствует типу провайдера, идентификаторы параметров необходимо указывать явно с помощью функции CPSetKeyParam().
Пример установки PIN на контейнер. Необходимо установить на контейнер с именем "test" PIN "12345".
HCRYPTPROV hProv;
BYTE PIN[6] = {'1', '2', '3', '4', '5', 0}; // Необходимо указывать признак конца строки - 0.
//Открываем контейнер
CPAcquireContext(&hProv, "test", 0, pVTable);
//Устанавливаем PIN
CPSetProvParam(hProv, PP_SIGNATURE_PIN, PIN, 0);
//PIN установлен.
В случае, если непосредственно установить PIN в текущем контексте невозможно, необходимо повторно открыть контекст контейнера и установить PIN в новом контексте.
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.
Ядро ОС: Вместо неё используется аналогичная функция CPCSetProvParam .
CPAcquireContext() ,CPGetProvParam() ,CPSetProvParam в MS CSP ,CryptSetProvParam в MS CryptoAPI 2.0