Функции управления объектами

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

C_CreateObject

CK_RV C_CreateObject(CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phObject) Параметры:

hSession (in) – дескриптор сеанса.
pTemplate (in) – указатель на шаблон объекта.
ulCount (in) – количество атрибутов в шаблоне.
phObject (out) – указатель на объект, получающий дескриптор нового объекта. Создает объект с заданными атрибутами. Объекты создаются на токене, либо в памяти Единой библиотеки (например, временные объекты). Подробную информацию по работе с объектами для каждого апплета смотрите в приложении. Запускается в режимах:

Для Криптотокен®, Laser и Datastore:

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

Для Криптотокен 2 ЭП:

Пользователь – если создавались объекты CKO_PUBLIC_KEY или CKO_SECRET_KEY с атрибутом CKA_TOKEN равном CK_FALSE.

Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_DOMAIN_PARAMS_INVALID – недопустимые или неподдерживаемые параметры домена.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OK – функция выполнена успешно.
CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
CKR_TEMPLATE_INCOMPLETE – шаблон, указанный для создания объекта, неполон.
CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен. Совет: Полный список ошибок см. в приложении.

C_DestroyObject

CK_RV C_DestroyObject(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject) Параметры:

hSession (in) – дескриптор сеанса.
hObject (in) – дескриптор объекта. Удаляет объект с токена или из памяти ЕБ. Запускается в режимах:
Пользователь.

Результат:

CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OBJECT_HANDLE_INVALID – недопустимый дескриптор объекта.
CKR_OK – функция выполнена успешно.
CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи. Совет: Полный список ошибок см. в приложении.

C_GetAttributeValue

CK_RV C_GetAttributeValue(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) Параметры:

hSession (in) – дескриптор сеанса.
hObject (in) – дескриптор объекта.
pTemplate (in/out) – указатель на шаблон объекта.
ulCount (in) – количество атрибутов в шаблоне. Получает значение одного или нескольких атрибутов для указанного объекта. Запускается в режимах:
Администратор;
Пользователь;
Гость.

Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_ATTRIBUTE_SENSITIVE – запрашиваемый атрибут недоступен для чтения.
CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OBJECT_HANDLE_INVALID – недопустимый дескриптор объекта.
CKR_OK – функция выполнена успешно.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса. Совет: Полный список ошибок см. в приложении.

C_SetAttributeValue

CK_RV C_SetAttributeValue(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) Параметры:

hSession (in) – дескриптор сеанса.
hObject (in) – дескриптор объекта.
pTemplate (in) – указатель на шаблон объекта.
ulCount (in) – количество атрибутов в шаблоне. Устанавливает значение одного или нескольких атрибутов для указанного объекта. Примечание: Значение атрибута CKA_VALUE должно быть представлено в формате от младшего к старшему (little endian).

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

Результат:

CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OBJECT_HANDLE_INVALID – недопустимый дескриптор объекта.
CKR_OK – функция выполнена успешно.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен. Совет: Полный список ошибок см. в приложении.

C_FindObjectsInit

CK_RV C_FindObjectsInit(CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) Параметры:

hSession (in) – дескриптор сеанса.
pTemplate (in) – указатель на шаблон объекта.
ulCount (in) – количество атрибутов в шаблоне. Инициализирует поиск объектов, которые совпадают с заданным шаблоном. Запускается в режимах:
Администратор;
Пользователь;
Гость. См. также: C_FindObjects() и C_FindObjectsFinal(). Результат:
CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OK – функция выполнена успешно.
CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет начать новую операцию.
CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса. Совет: Полный список ошибок см. в приложении.

C_FindObjects

CK_RV C_FindObjects(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE_PTR phObject, CK_ULONG ulMaxObjectCount, CK_ULONG_PTR pulObjectCount) Параметры:

hSession (in) – дескриптор сеанса.
phObject (out) – указатель, получающий дескрипторы найденных объектов.
ulMaxObjectCount (in) – максимальное кол-во дескрипторов объектов, которые необходимо вернуть.
pulObjectCount (out) – указатель, получающий количество найденных объектов. Ищет объекты, которые совпадают с заданным шаблоном. Запускается в режимах:
Администратор;
Пользователь;
Гость. См. также: C_FindObjectsInit() и C_FindObjectsFinal(). Результат:
CKR_ARGUMENTS_BAD – недопустимые аргументы.
CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OK – функция выполнена успешно.
CKR_OPERATION_NOT_INITIALIZED – в указанном сеансе нет активной операции данного типа.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса. Совет: Полный список ошибок см. в приложении.

C_FindObjectsFinal

CK_RV C_FindObjectsFinal(CK_SESSION_HANDLE hSession) Параметры:

hSession (in) – дескриптор сеанса. Завершает поиск объектов. Запускается в режимах:
Администратор;
Пользователь;
Гость.

См. также: C_FindObjectsInit() и C_FindObjects().

Результат:

CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
CKR_DEVICE_REMOVED – токен был изъят из слота.
CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
CKR_OK – функция выполнена успешно.
CKR_OPERATION_NOT_INITIALIZED – в указанном сеансе нет активной операции данного типа.
CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса. Совет: Полный список ошибок см. в приложении.

Пример

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

Пример поиска объектов на языке C:

// задаем шаблон поиска сертификата
CK_ATTRIBUTE certSearchAttribs[] =
{
  { CKA_CLASS, &certClass, sizeof(certClass) },                     // тип объекта
  { CKA_TOKEN, &bTrue, sizeof(bTrue) },                             // объект на токене
  { CKA_LABEL, (CK_VOID_PTR)labelCert.c_str(), labelCert.size() },  // метка объекта
};

CK_OBJECT_HANDLE certHandle = 0;;
CK_ULONG certObjCount = 0;

// начинаем поиск объект с заданными атрибутами
rv = C_FindObjectsInit(session,
                       certSearchAttribs,
                       sizeof(certSearchAttribs) / sizeof(CK_ATTRIBUTE));
if (rv != CKR_OK)
{
  PrintError("C_FindObjectsInit", rv);
  return;
}

// нам нужен один объект
rv = C_FindObjects(session, &certHandle, 1, &certObjCount);
if (rv != CKR_OK || ulObjectCount == 0)
{
  PrintError("C_FindObjects", rv);
}

// завершаем поиск
rv = C_FindObjectsFinal(session);
if (rv != CKR_OK)
{
  PrintError("C_FindObjectsFinal", rv);
  return;
}