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

USB-токены и смарт-карты JaCartaAPI и SDKUSB-токены и смарт-карты JaCarta

Примечание: Функции C_Decrypt(), C_DecryptUpdate() и C_DecryptFinal() не возвращают предусмотренного стандартом PKCS #11 кода ошибки CKR_ENCRYPTED_DATA_INVALID (недопустимые зашифрованные данные).

C_DecryptInit

CK_RV C_DecryptInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) Параметры:

hSession (in) – дескриптор сеанса.
pMechanism (in) – указатель на механизм. Идентификатор механизма задается в поле mechanism.
hKey (in) – дескриптор ключа расшифрования. Инициализирует и задает параметры для операции расшифрования. Поддерживается как аппаратное, так и программное расшифрование. Особенности приложения GOST:
Расшифрование на СКЗИ с защитой ключа (рекомендуемый режим) Для расшифрования на СКЗИ с защитой ключа используется виртуальный секретный ключ. Дескриптор этого ключа получается путем поиска объекта типа CKO_SECRET_KEY с атрибутом CKA_ID, равным значению “VSKO_ID”. Важно отметить, что на данном этапе сам ключевой материал отсутствует в памяти СКЗИ. Ключ должен быть предварительно сгенерирован и экспортирован с помощью функции C_WrapKey() или импортирован с помощью C_UnwrapKey(). Как только ключевой материал появляется в памяти СКЗИ, атрибут CKA_KT2_KEY_ACTIVE устанавливается в значение CK_TRUE. После завершения операции расшифрования ключ удаляется из памяти устройства, а атрибут CKA_KT2_KEY_ACTIVE сбрасывается в значение CK_FALSE.
Расшифрование с использованием сессионных ключей Шифрование с использованием сессионных ключей может выполняться на ключах, предварительно сгенерированных функцией C_GenerateKey() или импортированных в сессию с помощью функции C_CreateObject(). Атрибут CKA_TOKEN сессионных ключей имеет значение CK_FALSE. Также для механизма расшифрования CKM_GOST28147 доступен атрибут CKA_KT2_KEY_MESHING. Если его значение — CK_TRUE, применяется алгоритм усложнения ключей в соответствии с ГОСТ 28147–89 (RFC 4357, п. 2.3.2). Поддерживаются следующие механизмы для разных приложений:
GOST версии 2.5.5
- CKM_GOST28147_ECB (0x00001221) – механизм для симметричного шифра в режиме ECB по стандарту ГОСТ 28147–89.
- CKM_GOST28147 (0x00001222) – механизм для симметричного шифра в режиме CFB по стандарту ГОСТ 28147–89.
- CKM_MAGMA_CBC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x023) шифрование по алгоритму Магма в режиме сцепления блоков шифротекста
- CKM_MAGMA_CTR (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x020) шифрование по алгоритму Магма в режиме гаммирования
- CKM_MAGMA_CFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x022) шифрование по алгоритму Магма в режиме обратной загрузке шифротекста
- CKM_MAGMA_CTR_ACPKM (CK_VENDOR_PKCS11_RU_TEAM_TC26 |0x036UL) шифрование по алгоритму Магма в режиме гаммирования с преобразованием ключа
- CKM_MAGMA_OFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x022) шифрование по алгоритму Магма в режиме обратной загрузке выходных данных
GOST версии 2.5.13
- CKM_MAGMA_CBC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x023) шифрование по алгоритму Магма в режиме сцепления блоков шифротекста
- CKM_MAGMA_CTR (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x020) шифрование по алгоритму Магма в режиме гаммирования
- CKM_MAGMA_CFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x022) шифрование по алгоритму Магма в режиме обратной загрузке шифротекста
- CKM_MAGMA_CTR_ACPKM (CK_VENDOR_PKCS11_RU_TEAM_TC26 |0x036UL) шифрование по алгоритму Магма в режиме гаммирования с преобразованием ключа
- CKM_MAGMA_OFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x022) шифрование по алгоритму Магма в режиме обратной загрузке выходных данных
- CKM_KUZNECHIK_CBC (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x01E) шифрование по алгоритму Кузнечик в режиме сцепления блоков шифротекста
- CKM_KUZNECHIK_CTR (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x01B) шифрование по алгоритму Кузнечик в режиме гаммирования
- CKM_KUZNECHIK_CFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x01C) шифрование по алгоритму Кузнечик в режиме обратной загрузке шифротекста
- CKM_KUZNECHIK_CTR_ACPKM (CK_VENDOR_PKCS11_RU_TEAM_TC26 |0x032UL) шифрование по алгоритму Кузнечик в режиме гаммирования с преобразованием ключа
- CKM_KUZNECHIK_OFB (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x01D) шифрование по алгоритму Кузнечик в режиме обратной загрузке выходных данных
PKI
- CKM_RSA_PKCS (0x00000001) – механизм для асимметричного шифра RSA. Также используется для ЭП.
- CKM_RSA_PKCS_OAEP (0x00000009) – механизм для асимметричного шифра RSA с использованием OAEP.
- CKM_DES3_ECB (0x00000132) – механизм для симметричного шифра triple-DES в режиме ECB.
- CKM_DES3_CBC (0x00000133) – механизм для симметричного шифра triple-DES в режиме CBC.
- CKM_AES_ECB (0x00001081) – механизм для симметричного шифра AES в режиме ECB.
- CKM_AES_CBC (0x00001082) – механизм для симметричного шифра AES в режиме CBC.

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

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

