Функция CryptCreateHash (wincrypt.h)

Статья
03/13/2024

Важно Этот API является устаревшим. Новое и существующее программное обеспечение должно начать использовать API-интерфейсы шифрования следующего поколения. Корпорация Майкрософт может удалить этот API в будущих выпусках.

Функция CryptCreateHash инициирует хэширование потока данных. Он создает и возвращает вызывающему приложению дескриптор хэш-объекта поставщика служб шифрования (CSP). Этот дескриптор используется в последующих вызовах CryptHashData и CryptHashSessionKey для ключей хэш-сеанса и других потоков данных.

Синтаксис

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Параметры

[in] hProv

Дескриптор CSP, созданный вызовом CryptAcquireContext.

[in] Algid

Значение ALG_ID , определяющее используемый хэш-алгоритм.

Допустимые значения для этого параметра зависят от используемого CSP. Список алгоритмов по умолчанию см. в разделе Примечания.

[in] hKey

Если тип хэш-алгоритма является хэш-ключом, например хэш-код проверки подлинности сообщений на основе хэша (HMAC) или алгоритм кода проверки подлинности сообщений (MAC), ключ для хэша передается в этом параметре. Для алгоритмов, не являющихся ключами, этот параметр должен иметь нулевое значение.

Для алгоритмов с ключами ключ должен быть ключом блочного шифра , например RC2, который имеет режим шифра цепочки блоков шифра (CBC).

[in] dwFlags

Определено следующее значение флага.

Значение	Значение
CRYPT_SECRETDIGEST 0x00000001	Этот флаг не используется.

[out] phHash

Адрес, на который функция копирует дескриптор в новый хэш-объект. Завершив использование хэш-объекта, отпустите дескриптор, вызвав функцию CryptDeographyHash .

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

Если функция выполняется успешно, функция возвращает значение TRUE.

Если функция завершается сбоем, она возвращает значение FALSE. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.

Коды ошибок, предваряемые NTE, создаются конкретным поставщиком служб CSP, который вы используете. В следующей таблице показаны некоторые возможные коды ошибок.

Код возврата	Описание
ERROR_INVALID_HANDLE	Один из параметров указывает недопустимый дескриптор.
ERROR_INVALID_PARAMETER	Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель.
ERROR_NOT_ENOUGH_MEMORY	Во время операции в операционной системе не хватает памяти.
NTE_BAD_ALGID	Параметр Algid указывает алгоритм, который не поддерживается этим поставщиком служб конфигурации.
NTE_BAD_FLAGS	Параметр dwFlags не равен нулю.
NTE_BAD_KEY	Хэш-алгоритм с ключом, например CALG_MAC, задается в Algid, а параметр hKey равен нулю или указывает недопустимый дескриптор ключа. Этот код ошибки также возвращается, если ключом является потоковый шифр или режим шифра, отличный от CBC.
NTE_NO_MEMORY	Во время операции у поставщика служб конфигурации не хватает памяти.

Вычисление фактического хэша выполняется с помощью функций CryptHashData и CryptHashSessionKey . Для них требуется дескриптор хэш-объекта. После добавления всех данных в хэш-объект можно выполнить любую из следующих операций:

Хэш-значение можно получить с помощью CryptGetHashParam.
Ключ сеанса можно получить с помощью CryptDeriveKey.
Хэш можно подписать с помощью CryptSignHash.
Подпись можно проверить с помощью CryptVerifySignature.

После вызова одной из функций из этого списка невозможно вызвать CryptHashData и CryptHashSessionKey .

Примеры

В следующем примере показано инициализация хэширования потока данных. Он создает и возвращает вызывающему приложению дескриптор хэш-объекта. Этот дескриптор используется в последующих вызовах CryptHashData и CryptHashSessionKey для хэширования любого потока данных. Пример, включающий полный контекст для этого примера, см. в разделе Пример программы C: создание и хэширование ключа сеанса. Еще один пример, в котором используется эта функция, см. в разделах Пример программы C. Подписывание хэша и Проверка хэш-подписи.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll