КриптоПро CSP  

CPCreateHash

Функция CPCreateHash() инициализирует дескриптор нового объекта функции хэширования потока данных.

BOOL WINAPI CPCreateHash(
  HCRYPTPROV hProv,
  ALG_ID AlgId,
  HCRYPTKEY hKey,
  DWORD dwFlags,
  HCRYPTHASH * phHash
);

Аргументы

hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().
AlgId
[in] Идентификатор используемого алгоритма хэширования. В криптопровайдере определены следующие алгоритмы хэширования:
  • CALG_GR3411 - Алгоритм хэширования в соответствии с ГОСТ Р 34.11-94;
  • CALG_GR3411_2012_256 - Алгоритм хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 256 бит.
  • CALG_GR3411_2012_512 - Алгоритм хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 512 бит.
  • CALG_G28147_IMIT - Алгоритм имитозащиты в соответствии с ГОСТ 28147-89;
  • CALG_TLS1_MASTER_HASH - Объект, содержащий ключевую информацию для создания ключей CALG_TLS1_ENC_KEY и CALG_TLS1_MAC_KEY;
  • CALG_TLS1_MASTER_HASH_2012_256 - Объект, содержащий ключевую информацию для создания ключей CALG_TLS1_ENC_KEY и CALG_TLS1_MAC_KEY на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012;
  • CALG_PBKDF2_94_256 - Объект, содержащий ключевую информацию для выработки ключа из пароля на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-94, длина выхода 256 бит;
  • CALG_PBKDF2_2012_256 - Объект, содержащий ключевую информацию для выработки ключа из пароля на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 256 бит;
  • CALG_PBKDF2_2012_512 - Объект, содержащий ключевую информацию для выработки ключа из пароля на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 512 бит;
  • CALG_TLS1PRF - Алгоритм "производящей функции" (PRF), генерирующей блок данных произвольной длины на основе ключа, метки и бинарных данных.
  • CALG_TLS1PRF_2012_256 - Алгоритм "производящей функции" (PRF), генерирующей блок данных произвольной длины на основе ключа, метки и бинарных данных, базирующийся на алгоритме хэширования в соответствии с ГОСТ Р 34.11-2012.
  • CALG_GR3411_HMAC - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-94 и сессионного ключа CALG_G28147.
  • CALG_GR3411_2012_256_HMAC - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, длина выхода 256 бит.
  • CALG_GR3411_2012_512_HMAC - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, длина выхода 512 бит.
  • CALG_EKEVERIFY_HASH - Алгоритм ключевого хэширования в протоколе взаимодействия с функциональным ключевым носителем. Ключ должен иметь тип CALG_PRO_AGREEDKEY_DH. Данные должны быть составлены в порядке, соответствующем полям структуры TOKEN_VERIFYDATA, за исключением поля Verify, и должны иметь длину sizeof(TOKEN_VERIFYDATA)- sizeof(DWORD). Данные должны подаваться на функцию хэширования одним блоком. Длина данных, возвращаемых через CPGetHashParam() – 4 байта.
  • CALG_MD5 - Алгоритм хэширования MD5 (RFC 1321).
  • CALG_SHA1 - Алгоритм хэширования SHA-1 (RFC 3174, FIPS PUB 180-1).
  • CALG_SHA_256 - Алгоритм хэширования SHA-256 (FIPS PUB 180-3).
  • CALG_SHA_384 - Алгоритм хэширования SHA-384 (FIPS PUB 180-3).
  • CALG_SHA_512 - Алгоритм хэширования SHA-512 (FIPS PUB 180-3).
  • CALG_UECMASTER_DIVERS - Объект, содержащий ключевую информацию ключа CALG_UECSYMMETRIC для диверсификации ключей карт с использованием CPCDeriveKey().
  • CALG_SHAREDKEY_HASH - Объект, содержащий ключевую информацию симметричного ключа для разложения в компоненты с использованием CPCDeriveKey().
  • CALG_FITTINGKEY_HASH - Объект, предназначен для сбора компонент в ключ CALG_UECSYMMETRIC с занесением в ключевой контейнер, если отсутствует AT_UECSYMMETRICKEY, либо в ключ CALG_G28147, CALG_UECSYMMETRIC_EPHEM, с использованием CPCHashSessionKey(), результирующий ключ производится функцией CPCDeriveKey().
  • CALG_GR3411_HMAC_FIXEDKEY - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-94 с фиксированным сессионным ключом CALG_G28147. Ключ на вход не передается, а устанавливается после с помощью функции SetHashParam с параметром HP_HMAC_FIXEDKEY. Для использования в библиотеке IPsec.
  • CALG_GR3411_2012_256_HMAC_FIXEDKEY - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-2012 с фиксированным сессионным ключом CALG_SYMMETRIC_512, длина выхода 256 бит. Ключ на вход не передается, а устанавливается после с помощью функции SetHashParam с параметром HP_HMAC_FIXEDKEY. Для использования в библиотеке IPsec.
  • CALG_GR3411_2012_512_HMAC_FIXEDKEY - Алгоритм ключевого хэширования на базе алгоритма ГОСТ Р 34.11-2012 с фиксированным сессионным ключом CALG_SYMMETRIC_512, длина выхода 512 бит. Ключ на вход не передается, а устанавливается после с помощью функции SetHashParam с параметром HP_HMAC_FIXEDKEY. Для использования в библиотеке IPsec.
  • CALG_GR3411_PRFKEYMAT - Алгоритм "производящей функции" (PRF) на базе алгоритма ГОСТ Р 34.11-94 и сессионного ключа CALG_G28147, генерирующей блок данных произвольной длины на основе бинарных данных (seed). Seed устанавливается через SetHashParam HP_PRFKEYMAT_SEED, а также может быть накоплен с помощью последовательных вызовов HashData и HashSessionKey. Установка seed должна производиться до хэширования.
  • CALG_GR3411_2012_256_PRFKEYMAT - Алгоритм "производящей функции" (PRF) на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, генерирующей блок данных произвольной длины на основе бинарных данных (seed). Seed устанавливается через SetHashParam HP_PRFKEYMAT_SEED, а также может быть накоплен с помощью последовательных вызовов HashData и HashSessionKey. Установка seed должна производиться до хэширования.
  • CALG_GR3411_2012_512_PRFKEYMAT - Алгоритм "производящей функции" (PRF) на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, генерирующей блок данных произвольной длины на основе бинарных данных (seed). Seed устанавливается через SetHashParam HP_PRFKEYMAT_SEED, а также может быть накоплен с помощью последовательных вызовов HashData и HashSessionKey. Установка seed должна производиться до хэширования.
hKey
[in] Если используется алгоритм имитозащиты по ГОСТ 28147-89 (CALG_G28147_IMIT), в этом параметре передаётся ключ сессии для объекта функции хэширования.

Если используется алгоритм CALG_TLS1_MASTER_HASH или CALG_TLS1_MASTER_HASH_2012_256, в этом параметре передается master_secret (ключ типа CALG_TLS1_MASTER), на основе которого будет создана ключевая информация по следующей формуле:
	    
      key_block = PRF(SecurityParameters.master_secret,
                         "key expansion",
                         SecurityParameters.server_random +
                         SecurityParameters.client_random);
	
Предварительно следует установить KP_CLIENT_RANDOM и KP_SERVER_RANDOM.

Если используется алгоритм CALG_TLS1PRF или CALG_TLS1PRF_2012_256, в этом параметре передается ключ типа CALG_TLS1_MASTER.

Для алгоритмов хэширования типа ГОСТ Р 34.11-94 и ГОСТ Р 34.11-2012 этот параметр должен быть установлен в ноль.
dwFlags
[in] Значения флагов.
  • CP_REUSABLE_HMAC - Указывается при создании объекта HMAC для повышения эффективности повторного использования;
  • CP_HASH_ITER_NUMBER - Указывается при создании объекта PRFKEYMAT для дополнительного хэширования номера итерации (PRFPLUS).
phHash
[out] Адрес по которому функция копирует дескриптор нового объекта функции хэширования.

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

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

Примечания

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

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

Требования:

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

См. также

CPDestroyHash() ,CPHashData() ,CPCreateHash в MS CSP World Wide Web link ,CryptCreateHash в MS CryptoAPI 2.0 World Wide Web link