C_SignInit

CK_RV C_SignInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey)

Параметры:    

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

Инициализирует операцию подписи для указанного ключа, выработки имитовставки и вычисления HMAC.

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

  • GOST версии 2.5.5, 2.5.9
    • CKM_GOSTR3410_256 – псевдоним для CKM_GOSTR3410;
    • CKM_GOSTR3410_WITH_GOSTR3411_2012_256 (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x008) – механизм для генерации и проверки ЭП (ГОСТ Р 34.10–2012 (длина ключа 256 бит)) с хэшированием (ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит)) подаваемых на вход данных. Размер данных не ограничен.
    • CKM_GOSTR3410_WITH_GOSTR3411_12_256 – псевдоним для CKM_GOSTR3410_WITH_GOSTR3411_2012_256;
    • CKM_GOSTR3411_2012_256_HMAC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x014) – механизм выработки и проверки имитовставки, соответствующий стандарту ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит);
    • CKM_GOSTR3411_12_256_HMAC – псевдоним для CKM_GOSTR3411_2012_256_HMAC;
    • CKM_GOSTR3411_2012_512_HMAC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x015) – механизм выработки и проверки имитовставки, соответствующий стандарту ГОСТ Р 34.11–2012 (длина хэш–кода 512 бит);
    • CKM_GOSTR3411_12_512_HMAC – псевдоним для CKM_GOSTR3411_2012_512_HMAC.
  • GOST версии 2.5.13
    • CKM_GOSTR3410_256 – псевдоним для CKM_GOSTR3410;
    • CKM_GOSTR3410_WITH_GOSTR3411_2012_256 (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x008) – механизм для генерации и проверки ЭП (ГОСТ Р 34.10–2012 (длина ключа 256 бит)) с хэшированием (ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит)) подаваемых на вход данных. Размер данных не ограничен.
    • CKM_GOSTR3410_WITH_GOSTR3411_12_256 – псевдоним для CKM_GOSTR3410_WITH_GOSTR3411_2012_256
    • CKM_GOSTR3411_2012_256_HMAC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x014) – механизм выработки и проверки имитовставки, соответствующий стандарту ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит)
    • CKM_GOSTR3411_12_256_HMAC – псевдоним для CKM_GOSTR3411_2012_256_HMAC;
    • CKM_GOSTR3411_2012_512_HMAC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x015) – механизм выработки и проверки имитовставки, соответствующий стандарту ГОСТ Р 34.11–2012 (длина хэш–кода 512 бит)
    • CKM_GOSTR3411_12_512_HMAC – псевдоним для CKM_GOSTR3411_2012_512_HMAC.
    • CKM_GOSTR3410_512 - механизм реализации алгоритма подписи/проверки уже вычисленного значения хэш-функции на ключе длиной 512 бит
    • CKM_GOSTR3410_WITH_GOSTR3411_2012_512 - механизм совместного алгоритма хэширования [ГОСТ 34.11-2018] с длиной хэш-функции 512 бит и алгоритма подписи [ГОСТ 34.10-2018] на ключе ЭП длиной 512 бит
  • PKI
    • CKM_RSA_PKCS (0x00000001) – механизм для генерации и проверки ЭП по алгоритму RSA. Может быть также использован для зашифрования/расшифрования данных.
    • CKM_SHA1_RSA_PKCS (0x00000006) – механизм для генерации и проверки ЭП (RSA) с предварительным хэшированием по алгоритму SHA-1.
    • CKM_SHA256_RSA_PKCS (0x00000040) – механизм для генерации и проверки ЭП (RSA) с предварительным хэшированием по алгоритму SHA-256.
    • CKM_DES3_MAC (0x00000134) – механизм для формирования и проверки имитовставки фиксированной длины на основе triple-DES. Ограничение длины выхода – 4 байт.
    • CKM_DES3_MAC_GENERAL (0x00000135) – механизм для формирования и проверки имитовставки произвольной длины на основе triple-DES.
    • CKM_MD5_HMAC (0x00000211) – механизм для формирования и проверки имитовставки на основе MD5.
    • CKM_SHA_1_HMAC (0x00000221) – механизм для формирования и проверки имитовставки на основе SHA-1.
    • CKM_SHA256_HMAC (0x00000251) – механизм для формирования и проверки имитовставки на основе SHA-256.
    • CKM_SHA384_HMAC (0x00000261) – механизм для формирования и проверки имитовставки на основе SHA-384.
    • CKM_SHA512_HMAC (0x00000271) – механизм для формирования и проверки имитовставки на основе SHA-512.
    • CKM_CMS_SIG (0x00000500) – механизм для генерации и проверки ЭП в формате CMS.
    • CKM_ECDSA (0x00001041) – механизм для генерации и проверки ЭП по алгоритму ECDSA.
    • CKM_ECDSA_SHA1 (0x00001042) – механизм для генерации и проверки ЭП (ECDSA) с предварительным хэшированием по алгоритму SHA1.
    • CKM_ECDSA_SHA256 (0x00001043) – механизм для генерации и проверки ЭП (ECDSA) с предварительным хэшированием по алгоритму SHA256.
    • CKM_AES_MAC (0x00001083) – механизм для формирования и проверки имитовставки фиксированной длины на основе AES. Ограничение длины выхода – 8 байт.
    • CKM_AES_MAC_GENERAL (0x00001084) – механизм для формирования и проверки имитовставки произвольной длины на основе AES
    • CKM_SHA1_RSA_PKCS_PSS - механизм для генерации и проверки ЭП по алгоритму RSASSA-PSS с применением алгоритма хэширования SHA-1
    • CKM_SHA224_RSA_PKCS_PSS - механизм для генерации и проверки ЭП по алгоритму RSASSA-PSS с применением алгоритма хэширования SHA-224
    • CKM_SHA256_RSA_PKCS_PSS - механизм для генерации и проверки ЭП по алгоритму RSASSA-PSS с применением алгоритма хэширования SHA-256
    • CKM_SHA384_RSA_PKCS_PSS - механизм для генерации и проверки ЭП по алгоритму RSASSA-PSS с применением алгоритма хэширования SHA-384
    • CKM_SHA512_RSA_PKCS_PSS - механизм для генерации и проверки ЭП по алгоритму RSASSA-PSS с применением алгоритма хэширования SHA-512

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

