BOOL WINAPI CPSetKeyParam( HCRYPTPROV hProv, HCRYPTKEY hKey, DWORD dwParam, BYTE * pbData, DWORD dwFlags );
Значение dwParam | Содержимое буфера pbData | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
KP_ALGID | Идентификатор алгоритма ключа (ALG_ID), соответствующий данному ключу. Передаётся функции через буфер pbData. Возможо установить значение CALG_G28147 для ключей класса ALG_CLASS_DATA_ENCRYPT (сессионных ключей).
| ||||||||||||||||||||||||||
KP_IV | Устанавливает начальное значение вектора инициализации (IV или синхропосылки) алгоритма шифрования. Начальное значение синхропосылки по умолчанию (после создания, дублирования и или завершения операции шифрования) - случайное. Последовательность байтов, содержащая IV, передаётся функции через буфер pbData. Если ключ использовался в вызове CPEncrypt() или CPDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE. | ||||||||||||||||||||||||||
KP_IV_BLOB | Устанавливает начальное значение вектора инициализации (IV или синхропосылки) для алгоритма VKO GOST R 34.10-2012-256 и шифрования по ГОСТ Р 34.12-2015. Начальное значение синхропосылки по умолчанию - случайное. Данные передаются в форме BLOB структуры, где член структуры pbData указывает на данные, а cbData передаёт длину данных. | ||||||||||||||||||||||||||
KP_CERTIFICATE | Установка сертификата в контейнер (на носитель). Сертификат должен соответствовать ключу в контейнере. | ||||||||||||||||||||||||||
KP_PADDING | Способ дополнения. Величина DWORD, содержащая метод дополнения, используемый шифром ключа, передаётся функции через буфер pbData. В настоящее время определены следующие способы дополнения:
| ||||||||||||||||||||||||||
KP_MODE | Режим шифра. Переменная типа DWORD. Передаётся функции через буфер pbData. Если ключ использовался в вызове CPEncrypt() или CPDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE. В следующем списке приведены режимы шифрования для ключей CALG_G28147 класса ALG_CLASS_DATA_ENCRYPT, доступные в настоящее время:
Для ключей CALG_GR3412_2015_M, CALG_GR3412_2015_K доступны следующие режимы шифрования, определенные в ГОСТ Р 34.13-2015:
| ||||||||||||||||||||||||||
KP_MODE_BITS | Глубина обратной связи. Возвращается в виде переменной типа DWORD. Для CALG_G28147 значение этой величины равно 64, что соответствует режиму гаммирования с обратной связью ГОСТ 28147-89. Для ключей CALG_GR3412_2015_M и CALG_GR3412_2015_K определяет длину блока гаммы и по умолчанию равно 64 и 128 бит соответственно. | ||||||||||||||||||||||||||
KP_MIXMODE | Дополнительный параметр ключа. Может быть установлен для ключей типа CALG_G28147, CALG_GR3412_2015_M, CALG_GR3412_2015_K и определяет режим преобразования ключа после зашифрования каждых X байт информации. Величина X определяется типом ключа: для CALG_G28147 она равна 1024 байт, для CALG_GR3412_2015_M и CALG_GR3412_2015_K вычисляется как 128 и 256, соответственно умноженное на длину блока гаммы в байтах. Режим преобразования ключа (CRYPT_PROMIX_MODE) для CALG_G28147 установлен по умолчанию, для CALG_GR3412_2015_M и CALG_GR3412_2015_K данный режим (CRYPT_ACPKM_MODE) доступен только при работе в режиме CRYPT_MODE_CTR. Выйти из режима CRYPT_PROMIX_MODE/CRYPT_ACPKM_MODE можно, если для этого параметра в pbData будет установлено CRYPT_SIMPLEMIX_MODE. Если в pbData установлено CRYPT_PROMIX_MODE/CRYPT_ACPKM_MODE, устанавливается режим преобразования ключа. Размер pbData - 4 байта. Если ключ использовался в вызове CPCEncrypt() или CPCDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE. | ||||||||||||||||||||||||||
KP_MIXSTART | Осуществляет диверсификацию ключа ГОСТ 28147-89 по алгоритму CALG_PRO_DIVERS. Через параметр pbData передаётся блоб диверсификации ключа в форме CRYPT_DATA_BLOB, см. CPCImportKey(). Допускается многократный вызов с различными параметрами диверсификации. | ||||||||||||||||||||||||||
KP_MIX_BLOCK_SIZE | Количество зашифрований блока данных, после которого производится смена ключа при работе в режиме CRYPT_PROMIX_MODE для алгоритмов CALG_GR3412_2015_M и CALG_GR3412_2015_K. По умолчанию имеет значения 128 и 256 соответственно. Устанавливаемое значение должно иметь вид 2^k, где k - некоторое натуральное число. | ||||||||||||||||||||||||||
KP_AUTH_TAG | Проверка тэга аутентификации при расшифровании в AEAD-режиме. Может быть использовано при расшифровании потока данных после вызова CPDecrypt() с финализацией (флагом Final = TRUE). Передаётся в виде структуры CRYPT_DATA_BLOB. | ||||||||||||||||||||||||||
KP_AUTH_DATA | Обработка дополнительных нешифруемых данных при шифровании и расшифровании в AEAD-режиме. Не может быть использовано после начала процедуры шифрования/расшифрования. После установки данного параметра AEAD-шифрование можно проводить только в режиме потока данных. Передаётся в виде структуры CRYPT_DATA_BLOB. | ||||||||||||||||||||||||||
KP_CIPHEROID | Идентификатор узла замены. Строка, заканчивающаяся нулем. При первоначальной выработке ключа по умолчанию устанавливается в соответствии с параметрами, указанными в панели криптопровайдера. Для провайдера PROV_GOST_2001_DH в панели по умолчанию указан набор "ГОСТ 28147-89, параметры по умолчанию" (szOID_Gost28147_89_CryptoPro_A_ParamSet, 1.2.643.2.2.31.1), для PROV_GOST_2012_256 и PROV_GOST_2012_512 - набор "ГОСТ 28147-89, параметры шифрования ТК 26 Z" (szOID_Gost28147_89_TC26_Z_ParamSet, 1.2.643.7.1.2.5.1.1). | ||||||||||||||||||||||||||
KP_DHOID | Идентификатор параметров ключа ГОСТ Р 34.10-2001/ГОСТ Р 34.10-2012, применяемых в алгоритме Диффи-Хеллмана. Строка, заканчивающаяся нулем. Может быть использован только для "пустой" ключевой пары, созданной с флагом CRYPT_PREGEN. | ||||||||||||||||||||||||||
KP_SIGNATUREOID | Идентификатор параметров ключа ГОСТ Р 34.10-2001/ГОСТ Р 34.10-2012, применяемых в алгоритме подписи. Строка, заканчивающаяся нулем. Может быть использован только для "пустой" ключевой пары, созданной с флагом CRYPT_PREGEN. | ||||||||||||||||||||||||||
KP_HASHOID | Идентификатор функции хэширования. Строка, заканчивающаяся нулем. Необходимо устанавливать глобальным параметром PP_HASHOID до генерации ключа. Для "пустой" эфемерной ключевой пары может быть также установлено значение NULL. Для ключей, для которых уже было установлено значение параметров ключа id-tc26-gost-3410-12-256-paramSetA, id-tc26-gost-3410-12-256-paramSetB, id-tc26-gost-3410-12-256-paramSetC, id-tc26-gost-3410-12-256-paramSetD с помощью вызова CPCSetKeyParam(KP_DHOID), вызов с нулевым параметром pbData явно устанавливает запрет на запись поля digestParamSet в структуру PublicKeyInfo. | ||||||||||||||||||||||||||
KP_CLIENT_RANDOM | Идентификатор величины ClientRandom, используемой с ключами типа CALG_TLS1_MASTER. Размер ClientRandom - 32 байта. Используется при преобразовании premaster_secret в master_secret и при генерации ключевой информации в момент создания хэша CALG_TLS1_MASTER_HASH. | ||||||||||||||||||||||||||
KP_SERVER_RANDOM | Идентификатор величины ServerRandom, используемой с ключами типа CALG_TLS1_MASTER.Размер ServerRandom - 32 байта. Используется при преобразовании premaster_secret в master_secret и при генерации ключевой информации в момент создания хэша CALG_TLS1_MASTER_HASH. | ||||||||||||||||||||||||||
KP_SESSION_HASH | Идентификатор величины session_hash, используемой с ключами типа CALG_TLS1_MASTER. Передаётся в виде структуры CRYPT_DATA_BLOB. Используется при преобразовании premaster_secret в master_secret в рамках RFC 7627 (Extended Master Secret). | ||||||||||||||||||||||||||
KP_PREHASH | Идентификатор, используемый ключами типа CALG_TLS1_MASTER. Предварительно требуется установить KP_CLIENT_RANDOM и KP_SERVER_RANDOM. Вызов функции преобразует premaster_secret в master_secret. | ||||||||||||||||||||||||||
KP_X | Параметр, используемый для фактического выращивания ключа "пустой" ключевой пары. Параметр pbData должен строго содержать значение NULL. | ||||||||||||||||||||||||||
KP_DEMASKPUBLIC | Устанавливает открытый ключ на ключ CALG_PRO_AGREEDKEY_DH, что обеспечивает расшифрование ключа в алгоритме выработки ключа обмена с использованием функционального ключевого носителя. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем. | ||||||||||||||||||||||||||
KP_SYNCRO | Устанавливает значение синхропосылки на ключ пользователя. Ключ должен быть создан в контексте с флагом CRYPT_TOKEN_SHARED. Данные передаются в форме BLOB структуры, где pbData указавает на данные – 32 бита синхропосылки, а cbData передаёт длину данных. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем. | ||||||||||||||||||||||||||
KP_STORE | Сохраняет ключ в контейнер. В контейнер могут сохраняться ключи шифрования. Ключ может сохраняться только в пустой контейнер или перезаписывать значение ключа того же алгоритма в контейнере. Нельзя сохранять ключ в контейнер, где уже есть закрытые ключи. В контейнер с симметричным ключом нельзя добавить закрытый ключ. После сохранения симметричный ключ доступен с помощью функции CPGetUserKey, c dwKeySpec=AT_SYMMETRIC. | ||||||||||||||||||||||||||
KP_UEC_DERIVE_COUNTER | Для ключа типа AT_UECSYMMETRICKEY устанавливает значение счетчика ключей, полученных диверсификацией данного. Переменная типа DWORD. |
Коды возврата | Описание |
---|---|
ERROR_INVALID_PARAMETER | Один из параметров содержит некорректное значение. Чаще всего это некорректный указатель. |
NTE_BAD_FLAGS | Параметр dwFlags имеет ненулевое значение. |
NTE_BAD_TYPE | Параметр dwParam передаёт неизвестное значение параметра. |
NTE_BAD_KEY | Дескриптор ключа ошибочен. |
NTE_BAD_KEY_STATE | Указанный параметр временно не может быть изменен. |
NTE_PERM | Попытка чтения ключевых параметров, когда право чтения криптопровайдером не предоставлено. |
NTE_FIXEDPARAMETER | Была произведена попытка установить параметры, постоянные для данного криптопровайдера. |
NTE_BAD_DATA | Неправильные данные в буфере pbData. |
SCARD_E_NO_KEY_CONTAINER | Контекст открыт с флагом CRYPT_DEFAULT_CONTAINER_OPTIONAL, и не связан ни с одним контейнером, поэтому выполнение данной операции недоступно. |
ДОПОЛНЕНИЕ PKCS #5 Эта схема дополнения определена RSA Data Security, Inc. и описана в "Public-Key Cryptography Standards (PKCS)", PKCS #5, раздел 6.2. При использовании данной схемы последовательность всегда дополняется знаками, даже в случае, когда её длина кратна длине блока шифрования. Последовательность дополнения состоит из байтов, каждый из которых равен числу дополнительных байтов. Если дополняется последовательность из 24 бит, последовательность дополнения равна “05 05 05 05 05”. Если дополняется 64 бита, последовательность дополнения равна “08 08 08 08 08 08 08 08”. При расшифровании, если расширение блока удовлетворяет условиям дополнения PKCS #5, функция CPDecrypt() в переменной pdwDataLen, возвращает истинное значение длины открытого текста. Если расширение блока не удовлетворяет условиям дополнения PKCS #5, функция CPDecrypt() возвращает ошибку NTE_BAD_DATA, а в переменной pdwDataLen значение длины шифрованного текста.
ДОПОЛНЕНИЕ ZERO При использовании данной схемы, последовательность дополняется нулевыми байтами до наименьшей длины, кратной длине блока шифрования.
ДОПОЛНЕНИЕ RANDOM При использовании данной схемы, последовательность дополняется случайными байтами до наименьшей длины, кратной длине блока шифрования.
ДОПОЛНЕНИЕ ISO 10126 Эта схема определена стандартом ISO 10126. При использовании данной схемы последовательность всегда дополняется знаками, даже если её длина кратна длине блока шифрования. Последовательность дополнения кроме последнего байта состоит из случайных байтов, в последнем байте указывается общая длина дополнения в байтах. Если дополняется последовательность длиной 24 бита, то последовательность дополнения может быть следующей: "6F 43 3D B2 05", где первые 4 байта выбраны случайно. Если дополняются 64 бита, последовательность дополнения может быть следующей: "B6 87 2D 4A 40 A1 F9 08", где первые семь байт выбраны случайно. При расшифровании, если расширение блока удовлетворяет условиям дополнения ISO 10126, функция CPCDecrypt() в переменной pdwDataLen, возвращает истинное значение длины открытого текста. Если расширение блока не удовлетворяет условиям дополнения ISO 10126, функция CPCDecrypt() возвращает ошибку NTE_BAD_DATA, а в переменной pdwDataLen значение длины шифрованного текста.
ДОПОЛНЕНИЕ ANSI X.923 Эта схема определена стандартом ANSI X.923. При использовании данной схемы последовательность всегда дополняется знаками, даже если её длина кратна длине блока шифрования. Последовательность дополнения кроме последнего байта состоит из нулевых байтов, в последнем байте указывается общая длина дополнения в байтах. Если дополняется последовательность длиной 24 бита, то последовательность дополнения является следующей: "00 00 00 00 05". Если дополняются 64 бита, последовательность дополнения является следующей: "00 00 00 00 00 00 00 08". При расшифровании, если расширение блока удовлетворяет условиям дополнения ANSI X.923, функция CPCDecrypt() в переменной pdwDataLen, возвращает истинное значение длины открытого текста. Если расширение блока не удовлетворяет условиям дополнения ANSI X.923, функция CPCDecrypt() возвращает ошибку NTE_BAD_DATA, а в переменной pdwDataLen значение длины шифрованного текста.
РЕЖИМ CRYPT_MODE_ECB В соответствии с требованиями ГОСТ 28147-89 режим шифрования простой заменой CRYPT_MODE_ECB может использоваться только для шифрования ключевой информации.
Значение параметра KP_CIPHEROID, установленное на долговременный ключ, сохраняется только в текущем контексте. После вызова функции CPReleaseContext() при повторном открытии контейнера и обращении к ключу данный параметр примет установленное в контейнере значение.
Значения параметров KP_MODE, KP_MIXMODE, KP_CIPHEROID и KP_PADDING, устанавливаемые по умолчанию во вновь создаваемый симметричный ключ операциями CPImportKey(), CPDuplicateKey() и CPDeriveKey(), указаны в соответствующих разделах.
После начала процедуры шифрования/расшифрования CPEncrpyt()/CPDecrypt() (с флагом Final = FALSE) или установки параметра KP_AUTH_DATA смена параметров ключа невозможна до вызова CPEncrpyt()/CPDecrypt() с финализацией (флагом Final = TRUE) или CPGetKeyParam() с параметром KP_AUTH_TAG.
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.
Ядро ОС: Вместо неё используется аналогичная функция CPCSetKeyParam .
CPGenKey() ,CPGetKeyParam() ,CPSetKeyParam в MS CSP ,CryptSetKeyParam в MS CryptoAPI 2.0