DWORD CPCAPI CPCSetProvParam( HCRYPTMODULE hCSP, HCRYPTPROV hProv, DWORD dwParam, BYTE * pbData, DWORD dwFlags );
Значение dwParam | Содержимое буфера pbData |
---|---|
PP_KEYSET_SEC_DESCR | Устанавливает дескриптор безопасности раздела реестра Windows, где хранятся ключи пользователя. Значение дескриптора передаётся в pbData. |
PP_HASHOID | Устанавливает идентификатор алгоритма функции хэширования. |
PP_CIPHEROID | Устанавливает идентификатор алгоритма шифрования. |
PP_SIGNATUREOID | Устанавливает идентификатор алгоритма подписи. |
PP_DHOID | Устанавливает идентификатор алгоритма Диффи-Хеллмана. |
PP_ADMIN_PIN | Задаёт пароль администратора (PUK) для сброса и установки аутентификационной информации пользователя. Параметр доступен в некоторых криптопровайдерах, там, где возможен ввод PUK. В качестве данных передается ASCIIZ-строка. PUK запрашивается носителем только в случае, когда доступ к нему невозможен по PIN-коду. Таким случаем является состояние только что выпущенного носителя, на котором PIN-код еще не был задан пользователем, а ключевые контейнеры не существуют. После корректного предъявления PUK носитель переходит в режим доступа с правами администратора, в котором могут быть недоступны операции пользовательского режима. Дополнительно носитель может по вводу корректного PUK автоматически сбрасывать всю аутентификационную информацию (значение счетчика неуспешных попыток ввода PIN и значение PIN-кода), и удалять всю пользовательскую информацию (контейнеры ключей). Исходя из этого, рекомендуется использовать данный параметр только в том случае, когда заведемо известно об отсутствии пользовательской информации на носителе, или потеря ее представляется целесообразной. Ниже приводится пример кода, устанавливающего PIN на неинициализированном носителе перед созданием на нем контейнера: CPCAcquireContext(hCSP, &hProv, "NewContainer", CRYPT_NEWKEYSET, pvTable); CPCSetProvParam(hCSP, hProv, PP_ADMIN_PIN, "1234567890", 0); CPCSetProvParam(hCSP, hProv, PP_KEYEXCHANGE_PIN, "12345678", 0); CPCGenKey(hCSP, hProv, AT_KEYEXCHANGE, 0, &hKey); CPCDestroyKey(hCSP, hProv, hKey); CPCReleaseContext(hCSP, hProv, 0); Если PUK на неинициализированном номтеле не задан этой функцией, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPAcquireContext()). В рассмотренном примере это произойдет во время вызова CPGenKey. То же верно и для PIN-кода носителя, т.е. при создании контейнера на неинициализированном носителе в рассмотренном примере могут отсутствовать как первый, так второй вызов CPSetProvParam, или оба вызова сразу. Криптопровайдер выведет в таких случаях либо окно ввода PUK, либо окно установки PIN, либо окно ввода PUK и установки нового PIN соответственно. |
PP_KEYEXCHANGE_PIN | Задаёт пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Если пароль не задан этой функцией или задан этой функцией неверно, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPCAcquireContext()). Если pbData - NULL, то существующий пароль для этого контейнера забывается и для доступа к ключу потребуется повторный ввод пароля. В "КриптоПро CSP 3.9" используется единый пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Параметры PP_KEYEXCHANGE_PIN и PP_SIGNATURE_PIN эквивалентны. |
PP_SIGNATURE_PIN | Задаёт пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Если пароль не задан этой функцией или задан этой функцией неверно, то он запрашивается у пользователя посредством UI перед первым обращением к носителю (если не был установлен флаг CRYPT_SILENT, см. CPCAcquireContext()). Если pbData - NULL, то запомненный ранее пароль для этого контейнера забывается и для доступа к ключу потребуется повторный ввод пароля. В "КриптоПро CSP 3.9" используется единый пароль (PIN) для доступа к ключам AT_SIGNATURE и AT_KEYEXCHANGE. Параметры PP_KEYEXCHANGE_PIN и PP_SIGNATURE_PIN эквивалентны. |
PP_CHANGE_PIN | Задаёт новый пароль для контейнера hProv. |
PP_SET_PIN | Устанавливает пароль на контейнер hProv в случае зашифрования его на другом контейнере или на нескольких контейнерах для схемы n из k. Этот пароль будет использован при последующем открытии контейнера hProv на чтение. Если контейнер hProv был создан при помощи функции CPCAcquireContext() с флагом CRYPT_NEWKEYSET, то пароль, устанавливаемый на него, также будет установлен на доступ к ключу этого контейнера. Если функция CPCSetProvParam() не вызывалась, то при доступе к ключу выдается UI (если не был установлен флаг CRYPT_SILENT, см. CPCAcquireContext()). При открытии контейнера в SILENT-режиме возвращается ошибка. |
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_CONTAINER_EXTENSION | Устанавливает extension для контейнера. Если extension уже был задан в контейнере, то функция заменяет этот extension в контейнере. В качестве pbData должен быть передан extension в формате CERT_EXTENSION. |
PP_CONTAINER_EXTENSION_DEL | Удаляет из контейнера extension, заданный строковым представлением OID. |
PP_CONTAINER_DEFAULT | Устанавливает текущий контейнер - контейнером по умолчанию на текущем носителе. |
Значение 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 | Носитель контейнера был удален из считывателя |
Ядро FreeBSD: 7/8/9 или выше
Ядро Linux: ядро 2.4.x/2.6.x/3.0.х/3.2.х или выше
Ядро Solaris: 10/11 или выше.
Ядро Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше.
CPCAcquireContext() ,CPCGetProvParam() ,CPSetProvParam в MS CSP ,CryptSetProvParam в MS CryptoAPI 2.0