Крипто-Про 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_PRO_EXPORT Ключ экспорта/импорта ключей типа CALG_G28147 для хранения на диске или передачи по каналу связи.
CALG_SIMPLE_EXPORT Ключ экспорта/импорта ключей типа CALG_G28147 по ГОСТ 28147-89 в режиме простой замены для хранения на ключевом носителе.

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

Недопустимо использование CALG_SIMPLE_EXPORT для экспорта/импорта ключей с целью хранения их диске.
CALG_TLS1_MASTER Ключ для реализации протокола TLS.
CALG_TLS1_MAC_KEY Ключ для реализации протокола TLS.
CALG_TLS1_ENC_KEY Ключ для реализации протокола TLS.
KP_IV Начальный вектор (IV). Последовательность байтов, содержащая IV, передаётся функции через буфер pbData .
KP_CERTIFICATE Установка сертификата в контейнер (на носитель).
KP_PADDING Способ дополнения. Величина DWORD, содержащая метод дополнения, используемый шифром ключа, передаётся функции через буфер pbData. В настоящее время определены следующие способы дополнения:
  • PKCS5_PADDING - PKCS#5.(См ПРИМЕЧАНИЕ в данном разделе и ПРИМЕЧАНИЕ к CryptSetKeyParam в MS CryptoAPI 2.0 World Wide Web link )
  • ZERO_PADDING - дополнение нулевыми байтами,
  • RANDOM_PADDING - дополнение случайными байтами.
KP_MODE Режим шифра. Переменная типа DWORD. Передаётся функции через буфер pbData. В следующем списке приведены режимы шифрования, доступные в настоящее время:
  • CRYPT_MODE_ECB - блочный шифр простой замены ГОСТ 28147-89;
  • CRYPT_MODE_CNT - шифрование гаммированием ГОСТ 28147-89;
  • CRYPT_MODE_CFB - шифрование гаммированием с обратной связью ГОСТ 28147-89;
  • CRYPT_MODE_CBC - блочный шифр с обратной связью на базе ГОСТ 28147-89.
KP_MODE_BITS Глубина обратной связи. Переменная типа DWORD. Значение этой величины равно 64, что соответствует режиму гаммирования с обратной связью ГОСТ 28147-89.
KP_MIXMODE Дополнительный параметр ключа. Устанавливает режим преобразования ключа после зашифрования каждых 1024 байт информации. Режим преобразования ключа установлен по умолчанию. Выйти из этого режима можно, если для этого параметра pbData будет установлена в FALSE. Если pbData установлена в TRUE, устанавливается режим преобразования ключа. Размер pbData - 4 байта. Может быть установлен для ключей типа CALG_G28147. Возвращается в виде переменной типа DWORD.
KP_CIPHEROID Идентификатор узла замены. Строка, заканчивающаяся нулем.
KP_DHOID Идентификатор параметров ключа ГОСТ Р 34.10-94 и ГОСТ Р 34.10-2001 применяемых в алгоритме Диффи-Хеллмана. Строка, заканчивающаяся нулем.
KP_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 байта в форме little endian. Данные передаются в форме BLOB структуры, где член структуры pbData указавает на данные, а cbData передаёт длину данных.
pbData
[in] Указатель на буфер данных параметра. При вызове функции буфер содержит, соответствующие значению параметра в dwParam. Формат данных зависит от типа параметра.
dwFlags
[in] Значения флагов. Параметр зарезервирован для будущего использования и должен быть нулевым.

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError.
Коды возврата Описание
NTE_BAD_FLAGS Параметр dwFlags имеет ненулевое значение.
NTE_BAD_TYPE Параметр dwParam передаёт неизвестное значение параметра.
NTE_PERM Попытка чтения ключевых параметров, когда право чтения криптопровайдером не предоставлено.
NTE_FIXEDPARAMETER Была произведена попытка установить параметры, постоянные для данного криптопровайдера.

Примечания

ДОПОЛНЕНИЕ 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,а в переменной pdeDataLen значение длины шифрованного текста. Дополнение PKCS #5 не обеспечивает контроль целостности данных. ДОПОЛНЕНИЕ ZERO При использовании данной схемы, последовательность дополняется нулевыми байтами до наименьшей длины, кратной длине блока шифрования. ДОПОЛНЕНИЕ RANDOM При использовании данной схемы, последовательность дополняется случайными байтами до наименьшей длины, кратной длине блока шифрования.

РЕЖИМ CRYPT_MODE_ECB В соответствии с требованиями ГОСТ 28147-89 режим шифрования простой заменой CRYPT_MODE_ECB может использоваться только для шифрования ключевой информации.

Требования:

Windows 2000/XP/2003: Необходимо Windows 2000 SP4 или старше с Internet Explorer 6.0 или старше.
Windows NT/95/98/ME: CSP 3.0 не поддерживает (см. КриптоПро CSP 2.0 World Wide Web link ).
Solaris: 9 Update 4 или выше.
FreeBSD: FreeBSD 5.2 или выше
Linux: RedHat 7.3, RedHad 9.0.
Файл описания: Прототип описан в файле wincsp.h.
Ядро Windows NT: IRQL < DISPATCH_LEVEL

См. также:

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

Крипто-Про CSP Версия: 3.0 Сборка 3293
Что Вы думаете по поводу данной статьи?
Закажите CD c Крипто-Про CSP