КриптоПро CSP  

CPCCreateHash

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

DWORD CPCAPI CPCCreateHash(
  HCRYPTMODULE hCSP,
  HCRYPTPROV hProv,
  ALG_ID AlgId,
  HCRYPTKEY hKey,
  DWORD dwFlags,
  HCRYPTHASH * phHash
);

Аргументы

hCSP
[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().
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 на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-94;
  • CALG_TLS1_MASTER_HASH_2012_256 - Объект, содержащий ключевую информацию для создания ключей CALG_TLS1_ENC_KEY и CALG_TLS1_MAC_KEY на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012;
  • CALG_PBKDF2_2012_256 - Объект, содержащий ключевую информацию для выработки ключа из пароля на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 256 бит;
  • CALG_PBKDF2_2012_512 - Объект, содержащий ключевую информацию для выработки ключа из пароля на основе алгоритма хэширования в соответствии с ГОСТ Р 34.11-2012, длина выхода 512 бит;
  • CALG_TLS1PRF - Алгоритм "производящей функции" (PRF), генерирующей блок данных произвольной длины на основе ключа, метки и бинарных данных, базирующийся на алгоритме хэширования в соответствии с ГОСТ Р 34.11-94.
  • 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.
  • CALG_GR3411_2012_256_PRFKEYMAT - Алгоритм "производящей функции" (PRF) на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, генерирующей блок данных произвольной длины на основе бинарных данных (seed). Seed устанавливается через SetHashParam HP_PRFKEYMAT_SEED.
  • CALG_GR3411_2012_512_PRFKEYMAT - Алгоритм "производящей функции" (PRF) на базе алгоритма ГОСТ Р 34.11-2012 и сессионных ключей CALG_G28147/CALG_SYMMETRIC_512, генерирующей блок данных произвольной длины на основе бинарных данных (seed). Seed устанавливается через SetHashParam HP_PRFKEYMAT_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] Значения флагов.
phHash
[out] Адрес по которому функция копирует дескриптор нового объекта функции хэширования.

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).
Коды возвратаОписание
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, относящийся к действию сертификата ФСБ.

Требования:

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

См. также

CPCDestroyHash() ,CPCHashData() ,CPCreateHash в MS CSP World Wide Web link ,CryptCreateHash в MS CryptoAPI 2.0 World Wide Web link