C_DigestInit

CK_RV C_DigestInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism)

Параметры:    

  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм. Идентификатор механизма задается в поле mechanism.

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

Поддерживаемые механизмы хэширования:

  • GOST

    • CKM_GOSTR3411 (0x00001210) – механизм хеширования, соответствующий стандарту ГОСТ Р 34.11–94;
    • CKM_GOSTR3411_2012_256 (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x012) – механизм хеширования по ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит);
    • CKM_GOSTR3411_12_256 – псевдоним для CKM_GOSTR3411_2012_256;
    • CKM_GOSTR3411_2012_512 (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x013) – механизм хеширования по ГОСТ Р 34.11–2012 (длина хэш–кода 512 бит);
    • CKM_GOSTR3411_12_512 – псевдоним для CKM_GOSTR3411_2012_512.

  • PKI

    • 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.

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

Для PKI:

Для GOST:

См. также: C_Digest(), C_DigestUpdate() и C_DigestFinal().

Результат:    

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. 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_RV 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) – размер хэша.

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

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

Для PKI:

Для GOST:

См. также: C_DigestInit(), C_DigestUpdate() и C_DigestFinal().

Результат:    

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. 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_RV C_DigestUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen)

Параметры:    

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

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

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


Для PKI:

Для GOST:

См. также: C_DigestInit(), C_Digest() и C_DigestFinal().

Результат:    

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. 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_RV C_DigestFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pDigest, CK_ULONG_PTR pulDigestLen)

Параметры:    

  • hSession (in) – дескриптор сеанса.
  • pDigest (out) – указатель на хэш.
  • pulDigestLen (out) – размер хэша.

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

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

Для PKI:

Для GOST:

См. также: C_DigestInit(), C_Digest() и C_DigestUpdate().

Результат:    

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. 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()

Вычисление хэш-последовательности по ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит) на языке C:

<pre>// дескриптор сессии
CK_SESSION_HANDLE session = 0;
 
// исходные данные для хэширования
CK_BYTE buffer[1024];
 
// механизм для вычисления хэш-последовательности по ГОСТ Р 34.11-2012 (длина хэш-кода 256 бит)
// вычислять значение хеш-функции аппаратно
CK_MECHANISM mech = { CKM_GOSTR3411_2012_256, NULL_PTR, 0 };
 
// результирующие данные для хэш-значения
// согласно CKM_GOSTR3411_2012_256 длина хэша - 32 байта (256 бит)
CK_BYTE hash[32];
 
// размер хэш-последовательности
// согласно CKM_GOSTR3411_2012_256 длина хэша - 32 байта (256 бит)
CK_ULONG hashLen = 32;
 
// функция задает механизм для вычисления хэш-последовательности
rv = C_DigestInit(session, &amp;mech);
if(rv != CKR_OK)
{
PrintError(&quot;C_DigestInit&quot;, rv);
return;
}
 
// функция вычисляет хэш-последовательность
rv = C_Digest(session, buffer, sizeof(buffer), hash, &amp;hashLen);
if(rv != CKR_OK)
{
PrintError(&quot;C_Digest&quot;, rv);
return;
}</pre>

 Вычисление хэш-последовательности по ГОСТ Р 34.11–2012 (длина хэш–кода 512 бит) на языке C:

<pre>// дескриптор сессии
CK_SESSION_HANDLE session = 0;
 
// исходные данные для хэширования
CK_BYTE buffer[1024];
 
// механизм для вычисления хэш-последовательности по ГОСТ Р 34.11-2012 (длина хэш-кода 512 бит)
// вычислять значение хеш-функции аппаратно
CK_MECHANISM mech = { CKM_GOSTR3411_2012_512, NULL_PTR, 0 };
 
// результирующие данные для хэш-значения
// согласно CKM_GOSTR3411_2012_512 длина хэша - 64 байта (512 бит)
CK_BYTE hash[64];
 
// размер хэш-последовательности
// согласно CKM_GOSTR3411_2012_512 длина хэша - 64 байта (512 бит)
CK_ULONG hashLen = 64;
 
// функция задает механизм для вычисления хэш-последовательности
rv = C_DigestInit(session, &amp;mech);
if(rv != CKR_OK)
{
PrintError(&quot;C_DigestInit&quot;, rv);
return;
}
 
// функция вычисляет хэш-последовательность
rv = C_Digest(session, buffer, sizeof(buffer), hash, &amp;hashLen);
if(rv != CKR_OK)
{
PrintError(&quot;C_Digest&quot;, rv);
return;
}</pre>