КриптоПро CSP  

CPSetKeyParam

Функция CPSetKeyParam() устанавливает параметры ключа.

BOOL WINAPI CPSetKeyParam(
  HCRYPTPROV hProv,
  HCRYPTKEY hKey,
  DWORD dwParam,
  BYTE * pbData,
  DWORD dwFlags
);

Аргументы

hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().
hKey
[in] Дескриптор ключа, параметры которого устанавливаются.
dwParam
[in] Параметр, принимающий следующие возможные значения:
Значение dwParam Содержимое буфера pbData
KP_ALGID Идентификатор алгоритма ключа (ALG_ID), соответствующий данному ключу. Передаётся функции через буфер pbData. Возможо установить значение CALG_G28147 для ключей класса ALG_CLASS_DATA_ENCRYPT (сессионных ключей).
ALG_ID Описание
CALG_G28147 Ключ шифрования и/или имитозащиты данных по ГОСТ 28147-89. В последствии этот ключ можно пометить как ключ для импорта/экспорта с помощью функции CPSetKeyParam().
CALG_SYMMETRIC_512 Ключ парной связи по Диффи-Хеллману с длиной выхода 512 бит.
CALG_PRO_EXPORT Ключ экспорта/импорта ключей типа CALG_G28147 для хранения на диске или передачи по каналу связи.
CALG_PRO12_EXPORT Ключ защищённого экспорта по рекомендациям ТК26 (обязателен для использования с ключами ГОСТ Р 34.10-2012).
CALG_SIMPLE_EXPORT Ключ экспорта/импорта ключей типа CALG_G28147 по ГОСТ 28147-89 в режиме простой замены для хранения на ключевом носителе.

Использование CALG_SIMPLE_EXPORT для ключей CALG_G28147, переданных в канале связи, возможно только в случае обеспечения строгой однократности операции импорта ключа принимающей стороной и гарантированной случайности получения ключа передающей стороной.

Использование CALG_SIMPLE_EXPORT при экспорте/импорте ключей CALG_TLS1_MASTER происходит с усложнением ключа аналогичным CALG_PRO_EXPORT.

Недопустимо использование CALG_SIMPLE_EXPORT для экспорта/импорта ключей с целью их хранения на диске.
CALG_TLS1_MASTER Ключ для реализации протокола TLS.
CALG_TLS1_MAC_KEY Ключ для реализации протокола TLS.
CALG_TLS1_ENC_KEY Ключ для реализации протокола TLS.
Устанавливает значения CALG_EKE_CIPHER на ключ CALG_PRO_AGREEDKEY_DH. Так же на ключ CALG_EKE_CIPHER может быть установлен тип CALG_PRO_AGREEDKEY_DH. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем.
KP_IV Устанавливает начальное значение вектора инициализации (IV или синхропосылки) алгоритма шифрования. Начальное значение синхропосылки по умолчанию (после создания, дублирования и или завершения операции шифрования) - случайное. Последовательность байтов, содержащая IV, передаётся функции через буфер pbData. Если ключ использовался в вызове CPEncrypt() или CPDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE.
KP_IV_BLOB Устанавливает начальное значение вектора инициализации (IV или синхропосылки) для алгоритма VKO GOST R 34.10-2012-256. Начальное значение синхропосылки по умолчанию - случайное. Данные передаются в форме BLOB структуры, где член структуры pbData указывает на данные, а cbData передаёт длину данных.
KP_CERTIFICATE Установка сертификата в контейнер (на носитель). Сертификат должен соответствовать ключу в контейнере.
KP_PADDING Способ дополнения. Величина DWORD, содержащая метод дополнения, используемый шифром ключа, передаётся функции через буфер pbData. В настоящее время определены следующие способы дополнения:
  • PKCS5_PADDING - PKCS#5.(См ПРИМЕЧАНИЕ в данном разделе и ПРИМЕЧАНИЕ к CryptSetKeyParam в MS CryptoAPI 2.0 World Wide Web link )
  • ZERO_PADDING - дополнение нулевыми байтами,
  • RANDOM_PADDING - дополнение случайными байтами,
  • ISO10126_PADDING - дополнение в соответствии с ISO 10126,
  • ANSI_X923_PADDING - дополнение в соответствии с ANSI X.923.
При первоначальной выработке ключа по умолчанию устанавливается значение PKCS5_PADDING.
KP_MODE

Режим шифра. Переменная типа DWORD. Передаётся функции через буфер pbData. Если ключ использовался в вызове CPEncrypt() или CPDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE. В следующем списке приведены режимы шифрования для ключей CALG_G28147 класса ALG_CLASS_DATA_ENCRYPT, доступные в настоящее время:

  • CRYPT_MODE_ECB - блочный шифр простой замены ГОСТ 28147-89;
  • CRYPT_MODE_CNT - шифрование гаммированием ГОСТ 28147-89;
  • CRYPT_MODE_CFB - шифрование гаммированием с обратной связью ГОСТ 28147-89;
  • CRYPT_MODE_CBCRFC4357 - блочный шифр с обратной связью на базе ГОСТ 28147-89, согласно RFC 4357;
  • CRYPT_MODE_CBCSTRICT - блочный шифр с обратной связью на базе ГОСТ 28147-89, шифртекст блока всегда является IV для следующего. Рекомендуется для использования только для обеспечения совместимости с существующими продуктами.
При первоначальной выработке ключа по умолчанию устанавливается значение CRYPT_MODE_CFB.

Для ключей CALG_EKE_CIPHER доступны режимы шифрования:

  • CRYPT_MODE_EKEXOR - одноразовый шифр гаммирования по модулю 2, в данном режиме вычисляется значение открытого ключа, соответсвующего ключу CALG_PRO_AGREEDKEY_DH и координата X ключа накладывается по модулю 2 на данные, данные длиной 32 байта должны подаваться одним блоком;
  • CRYPT_MODE_EKEECADD - одноразовый шифр гаммирования в группе точек эллиптической кривой, в данном режиме вычисляется значение открытого ключа, соответсвующего ключу CALG_PRO_AGREEDKEY_DH и ключ накладывается на данные аддитивно в группе точек эллиптической кривой, данные должны быть блобом открытого ключа длиной 100 байт и подаваться одним блоком.

KP_MODE_BITS Глубина обратной связи. Переменная типа DWORD. Значение этой величины равно 64, что соответствует режиму гаммирования с обратной связью ГОСТ 28147-89.
KP_MIXMODE Дополнительный параметр ключа. Устанавливает режим преобразования ключа после зашифрования каждых 1024 байт информации. Режим преобразования ключа (CRYPT_PROMIX_MODE) установлен по умолчанию. Выйти из этого режима можно, если для этого параметра в pbData будет установлено CRYPT_SIMPLEMIX_MODE. Если в pbData установлено CRYPT_PROMIX_MODE, устанавливается режим преобразования ключа. Размер pbData - 4 байта. Может быть установлен для ключей типа CALG_G28147. Если ключ использовался в вызове CPEncrypt() или CPDecrypt() с параметром Final = FALSE, то изменение данного параметра невозможно до вызова соответствующей функции с параметром Final = TRUE.
KP_MIXSTART Осуществляет диверсификацию ключа по алгоритму CALG_PRO_DIVERS. Через параметр pbData передаётся блоб диверсификации ключа в форме CRYPT_DATA_BLOB, см. CPCImportKey(). Допускается многократный вызов с различными параметрами диверсификации.
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, применяемых в алгоритме Диффи-Хеллмана. Строка, заканчивающаяся нулем. Начиная с версии 3.6 допускается устанавливать идентификаторы подписи. Необходимо устанавливать глобальным параметром PP_DHOID до генерации ключа.
KP_HASHOID Идентификатор функции хэширования. Строка, заканчивающаяся нулем. Необходимо устанавливать глобальным параметром PP_HASHOID до генерации ключа.
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_PREHASH

Идентификатор, используемый ключами типа CALG_TLS1_MASTER. Предварительно требуется установить KP_CLIENT_RANDOM и KP_SERVER_RANDOM. Вызов функции преобразует premaster_secret в master_secret.

KP_X Закрытый ключ в ключевой паре. 32 байта для ключей ГОСТ Р 34.10-2012 длины 256 бит (ГОСТ Р 34.10-2001) и 64 байта для ключей ГОСТ Р 34.10-2012 длины 512 бит в форме little endian. Данные передаются в форме BLOB структуры, где член структуры pbData указавает на данные, а cbData передаёт длину данных.
KP_MULX Для произвольной ключевой пары осуществляет умножение закрытого и открытого ключей на значение передаваемого параметра pbData. Для ключа CALG_PRO_AGREEDKEY_DH осуществляет умножение закрытого ключа на значение передаваемого параметра pbData. Данные передаются в форме BLOB структуры, где член структуры pbData указавает на данные - 32 байта для ключей ГОСТ Р 34.10-2012 длины 256 бит (ГОСТ Р 34.10-2001) и 64 байта для ключей ГОСТ Р 34.10-2012 длины 512 бит в форме little endian, а cbData передаёт длину данных.
KP_MULX_INVERS Аналогично KP_MULX осуществляет умножение на величину, обратную к величине, передаваемой в параметре pbData.
KP_ADDX Для закрытого ключа осуществляет сложение по модулю q значения ключа и значения смещения, передаваемого через параметр pbData. Данные передаются в форме BLOB структуры, где поле pbData указавает на данные - смещение, а cbData передаёт длину данных.
KP_SUBX Для открытого ключа осуществляет вычитание по модулю q из значения ключа значения смещения, передаваемого через параметр pbData. Данные передаются в форме BLOB структуры, где поле pbData указывает на данные - смещение, а cbData передаёт длину данных.
KP_ECADD Для открытого ключа осуществляет сложение в группе точек эллиптической кривойо ткрытого ключа и значения блоба открытого ключа, передаваемого через параметр pbData. Данные передаются в форме BLOB структуры, где поле pbData указавает на данные - блоб открытого ключа, а cbData передаёт длину данных.
KP_ECSUB Для открытого ключа осуществляет вычитание в группе точек эллиптической кривой открытого из ключа значение блоба открытого ключа, передаваемого через параметр pbData. Данные передаются в форме BLOB структуры, где поле pbData указавает на данные - блоб открытого ключа, а cbData передаёт длину данных.
KP_DEMASKPUBLIC Устанавливает открытый ключ на ключ CALG_PRO_AGREEDKEY_DH, что обеспечивает расшифрование ключа в алгоритме выработки ключа обмена с использованием функционального ключевого носителя. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем.
KP_SYNCRO Устанавливает значение синхропосылки на ключ пользователя. Ключ должен быть создан в контексте с флагом CRYPT_TOKEN_SHARED. Данные передаются в форме BLOB структуры, где pbData указавает на данные – 32 бита синхропосылки, а cbData передаёт длину данных. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем.
KP_UEC_DERIVE_COUNTER Для ключа типа AT_UECSYMMETRICKEY устанавливает значение счетчика ключей, полученных диверсификацией данного. Переменная типа DWORD.
pbData
[in] Указатель на буфер данных параметра. При вызове функции буфер содержит, соответствующие значению параметра в dwParam. Формат данных зависит от типа параметра.
dwFlags
[in] Значения флагов. Параметр зарезервирован для будущего использования и должен быть нулевым.

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

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

Примечания

ДОПОЛНЕНИЕ 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(), указаны в соответствующих разделах.

Требования:

AIX: 5/6/7 или выше.
FreeBSD: 7/8/9 или выше.
Linux: LSB 3.1 (RHEL 4, SuSE 10) или выше.
Solaris: 10 или выше.
Mac OSX: 10.7/8 или выше.
iOS: 6/7 или выше.
Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше с Internet Explorer 6.0 или старше.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCSetKeyParam .

См. также

CPGenKey() ,CPGetKeyParam() ,CPSetKeyParam в MS CSP World Wide Web link ,CryptSetKeyParam в MS CryptoAPI 2.0 World Wide Web link