Приложение

Общие сведения о работе с объектами

Атрибут CKA_TOKEN определяет расположение и длительность хранения объекта. Возможные значения:

  • CK_TRUE – объект хранится только в памяти устройства и не удаляется после завершения сеанса;
  • CK_FALSE (либо не задан) – объект хранится в оперативной памяти и может использоваться только в промежуток времени с момента его создания и до закрытия сеанса (см. C_CloseSession() и C_CloseAllSessions()).
Возможное значение CKA_TOKEN для поддерживаемых объектов
  Криптотокен
Объект TRUE FALSE
CKO_PUBLIC_KEY V
CKO_PRIVATE_KEY V
CKO_SECRET_KEY (ключ согласования) V V
CKO_SECRET_KEY V
CKO_CERTIFICATE V V
CKO_DATA V V

Криптотокен

Примечание

Создание объектов с помощью апплета Криптотокен должно производиться в режиме пользователя.

CKO_PRIVATE_KEY

Поддерживаемые функции и особенности их работы с объектом CKO_PRIVATE_KEY
  CKA_TOKEN = CK_TRUE CKA_TOKEN = CK_FALSE
C_GenerateKeyPair() V X
Рекомендуемый набор атрибутов CKO_PRIVATE_KEY
Имя атрибута Значение атрибута
CKA_CLASS CKO_PRIVATE_KEY
CKA_PRIVATE CK_TRUE
CKA_TOKEN CK_TRUE
CKA_UNWRAP CK_FALSE
CKA_SIGN CK_TRUE
CKA_EXTRACTABLE CK_FALSE
CKA_NEVER_EXTRACTABLE CK_TRUE
CKA_ALWAYS_SENSITIVE CK_TRUE
CKA_MODIFIABLE CK_FALSE
CKA_SENSITIVE CK_TRUE
CKA_VALUE_LEN 32

Если значение хотя бы одного из атрибутов отличается от указанных в таблице выше, то функция возвращает CKR_ATTRIBUTE_READ_ONLY.

CKO_PUBLIC_KEY

Поддерживаемые функции и особенности их работы с объектом CKO_PUBLIC_KEY
  CKA_TOKEN = CK_TRUE CKA_TOKEN = CK_FALSE
C_CreateObject() V X
C_GenerateKeyPair() V X
Рекомендуемый набор атрибутов CKO_PUBLIC_KEY
Имя атрибута Значение атрибута
CKA_CLASS CKO_PUBLIC_KEY
CKA_PRIVATE CK_FALSE
CKA_TOKEN CK_TRUE
CKA_GOSTR3410_PARAMS см. Возможные значения атрибута CKA_GOSTR3410_PARAMS

Если значение хотя бы одного из атрибутов отличается от указанных в таблице выше, то функция возвращает CKR_ATTRIBUTE_READ_ONLY.

CKO_SECRET_KEY

Поддерживаемые функции и особенности их работы с объектом CKO_SECRET_KEY
  Ключ CKA_TOKEN = CK_TRUE CKA_TOKEN = CK_FALSE
C_CreateObject() Сеансовый секретный Возвращает CKR_ATTRIBUTE_VALUE_INVALID V
C_GenerateKey() Сеансовый секретный X V
C_DeriveKey() Согласования V V
C_UnwrapKey() Сеансовый секретный X V

Создание объекта секретного ключа в памяти токена (атрибут CKA_TOKEN = CK_TRUE) не предусмотрено.

Рекомендуемый набор атрибутов CKO_SECRET_KEY
Имя атрибута Значение атрибута
CKA_CLASS CKO_SECRET_KEY
CKA_PRIVATE CK_TRUE
CKA_TOKEN CK_TRUE

Если хотя бы один из заданных аргументами функции атрибутов принимает значение, отличное от приведённых в таблице, будет выдаваться ошибка CKR_ATTRIBUTE_READ_ONLY.

Для создания секретного ключа также необходимо указать CKA_VALUE, который должен быть представлен в формате от младшего к старшему (little endian).

Особенности работы с C_CreateObject

