Функции зашифрования

C.EncryptInit, C.Encrypt, C.EncryptUpdate и C.EncryptFinal

Предупреждение

При шифровании с использованием механизма CKM_GOST28147 длина данных должна быть кратной 8 байт.

C.EncryptInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey)

Параметры:

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

Инициализирует операцию зашифрования по ГОСТ 28147-89. Поддерживается как аппаратное, так и программное зашифрование.

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

Для апплета Криптотокен:

• CKM_GOST28147 (0x00001221) – механизм для симметричного шифра в режиме ECB по стандарту ГОСТ 28147-89.
• CKM_GOST28147 (0x00001222) – механизм для симметричного шифра в режиме CFB по стандарту ГОСТ 28147-89.

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

• Пользователя.

См.также

C.Encrypt(), C.EncryptUpdate() и C.EncryptFinal().

Результат:

• 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_KEY_FUNCTION_NOT_PERMITTED – атрибуты ключа не позволяют его использование данным образом.
• CKR_KEY_HANDLE_INVALID – недопустимый дескриптор ключа.
• CKR_KEY_SIZE_RANGE – размер ключа лежит за пределами, поддерживаемыми библиотекой Cryptoki.
• CKR_KEY_TYPE_INCONSISTENT – данный ключ невозможно использовать с указанным механизмом.
• 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.Encrypt(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pEncryptedData, CK_ULONG_PTR pulEncryptedDataLen)

Параметры:

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

Осуществляет единоразовое зашифрование, т.е зашифровывает только один блок данных. Шифрование выполняется по ГОСТ 28147-89.

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

• Пользователя.

См.также

C.EncryptInit(), C.EncryptUpdate() и C.EncryptFinal().

Результат:

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

Совет

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

C.EncryptUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart, CK_ULONG_PTR pulEncryptedPartLen)

Параметры:

• hSession (in) – дескриптор сеанса.
• pPart (in) – указатель на блок исходных данных.
• ulPartLen (in) – размер блока данных.
• pEncryptedPart (out) – указатель на зашифрованный блок данных.
• pulEncryptedPartLen (out) – размер зашифрованного блока данных.

Продолжает составную операцию зашифрования – зашифровывает очередной блок данных (по ГОСТ 28147-89).

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

• Пользователя.

См.также

C.EncryptInit(), C.Encrypt() и C.EncryptFinal().

Результат:

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

Совет

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

C.EncryptFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastEncryptedPart, CK_ULONG_PTR pulLastEncryptedPartLen)

Параметры:

• hSession (in) – дескриптор сеанса.
• pLastEncryptedPart (out) – последний зашифрованный блок.
• pulLastEncryptedPartLen (out) – размер последнего зашифрованного блока.

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

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

• Пользователя.

См.также

C.EncryptInit(), C.Encrypt() и C.EncryptUpdate().

Результат:

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

Совет

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

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

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

Для единоразовой операции зашифрования	Для составной операции зашифрования
C.EncryptInit(), C.Encrypt().	C.EncryptInit(), C.EncryptUpdate() (один или более раз), C.EncryptFinal().

Пример зашифрования для ОС Android на языке Java:

// дескриптор сессии
LongRef session = new LongRef();
// дескриптор сессионного ключа
LongRef sessionKeyHandle = new LongRef();
// механизм для шифрования данных
CKM encryptionMech = new CKM(CKM.GOST28147, null);
// шифруемое сообщение
byte[] plainData = new byte[32];
// зашифрованное сообщение
byte[] encryptedData = new byte[32];
// длинна сообщений
LongRef dataLength = new LongRef(encryptedData.length);

// инициализация шифрования
rv = C.EncryptInit(session.value, encryptionMech, sessionKeyHandle.value);
if(rv != CKR.OK)
{
        throw new CKRException("C.EncryptInit", rv);
}

// шифрование
rv = C.Encrypt(session.value, plainData, encryptedData, dataLength);
if(rv != CKR.OK)
{
        throw new CKRException("C.Encrypt", rv);
}