Функции хэширования

C_DigestInit, C_Digest, C_DigestUpdate и C_DigestFinal

C_DigestInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.

Инициализирует операцию хэширования.

Механизм хэширования задаётся в поле mechanism структуры CK_MECHANISM. Для хэширования библиотека Cryptoki поддерживает механизмы, перечисленные ниже. В зависимости от используемого механизма выполняется аппаратная или программная реализация функции.

  • Криптотокен

    • CKM_GOSTR3411 (0x00001210) – механизм хеширования, соответствующий стандарту ГОСТ Р 34.11-94.

      В зависимости от значений второго и третьего полей структуры CK_MECHANISM (см. таблицу ниже), вычисление хэш-последовательности выполняется аппаратно, т. е. с использованием криптографических возможностей устройства eToken ГОСТ или JaCarta ГОСТ, либо программно.

      pParameter ulParameterLen Способ вычисления хэш-последовательности
      NULL_PTR 0 Аппаратный (средствами JaCarta ГОСТ)
      0x06 0x07 0x2A 0x85 0x03 0x02 0x02 0x1E 0x01 9 Программный (используется набор эталонных параметров id-GostR3411-94-CryptoProParamSet, определённый в RFC 4357.
  • Laser

    • CKM_MD5 (0x00000210) механизм хеширования данных по алгоритму MD5.
    • CKM_SHA_1 (0x00000220) механизм хеширования данных по алгоритму SHA-1.
    • CKM_SHA256 (0x00000250) механизм хеширования данных по алгоритму SHA-256.
    • CKM_SHA384 (0x00000260) механизм хеширования данных по алгоритму SHA-384.
    • CKM_SHA512 (0x00000270) механизм хеширования данных по алгоритму SHA-512.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

Полный список ошибок см. в приложении.

C_Digest(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pDigest, CK_ULONG_PTR pulDigestLen)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pData (in) – указатель на данные.
  • ulDataLen (in) – размер данных.
  • pDigest (out) – указатель на хэш.
  • pulDigestLen (out) – размер хэша.

Осуществляет единоразовое хэширование, т.е хэширует только один блок данных.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_NOT_INITIALIZED – в указанном сеансе нет активной операции данного типа.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.

Совет

Полный список ошибок см. в приложении.

C_DigestUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pPart (in) – указатель на блок данных.
  • ulPartLen (in) – размер блока данных.

Продолжает составную операцию хэширования – хэширует очередной блок данных.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_NOT_INITIALIZED – в указанном сеансе нет активной операции данного типа.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.

Совет

Полный список ошибок см. в приложении.

C_DigestFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pDigest, CK_ULONG_PTR pulDigestLen)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pDigest (out) – указатель на хэш.
  • pulDigestLen (out) – размер хэша.

Завершает составную операцию хеширования.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_NOT_INITIALIZED – в указанном сеансе нет активной операции данного типа.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.

Совет

Полный список ошибок см. в приложении.

Пример использования

Для обеспечения успешного хэширования данных, необходимо, чтобы функции в алгоритме были использованы в одной из следующих последовательностей:

Для единоразовой операции хэширования Для составной операции хэширования
  1. C_DigestInit(),
  2. C_Digest().
  1. C_DigestInit(),
  2. C_DigestUpdate() (один или более раз),
  3. C_DigestFinal().

Пример вычисления хэш-последоватаельности на языке С:

// дескриптор сессии
CK_SESSION_HANDLE session = 0;
// механизм для вычисления хэш-последовательности. Вычислять значение хеш-функции программно.
CK_MECHANISM mech = { CKM_GOSTR3411, NULL_PTR, 0 };
// исходные данные для хэширования
CK_BYTE buffer[1024];
// результирующие данные для хэш-значения
CK_BYTE hash[32];
// размер хэш-последовательности
CK_ULONG hashLen = 32;

// задаем параметры механизма для апаратного вычисления значения хеш-функции
mech.pParameter = STR_CRYPTO_PRO_GOST3411;
mech.ulParameterLen = 9;

// функция задает механизм для вычисления хэш-последоватаельности
rv = C_DigestInit(session, &mech);
if(rv != CKR_OK)
{
   PrintError("C_DigestInit", rv);
}

// функция вычисляет хэш-последовательность
rv = C_Digest(session, buffer, sizeof(buffer), hash, &hashLen);
if(rv != CKR_OK)
{
   PrintError("C_Digest", rv);
}4

Пример вычисления хэш-последоватаельности на языке Java для ОС Android:

// дескриптор сессии
LongRef session = new LongRef();
// механизм для программного вычисления хэш-последовательности
CKM hashMech = new CKM(CKM.GOSTR3411, Default.STR_CRYPTO_PRO_GOST3411);
// буффер с данными для вычисления хэш-последовательности
byte[] data = new byte[32];
// буфер для результирующей хэш-последовательности
byte[] hash = new byte[32];
// длина буфера для хэш-последовательности
LongRef hashLength = new LongRef(hash.length);

// задание механизма для вычисления хэш-последовательности
rv = C.DigestInit(session.value, hashMech);
if(rv != CKR.OK)
{
        throw new CKRException("C_DigestInit", rv);
}

// вычисление хэш-последовательности
rv = C.Digest(session.value, data, hash, hashLength);
if(rv != CKR.OK)
{
        throw new CKRException("C_Digest", rv);
}