С помощью функции C_CreateObject() может быть создан сеансовый секретный ключ, (атрибут CK_TOKEN = CK_FALSE) который хранится только в рамках текущего сеанса, до момента выхода из режима пользователя или отключения устройства.

В шаблон создания такого объекта необходимо добавить атрибут CKA_GOST28147_PARAMS. Значение атрибута представляет собой массив байт, определяющий параметры функции шифрования, соответствующей ГОСТ 28147-89. Возможные значения смотри в таблице.

Объект должен создаваться в режиме пользователя.

Особенности работы с C_GenerateKey

Для выработки сеансового секретного ключа с помощью функции C_GenerateKey() используется набор параметров, который определяется структурой формата CK_GOSTR3410_DERIVE_PARAMS.

CKO_CERTIFICATE

Поддерживаемые функции и особенности их работы с объектом CKO_CERTIFICATE
  CKA_TOKEN = CK_TRUE CKA_TOKEN = CK_FALSE
C_CreateObject() V V

Рекомендуемый набор атрибутов:

  • CKA_CLASS;
  • CKA_TOKEN;
  • CKA_LABEL;
  • CKA_SERIAL_NUMBER.
Значения атрибутов, с которыми будет создаваться объект CKO_CERTIFICATE, если иные не были заданы явным образом
Атрибут Значение
CKA_CLASS (CK_OBJECT_CLASS)CKO_CERTIFICATE
CKA_TOKEN (CK_BBOOL)CK_TRUE
CKA_PRIVATE (CK_BBOOL)CK_FALSE
CKA_LABEL std::vector <CK_BYTE>(0)
CKA_TRUSTED (CK_BBOOL)CK_FALSE
CKA_SUBJECT std::vector <CK_BYTE>(0)
CKA_ID std::vector <CK_BYTE>(0)
CKA_SERIAL_NUMBER std::vector <CK_BYTE>(0)
CKA_MODIFIABLE (CK_BBOOL)CK_TRUE
CKA_COMPRESSED* (CK_BBOOL)CK_FALSE

Примечание

Привязка ключевой пары к сертификату происходит через атрибут CKA_ID.

CKO_DATA

Поддерживаемые функции и особенности их работы с объектом CKO_DATA
  CKA_TOKEN = CK_TRUE CKA_TOKEN = CK_FALSE
C_CreateObject() V V

Рекомендуемый набор атрибутов:

  • CKA_CLASS;
  • CKA_TOKEN;
  • CKA_LABEL;
  • CKA_VALUE.
Значения атрибутов, с которыми будет создаваться объект CKO_DATA, если иные не были заданы явным образом
Атрибут Значение
CKA_COMPRESSED* (CK_BBOOL)CK_FALSE

Компрессия данных

Компрессия данных реализована через атрибут CKA_COMPRESSED. Атрибут принимает значения CK_TRUE и CK_FALSE для включения и отключения компрессии соответственно.

По умолчанию атрибут установлен в значение CK_FALSE и присутствует во всех объектах типов CKO_CERTIFICATE и CKO_DATA. Компрессии подвергается аттрибут``CKA_VALUE``. Значение аттрибута присваивается при создании объекта и не изменяется впоследствии.

Компрессия поддерживается апплетом Криптотокен и предусмотрена в следующих функциях:

Возможные значения атрибутов CKA_GOST28147_PARAMS и CKA_GOSTR3410_PARAMS

Возможные значения атрибута CKA_GOST28147_PARAMS
Наименование параметров Содержание массива
id-Gost28147-89-TestParamSet 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00
id-Gost28147-89-CryptoPro-A-ParamSet 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x01
id-Gost28147-89-CryptoPro-B-ParamSet 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x02
id-Gost28147-89-CryptoPro-C-ParamSet 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x03
id-Gost28147-89-CryptoPro-D-ParamSet 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x04
В RFC 4357 данный набор параметров отсутствует. Он аналогичен набору id-Gost28147-89-CryptoPro-A-ParamSet, но предполагает использование режима гаммирования без обратной связи (имеющего в RFC 5830 наименование CNT). 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x65
Возможные значения атрибута CKA_GOSTR3410_PARAMS
Тип параметров эллиптических кривых Содержание массива
id-GostR3410-2001-CryptoPro-A-ParamSet 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01
id-GostR3410-2001-CryptoPro-B-ParamSet 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x02
id-GostR3410-2001-CryptoPro-C-ParamSet 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x03
id-GostR3410-2001-CryptoPro-XchA-ParamSet 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x24, 0x00
id-GostR3410-2001-CryptoPro-XchB-ParamSet 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x24, 0x01

