КриптоПро CSP  

CPCSetProvParam

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

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

Аргументы

hCSP
[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().
dwParam
[in] Аргумент, принимающий следующие значения:
Значение dwParam Содержимое буфера pbData
PP_KEYSET_SEC_DESCR Устанавливает дескриптор безопасности раздела реестра Windows, где хранятся ключи пользователя. Значение дескриптора передаётся в pbData.
PP_HASHOID Устанавливает идентификатор алгоритма функции хэширования.
PP_CIPHEROID Устанавливает идентификатор алгоритма шифрования. </tr
PP_SIGNATUREOID Устанавливает идентификатор алгоритма подписи в зависимости от типа провайдера.
PP_DHOID Устанавливает идентификатор алгоритма Диффи-Хеллмана в зависимости от типа провайдера.
PP_KEYEXCHANGE_PIN Задаёт пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Если пароль не задан этой функцией или задан этой функцией неверно, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPCAcquireContext()). Данный параметр осуществляет непосредственную проверку введенного пароля. Если 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, см. CPCAcquireContext()). Данный параметр осуществляет непосредственную проверку введенного пароля. Если 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_SET_PIN Устанавливает пароль на контейнер hProv в случае зашифрования его на другом контейнере или на нескольких контейнерах для схемы n из k. Этот пароль будет использован при последующем открытии контейнера hProv на чтение. Если контейнер hProv был создан при помощи функции CPCAcquireContext() с флагом CRYPT_NEWKEYSET, то пароль, устанавливаемый на него, также будет установлен на доступ к ключу этого контейнера. Если функция CPCSetProvParam() не вызывалась, то при доступе к ключу выдается UI (если не был установлен флаг CRYPT_SILENT, см. CPCAcquireContext()). При открытии контейнера в SILENT-режиме возвращается ошибка. При вызове с флагом CP_CRYPT_SAVE_PASSWORD пароль будет сохранен в системе.
PP_USE_HARDWARE_RNG

Инициирует добавление к ДСЧ контекста криптопровайдера hProv последовательности с физического ДСЧ. Для считывания последовательности используются callback-функции, заданные при инициализации провайдера в поле hardwareRNG структуры CPC_CONFIG (см. CPC_HARDWARE_RNG ). Таким образом, вызов CPCSetProvParam с данным аргументом необходимо делать на уровне прерываний, на котором эти callback-функции в состоянии корректно работать.

В исполнении KC2 без успешного обращения к этой функции невозможна генерация ключей.

PP_RANDOM Устанавливает в pbData ключевой блоб типа SIMPLEBLOB (см. CRYPT_SIMPLEBLOB ), содержащий последовательность случайных чисел, необходимую для установки программного ДСЧ уровня ядра ОС. См. описание параметра PP_RANDOM функции CPCGetProvParam().
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. В многопоточном окружении следует учитывать, что изменяет настройки всего СКЗИ (HCRYPTMODULE) и должна выполнятся, в общем случае, при том условии, что нет открытых контекстов ключей и/или ключей. В режиме ядра, при установке CPC_FAST_CODE_USER и нулевых указателях на функции захвата/освобождения FPU, они не изменяются. В pbData структура типа CPC_FAST_CODE .
PP_NK_SYNC Производит запись одной из частей контейнера разделенного по схеме K из N. В качестве pbData должен быть передан DWORD полученный функцией GetProvParam с параметром PP_HCRYPTPROV. Функция используется для создания контейнера разделенного на части без выдачи окон.
PP_DELETE_KEYSET Удаляет текущий контейнер с носителя. Функция используется для удаления контейнеров, требующих для очистки пароля, в SILENT режиме. Контейнер после успешного завершения данной операции больше не может быть использован ни в одной функции провайдера, исключая CPCReleaseContext (CryptReleaseContext).
PP_SET_AUTH Устанавливает пароль в заданной аутентификации в контексте. Принимает в pbData аутентификационную информацию в виде структуры CRYPT_CHANGE_AUTH , в которой лежат тип устанавливаемой аутентификации, предполагаемое действие (можно установить пароль, можно сбросить аутентификацию, можно вывести окно ввода пароля), и, в случае, если оно нужно, предъявляемое значение пароля (предъявляемая аутентификация описывается в структуре в полях с префиксом verfy_).
PP_CHANGE_AUTH Меняет пароль в заданной аутентификации в контексте. Принимает в pbData аутентификационную информацию в виде структуры CRYPT_CHANGE_AUTH , в которой лежат тип аутентификации, предполагаемое действие (можно сменить пароль на переданный в структуре, можно вывести окно смены пароля, можно сбросить количество ошибок аутентификации), и, в случае, если оно нужно, новое значение пароля (изменяемая аутентификация описывается в структуре в полях с префиксом changed_). Если для смены аутентификации требуется предварительное предъявление другой (или той же) аутентификации, то предъявляемая аутентификация описывается в структуре в полях с префиксом verfy_.
PP_WND_READER_INFO Служебный параметр. Устанавливает в контекст информацию об окне выбора считывателя.
PP_CONTAINER_EXTENSION Устанавливает extension для контейнера. Если extension уже был задан в контейнере, то функция заменяет этот extension в контейнере. В качестве pbData должен быть передан extension в формате CERT_EXTENSION.
PP_CONTAINER_EXTENSION_DEL Удаляет из контейнера extension, заданный строковым представлением OID.
PP_CONTAINER_DEFAULT Устанавливает текущий контейнер - контейнером по умолчанию на текущем носителе.
PP_HARDWARE_STORE_FLAGS Параметр, предназначенный для установки специфических флагов считывателя/носителя.
PP_WND_MESSAGE_AUTO Служебный параметр. Устанавливает в контекст информацию об окне сообщения (типа HDISPMESSAGECONTEXT).
PP_EXTERNAL_CONTAINER_LINK Параметр устанавливает в только что созданный контейнер открытые данные от контейнера, разделенного по схеме NK. В качестве данных принимается BLOB, содержащий массив байт, полученный с помощью этого же параметра из разделенного контейнера, и длину этого массива.
pbData
[in] Указатель на буфер, содержащий данные параметра. Этот буфер при обращении к функции должен содержать данные, которые соответствуют типу параметра, помещённому в dwParam. Формат данных зависит от типа параметра.
dwFlags
[in] Значения флагов. Используются следующие значения флагов:
Значение dwFlags Описание
SECURITY_INFORMATION Флаг устанавливается, если dwParam установлен в дескриптор безопасности раздела реестра PP_KEYSET_SEC_DESCR,содержащего ключевой контейнер. Указатель на дескриптор безопасности передаётся в аргументе pbData, его длина передаётся в аргументе pcbData. Используются следующие битовые флаги:
  • OWNER_SECURITY_INFORMATION - Указывает идентификатор владельца объекта.
  • GROUP_SECURITY_INFORMATION - Указывает идентификатор первичный группы объекта.
  • DACL_SECURITY_INFORMATION - Указывает идентификатор дискреционного ACL объекта.
  • SACL_SECURITY_INFORMATION - Указывает идентификатор системного ACL объекта.

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).
Коды возвратаОписание
ERROR_INVALID_PARAMETERОдин из параметров содержит некорректное значение. Чаще всего это некорректный указатель.
NTE_BAD_DATAДлина идентификатора главного ключа пользователя превышает максимально допустимую. Если функция вызывалась с PP_FAST_CODE_FUNCS, ошибка в заданном размере буфера для сохранения регистров.
NTE_BAD_FLAGSВеличина dwFlags имеет ненулевое значение.
NTE_BAD_TYPEdwParam определяет неизвестный параметр.
NTE_KEYSET_ENTRY_BADНарушение целостности ключей в ОЗУ.
NTE_FAILОшибка при считывании данных из системного реестра.
NTE_BAD_KEY_STATEОперация применяется к ключу, находящемуся в некорректном состоянии.
ERROR_NOT_SUPPORTEDДанная операция не поддерживается.
SCARD_W_CANCELLED_BY_USERПользователь прервал операцию нажатием клавиши Cancel
SCARD_W_WRONG_CHVПользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam, неправильный
SCARD_E_INVALID_CHVПользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы.
SCARD_W_CHV_BLOCKEDВвод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток разрешенное картой для ввода.
SCARD_E_UNSUPPORTED_FEATUREНоситель не поддерживает данную функциональность.
NTE_TOKEN_KEYSET_STORAGE_FULLНедостаточно места на носителе для сохранения информации.
NTE_SILENT_CONTEXTОперация не может быть выполнена без пользовательского интерфейса.
NTE_NOT_SUPPORTEDОперация не поддерживается.
SCARD_W_REMOVED_CARDНоситель контейнера был удален из считывателя
SCARD_E_NO_KEY_CONTAINERПопытка выполнения операции в контексте смарт-карты или токена, а не контейнера.
SCARD_W_SECURITY_VIOLATIONФукции безопасности токена или смарт-карты работают некорректно.
ERROR_PASSWORD_EXPIREDПароль данного носителя истек, необходимо его сменить.
SCARD_E_READ_ONLY_CARDСмарт-карта недоступна для использования из-за ограничений безопасности.
SCARD_W_CARD_NOT_AUTHENTICATEDДля выполнения операции нужно указать ПИН-код.

Примечания

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

Устанавливаемые с помощью PP_DHOID/PP_SIGNATUREOID идентификаторы параметров закрытых ключей определяют данные параметры только для долговременных ключей и эфемерных ключей, тип которых соответствует типу провайдера. Для эфемерных ключей, тип которых не соответствует типу провайдера, идентификаторы параметров необходимо указывать явно с помощью функции CPCSetKeyParam().

См. также

CPCAcquireContext() ,CPCGetProvParam() ,CPSetProvParam в MS CSP World Wide Web link ,CryptSetProvParam в MS CryptoAPI 2.0 World Wide Web link