См. также: C_Sign(), C_SignUpdate() и C_SignFinal().

Результат:    

  • 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_KEY_FUNCTION_NOT_PERMITTED – атрибуты ключа не позволяют его использование данным образом.
  • CKR_KEY_HANDLE_INVALID – недопустимый дескриптор ключа.
  • CKR_KEY_SIZE_RANGE – размер ключа лежит за пределами, поддерживаемыми библиотекой.
  • CKR_KEY_TYPE_INCONSISTENT – данный ключ невозможно использовать с указанным механизмом.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_OPERATION_NOT_INITIALIZED – операция подписи для указанного ключа не может быть инициализирована, т.к. ключ не был сгенерирован или импортирован.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

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

C_Sign

CK_RV C_Sign(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pSignature, CK_ULONG_PTR pulSignatureLen)

Параметры:    

  • hSession (in) – дескриптор сеанса.
  • pData (in) – указатель на данные.
  • ulDataLen (in) – размер данных.
  • pSignature (out) – указатель на подпись.
  • pulSignatureLen (out) – размер подписи.

Осуществляет единоразовую подпись, т.е. подписывает только один блок данных. Либо вычисляет HMAC от одного блока данных, вырабатывает имитовставку от одного блока данных – конкретная операция зависит от того, с каким значением параметра pMechanism была инициализирована операция подписи.

Примечание: Если операция подписи инициализирована с механизмом CKM_GOSTR3410 (см. C_SignInit()), то поддерживается только 32-байтовый размер данных.

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

См. также: C_SignInit(), C_SignUpdate() и C_SignFinal().

Результат:    

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

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

C_SignUpdate

CK_RV C_SignUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen)

Параметры:    

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

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

Примечание: Механизмы, используемые в процессе выработки электронной подписи или имитовставки предварительно задаются функцией C_SignInit().

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

См. также: C_SignInit(), C_Sign() и C_SignFinal().

Результат:    

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

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

C_SignFinal

CK_RV C_SignFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pSignature, CK_ULONG_PTR pulSignatureLen)

Параметры:    

  • hSession (in) – дескриптор сеанса.
  • pSignature (out) – указатель на подпись.
  • pulSignatureLen (out) – размер подписи.

Завершает составную операцию подписи, вычисления HMAC или выработки имитовставки.

Примечание: Механизмы, используемые в процессе выработки электронной подписи или имитовставки предварительно задаются функцией C_SignInit().

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

См. также: C_SignInit(), C_SignUpdate() и C_Sign().

Результат:    

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

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

Пример

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



  1. C_SignInit()
  2. C_Sign()
  1. C_SignInit()
  2. C_SignUpdate() (один или более раз)
  3. C_SignFinal()

Пример выработки ЭП по ГОСТ Р 34.10–2012 (длина ключа 256 бит) на языке C++:

<pre>// дескриптор сессии
CK_SESSION_HANDLE session = 0;
 
// механизм для формирования ЭП по ГОСТ Р 34.10-2012 с хешированием по ГОСТ Р 34.11-2012
CK_MECHANISM mech = { CKM_GOSTR3410_WITH_GOSTR3411_12_256, NULL_PTR, 0 };
 
// дескриптор закрытого ключа
CK_OBJECT_HANDLE privKeyHandle;
 
// подписываемые данные
CK_BYTE data[128];
 
// буфер для результирующей подписи
CK_BYTE signature[64];
 
// длина буфера подписи
CK_ULONG signatureLength = sizeof(signature);
 
// инициализируем операцию подписи
rv = C_SignInit(session, &amp;mech, privKeyHandle);
if(rv != CKR_OK)
{
PrintError(&quot;C_SignInit&quot;, rv);
return;
}
 
// подписываем данные
rv = C_Sign(session, data, sizeof(data), signature, &amp;signatureLength);
if(rv != CKR_OK)
{
PrintError(&quot;C_Sign&quot;, rv);
return;
}</pre><p><br /></p>

Пример выработки ЭП по RSA с предварительным хэшированием по SHA-256 на языке C++:

<pre>// дескриптор сессии
CK_SESSION_HANDLE session = 0;
 
// механизм для формирования ЭП по RSA с предварительным хэшированием по SHA-256
CK_MECHANISM mech = { CKM_SHA256_RSA_PKCS, NULL_PTR, 0 };
 
// дескриптор закрытого ключа
CK_OBJECT_HANDLE privKeyHandle;
 
// подписываемые данные
CK_BYTE data[128];
 
// буфер для результирующей подписи. Длина подписи зависит от ключа, который использовался при ее создании
std::vector&lt;CK_BYTE&gt; signature(1, 0);
 
// длина буфера подписи
CK_ULONG signatureLength = sizeof(data);
 
// инициализируем операцию подписи
rv = C_SignInit(session, &amp;mech, privKeyHandle);
if(rv != CKR_OK)
{
PrintError(&quot;C_SignInit&quot;, rv);
return;
}
 
// подписываем данные
rv = C_Sign(session, data, sizeof(data), &amp;signature.at(0), &amp;signatureLength);
if(rv != CKR_OK)
{
PrintError(&quot;C_Sign&quot;, rv);
return;
}</pre>