Функция CPDeriveKey() производит криптографические ключи сессии на основе значения хэш-функции, вычисленной по другим ключам, паролям или любым другим данным пользователя.

BOOL WINAPI CPDeriveKey(
  HCRYPTPROV hProv,
  ALG_ID AlgId,
  HCRYPTHASH hBaseData,
  DWORD dwFlags,
  HCRYPTKEY * phKey
);

Аргументы

hProv

[in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().

AlgId

[in] Идентификатор алгоритма шифрования, для которого производится ключ.

Значение AlgId	Описание
CALG_G28147	Ключ шифрования и/или имитозащиты данных по ГОСТ 28147-89. Впоследствии этот ключ может быть преобразован с помощью функции CPSetKeyParam() в ключ, на котором возможен экспорт/импорт других ключей.
CALG_GR3412_2015_M	Ключ шифрования по ГОСТ Р 34.12-2015 и/или имитозащиты данных по ГОСТ Р 34.13-2015 Магма. Не может использоваться для экспорта/импорта.
CALG_GR3412_2015_K	Ключ шифрования по ГОСТ Р 34.12-2015 и/или имитозащиты данных по ГОСТ Р 34.13-2015 Кузнечик. Не может использоваться для экспорта/импорта.
CALG_TLS1_ENC_KEY	Ключ шифрования на основе объекта TLS1_MASTER_HASH.
CALG_TLS1_MAC_KEY	Ключ имитозащиты на основе объекта TLS1_MASTER_HASH.
CALG_UECSYMMETRIC CALG_UECSYMMETRIC_EPHEM CALG_G28147	Ключи различных типов на основе объекта CALG_UECMASTER_DIVERS. Если именованный ключевой контекст не содержит ключа AT_UECSYMMETRICKEY, ключ CALG_UECSYMMETRIC заносится в ключевой контейнер.

hBaseData

[in] Дескриптор объекта функции хэширования, используемый для обработки входных данных. Во время вызова функции объект хэша "закрывается".
Для ГОСТ Р 34.11-94 и ГОСТ Р 34.11-2012 (и HMAC-ов на их основе) проводится дополнение до размера блока (если требуется), исполняются шаговые функции для последнего блока (если требуется), для длины и для контрольной суммы.
Расчёт хэш-функции может быть продолжен с помощью:

• последующего вызова *SetHashParam(HP_OPEN, TRUE) для CSP 3.6 и выше;
• предварительного вызова *DuplicateHash() - стандартный для Microsoft способ;

Для хэш с алгоритмами CALG_MD5, CALG_SHA1, CALG_SHA_256, CALG_SHA_384, CALG_SHA_512, CALG_G28147_IMIT, CALG_GR3413_2015_M_IMIT, CALG_GR3413_2015_K_IMIT функция может отработать успешно, но значение ключа всегда будет неопределённым.
Для хэш с алгоритмом CALG_SHAREDKEY_HASH функция вырабатывает очередную компоненту ключа.
Для хэш с алгоритмом CALG_FITTINGKEY_HASH функция вырабатывает собранный из компонентов ключ при условии, что все компоненты собраны функцией *HashSessionKey().

dwFlags

[in] Флаги определяют признаки производимого ключа сессии. В настоящее время определены следующие значения флагов:

Значение dwFlags	Описание
CRYPT_EXPORTABLE	Если флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPExportKey(). Если флаг не установлен, ключ не будет экспортируемым и будет доступен только в пределах текущей сессии приложению, которое создало этот ключ. Действие этого флага не распространяются на открытый ключ ключевых пары.
CRYPT_SERVER	Если при работе с TLS флаг установлен, то создаётся ключ шифрования сервера, если не установлен - создаётся ключ шифрования клиента.
CP_CRYPT_GETUPPERKEY	Если флаг установлен, то для ГОСТ Р 34.11-2012 512 бит (и HMAC-ов на его основе) функция будет использовать старшие 32 байта хэш-значения. Не может быть использован с другими алгоритмами.
CP_CRYPT_DUPLICATE_KEY	При установке данного флага функция вернет копию ключа, установленного в объект hHash. Если объект hHash был создан без ключа, вызов закончится с ошибкой.

phKey

[out] Адрес, по которому функция копирует дескриптор произведённого ключа.

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError.

Примечания

Если на вход подаётся фиксированный набор данных, то функция создаёт один и тот же ключ. В этом случае создаваемый ключ можно использовать только для шифрования данных или экспорта ключей на ключевые носители. Использовать его для шифрования данных или экспорта ключей, помещаемых на диск или передаваемых по каналу связи, не рекомендуется.

Использование алгоритмов CALG_MD5, CALG_SHA_256, CALG_SHA_384, CALG_SHA_512 не входит в функционал СКЗИ "КриптоПро CSP 5.0", относящийся к действию сертификата ФСБ.

Режимы шифрования, преобразования ключа, дополнения открытого текста до кратности блока, набор узлов замены для получаемого ключа устанавливаются такие же, как и для вновь созданного ключа (см. CPSetKeyParam()).

Полученный дескриптор ключа должен в обязательном порядке быть удалён с помощью вызова функции CPDestroyKey()  до вызова функции CPReleaseContext() для рабочего дескриптора криптопровайдера.

Требования:

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.
Ядро ОС: Вместо неё используется аналогичная функция CPCDeriveKey .

См. также

CPDestroyKey() ,CPGenKey() ,CPDeriveKey в MS CSP ,CryptDeriveKey в MS CryptoAPI 2.0