КриптоПро CSP  

CPCDeriveKey

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

DWORD CPCAPI CPCDeriveKey(
  HCRYPTMODULE hCSP,
  HCRYPTPROV hProv,
  ALG_ID AlgId,
  HCRYPTHASH hBaseData,
  DWORD dwFlags,
  HCRYPTKEY * phKey
);

Аргументы

hCSP
[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().
AlgId
[in] Идентификатор алгоритма шифрования, для которого производится ключ.
Значение AlgId Описание
CALG_G28147 Ключ шифрования и/или имитозащиты данных по ГОСТ 28147-89. Впоследствии этот ключ может быть преобразован с помощью функции CPCSetKeyParam() в ключ, на котором возможен экспорт/импорт других ключей.
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-ов на их основе) проводится дополнение до размера блока (если требуется), исполняются шаговые функции для последнего блока (если требуется), для длины и для контрольной суммы.
Для ГОСТ 28147-89 в режиме имитовставки проводится дополнение до размера блока (если требуется), и исполняется шаговая функции для последнего блока (если требуется).
Расчёт хэш-функции может быть продолжен с помощью:
  • последующего вызова *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_SHAREDKEY_HASH функция вырабатывает очередную компоненту ключа.
    Для хэш с алгоритмом CALG_FITTINGKEY_HASH функция вырабатывает собранный из компонентов ключ при условии, что все компоненты собраны функцией *HashSessionKey().
dwFlags
[in] Флаги определяют признаки производимого ключа сессии. В настоящее время определены следующие значения флагов:
Значение dwFlags Описание
CRYPT_EXPORTABLE Если флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPCExportKey(). Если флаг не установлен, ключ не будет экспортируемым и будет доступен только в пределах текущей сессии приложению, которое создало этот ключ. Действие этого флага не распространяются на открытый ключ ключевых пары.
CRYPT_SERVER Если при работе с TLS флаг установлен, то создается ключ шифрования сервера, если не установлен - создается ключ шифрования клиента.
CP_CRYPT_GETUPPERKEY Если флаг установлен, то для ГОСТ Р 34.11-2012 512 бит (и HMAC-ов на его основе) функция будет использовать старшие 32 байта хэш-значения. Не может быть использован с другими алгоритмами.
phKey
[out] Адрес, по которому функция копирует дескриптор произведённого ключа.

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).
Коды возвратаОписание
ERROR_INVALID_PARAMETERОдин из параметров содержит некорректное значение. Чаще всего это некорректный указатель.
NTE_BAD_ALGIDПараметр AlgId определяет алгоритм, который не поддерживается криптопровайдером.
NTE_BAD_FLAGSВеличина dwFlags имеет ошибочное значение.
NTE_BAD_HASHДескриптор хэша ошибочен.
NTE_NO_MEMORYКриптопровайдер во время операции исчерпал память.
NTE_FAILОшибка при считывании данных из системного реестра. см. Дополнительные параметры и определения .

Примечания

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

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

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

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

Требования:

Ядро FreeBSD: 7/8/9 или выше
Ядро Linux: ядро 2.4.x/2.6.x/3.0.х/3.2.х или выше
Ядро Solaris: 10/11 или выше.
Ядро Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше.

См. также

CPCDestroyKey() ,CPCGenKey() ,CPDeriveKey в MS CSP World Wide Web link ,CryptDeriveKey в MS CryptoAPI 2.0 World Wide Web link