Коды ошибок

  • CKR_OK (0x00000000) – функция выполнена успешно.
  • CKR_CANCEL (0x00000001) – операция была отменена.
  • CKR_HOST_MEMORY (0x00000002) – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_SLOT_ID_INVALID (0x00000003) – недопустимый идентификатор слота.
  • CKR_GENERAL_ERROR (0x00000005) – общий сбой при работе с библиотекой.
  • CKR_FUNCTION_FAILED (0x00000006) – выполнение функции было прервано или она не может быть выполнена.
  • CKR_ARGUMENTS_BAD (0x00000007) – недопустимые аргументы.
  • CKR_NO_EVENT (0x00000008) – возвращается, если C_WaitForSlotEvent вызван в режиме без блокировки и новых событий слота нет.
  • CKR_CANT_LOCK (0x0000000A) – невозможно использовать разделение ресурсов.
  • CKR_ATTRIBUTE_READ_ONLY (0x00000010) – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
  • CKR_ATTRIBUTE_SENSITIVE (0x00000011) – запрашиваемый атрибут недоступен для чтения.
  • CKR_ATTRIBUTE_TYPE_INVALID (0x00000012) – недопустимый тип атрибута.
  • CKR_DEVICE_ERROR (0x00000030) – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY (0x00000031) – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED (0x00000032) – токен был изъят из слота.
  • CKR_ENCRYPTED_DATA_LEN_RANGE (0x00000041) – недопустимый размер зашифрованных данных.
  • CKR_FUNCTION_NOT_SUPPORTED (0x00000054) – вызванная функция не поддерживается библиотекой Cryptoki.
  • CKR_KEY_HANDLE_INVALID (0x00000060) – недопустимый дескриптор ключа.
  • CKR_KEY_SIZE_RANGE (0x00000062) – размер ключа лежит за пределами, поддерживаемыми библиотекой Cryptoki.
  • CKR_KEY_TYPE_INCONSISTENT (0x00000063) – данный ключ невозможно использовать с указанным механизмом.
  • CKR_KEY_FUNCTION_NOT_PERMITTED (0x00000068) – атрибуты ключа не позволяют его использование данным образом.
  • CKR_KEY_NOT_WRAPPABLE (0x00000069) – библиотека Cryptoki не может экспортировать данный ключ.
  • CKR_MECHANISM_INVALID (0x00000070) – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID (0x00000071) – недопустимый параметр механизма.
  • CKR_OBJECT_HANDLE_INVALID (0x00000082) – недопустимый дескриптор объекта.
  • CKR_OPERATION_ACTIVE (0x00000090) – на устройстве уже есть активная операция, что не позволяет начать новую операцию.
  • CKR_OPERATION_NOT_INITIALIZED (0x00000091) – в указанном сеансе нет активной операции данного типа.
  • CKR_PIN_INCORRECT (0x000000A0) – неверный PIN-код.
  • CKR_PIN_INVALID (0x000000A1) – недопустимый PIN-код.
  • CKR_PIN_LEN_RANGE (0x000000A2) – недопустимый размер PIN-кода.
  • CKR_PIN_LOCKED (0x000000A4) – указанный PIN-код заблокирован и не может быть использован.
  • CKR_SESSION_CLOSED (0x000000B0) – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_COUNT (0x000000B1) – открыто слишком большое количество сеансов.
  • CKR_SESSION_HANDLE_INVALID (0x000000B3) – недопустимый дескриптор сеанса.
  • CKR_SESSION_PARALLEL_NOT_SUPPORTED (0x000000B4) – данный токен не поддерживает параллельные сеансы.
  • CKR_SESSION_EXISTS (0x000000B6) – сеанс с данным токеном уже существует, следовательно токен не может быть инициализирован.
  • CKR_SESSION_READ_ONLY_EXISTS (0x000000B7) – сеанс на чтение уже открыт и администратор не может быть залогинен.
  • CKR_SESSION_READ_WRITE_SO_EXISTS (0x000000B8) – сеанс чтения/записи уже открыт, администратор не имеет возможности залогиниться.
  • CKR_SIGNATURE_INVALID (0x000000C0) – недопустимая подпись.
  • CKR_SIGNATURE_LEN_RANGE (0x000000C1) – недопустимый размер подписи.
  • CKR_TEMPLATE_INCOMPLETE (0x000000D0) – шаблон, указанный для создания объекта, неполон.
  • CKR_TEMPLATE_INCONSISTENT (0x000000D1) – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
  • CKR_TOKEN_NOT_PRESENT (0x000000E0) – в слоте отсутствует токен.
  • CKR_TOKEN_NOT_RECOGNIZED (0x000000E1) – токен не поддерживается.
  • CKR_TOKEN_WRITE_PROTECTED (0x000000E2) – данный токен защищен от записи.
  • CKR_USER_ALREADY_LOGGED_IN (0x00000100) – пользователь уже залогинен.
  • CKR_USER_NOT_LOGGED_IN (0x00000101) – действие не может быть выполнено, т.к. пользователь не залогинен.
  • CKR_USER_PIN_NOT_INITIALIZED (0x00000102) – PIN-код пользователя не инициализирован (см. C_InitPIN()).
  • CKR_USER_TYPE_INVALID (0x00000103) – недопустимый тип пользователя.
  • CKR_USER_ANOTHER_ALREADY_LOGGED_IN (0x00000104) – указанный пользователь не может быть залогинен в данном сеансе, так как другой пользователь уже залогинен в нем.
  • CKR_BUFFER_TOO_SMALL (0x00000150) – вывод функции слишком велик для предоставленного буфера.
  • CKR_INFORMATION_SENSITIVE (0x00000170) – запрашиваемый объект недоступен для чтения.
  • CKR_CRYPTOKI_NOT_INITIALIZED (0x00000190) – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализированна (см. C_Initialize()).
  • CKR_CRYPTOKI_ALREADY_INITIALIZED (0x00000191) – библиотека Cryptoki уже была инициализированна вызовом C_Initialize() и не была закрыта соответствующим вызовом C_Finalize().
  • CKR_FUNCTION_REJECTED (0x00000200) – запрос на подпись отклонен пользователем.

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

Список поддерживаемых механизмов и их идентификаторов для библиотеки PKCS#11.

Совет

Отдельный список поддерживаемых механизмов для каждой конкретной функции доступен в ее описании.

Для апплета Криптотокен поддерживаются следующие механизмы шифрования:

  • CKM_GOSTR34100x00001201;
  • CKM_GOSTR3410_KEY_PAIR_GEN0x00001200;
  • CKM_GOSTR3410_WITH_GOSTR34110x00001202;
  • CKM_GOSTR3410_DERIVE0x00001204;
  • CKM_GOSTR34110x00001210;
  • CKM_GOST281470x00001222;
  • CKM_GOST28147_ECB0x00001221;
  • CKM_GOST28147_KEY_WRAP0x00001224;
  • CKM_GOST28147_KEY_GEN0x00001220;
  • CKM_TLS_GOST_MASTER_KEY_DERIVE(NSSCK_VENDOR_PKSC11_RU_TEAM|0x101);
  • CKM_TLS_GOST_KEY_AND_MAC_DERIVE(NSSCK_VENDOR_PKSC11_RU_TEAM|0x102);
  • CKM_TLS_GOST_PRF(NSSCK_VENDOR_PKSC11_RU_TEAM|0x103);
  • CKM_TLS_GOST_PRE_MASTER_KEY_GEN(NSSCK_VENDOR_PKSC11_RU_TEAM|0x104).