См. также: C_Decrypt(), C_DecryptUpdate() и C_DecryptFinal().

Результат:

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_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен. Совет: Полный список ошибок см. в приложении.

C_Decrypt

CK_RV C_Decrypt(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedData, CK_ULONG_PTR pulEncryptedDataLen, CK_BYTE_PTR pData, CK_ULONG ulDataLen)

Параметры:

hSession (in) – дескриптор сеанса.
pEncryptedData (in) – указатель на зашифрованные данные.
pulEncryptedDataLen (in) – размер зашифрованных данных.
pData (out) – указатель на исходные данные.
ulDataLen (out) – размер данных. Осуществляет единоразовое расшифрование, т.е. расшифровывает только один блок данных. Предупреждение: При шифровании с использованием механизма CKM_GOST28147_ECB длина данных должна быть кратной 8 байт.

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

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

См. также” C_DecryptInit(), C_DecryptUpdate() и C_DecryptFinal(). Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_ENCRYPTED_DATA_LEN_RANGE – недопустимый размер зашифрованных данных.
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_DecryptUpdate

CK_RV C_DecryptUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart, CK_ULONG_PTR pulEncryptedPartLen) Параметры:

hSession (in) – дескриптор сеанса.
pEncryptedPart (in) – указатель на зашифрованный блок данных.
pulEncryptedPartLen (in) – размер зашифрованного блока данных.
pPart (out) – указатель на блок исходных данных.
ulPartLen (out) – размер блока данных. Продолжает составную операцию расшифрования – расшифровывает очередной блок данных. Предупреждение: При шифровании с использованием механизма CKM_GOST28147_ECB длина данных должна быть кратной 8 байт.

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

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

См. также: C_DecryptInit(), C_Decrypt() и C_DecryptFinal(). Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_ENCRYPTED_DATA_LEN_RANGE – недопустимый размер зашифрованных данных.
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_DecryptFinal

CK_RV C_DecryptFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastEncryptedPart, CK_ULONG_PTR pulLastEncryptedPartLen)

Параметры:

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

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

Пользователь

См. также: C_DecryptInit(), C_Decrypt() и C_DecryptUpdate().

Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_ENCRYPTED_DATA_LEN_RANGE – недопустимый размер зашифрованных данных.
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 – действие не может быть выполнено, т.к. пользователь не залогинен. Совет: Полный список ошибок см. в приложении.

Пример

    ////////////////////////////////////////////////////////////////////
    /// осуществляем импорт симметричного ключа Магма (ГОСТ 34.12-2018)
    rv = CALL_P11(C_UnwrapKey(hSession, &wrapMechanism, hReceiverPrivateKey, wrappedKey, wrappedKeyLen, secretKeyTemplate, sizeof(secretKeyTemplate) / sizeof(CK_ATTRIBUTE), &hVirtualSecretKey));
    CHECK_RES(rv, "C_UnwrapKey");
    printf("C_UnwrapKey - OK\n");
    printf("Key unwrapping: ok\n");

    //////////////////////////////////////////////////////////////////////
    // Инициализировать операцию расшифрования по алгоритму ГОСТ 28147-89
    rv = CALL_P11(C_DecryptInit(hSession, &ckmEncDec, hVirtualSecretKey));
    CHECK_RES(rv, "C_DecryptInit");
    printf("C_DecryptInit - OK\n");

    //////////////////////////////////////////////////////
    /// Определяем размер буфера для расшифрованных данных
    rv = CALL_P11(C_Decrypt(hSession, pEncrypted, ulEncryptedLen, NULL_PTR, &ulDecryptedLen));

    // выделяем память для расшифрованных данных
    pDecrypted = (CK_BYTE_PTR)malloc(ulDecryptedLen);

    //////////////////////////
    /// расшифровываем данные
    rv = CALL_P11(C_Decrypt(hSession, pEncrypted, ulEncryptedLen, pDecrypted, &ulDecryptedLen));
    CHECK_RES(rv, "C_UnwrapKey");
    printf("C_UnwrapKey - OK\n");
    printf("Data decryption: ok\n");