Навигация

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

C_CreateObject

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) – указатель на объект, получающий дескриптор нового объекта.

Функция C_CreateObject используется для создания объекта с заданными атрибутами. Объекты создаются на токене, либо в памяти Единой библиотеки (например, временные объекты).

Подробную информацию по работе с объектами для каждого апплета смотрите в приложении.

Примечание

В данной функции предусмотрена компрессия данных. Для осуществления компрессии значение атрибута CKA_COMPRESSED для объекта должно быть CK_TRUE`. Подробнее смотрите в приложении.

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

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

C_DestroyObject(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • hObject (in) – дескриптор объекта.

Функция C_DestroyObject используется для удаления объекта с токена или из памяти ЕБ.

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

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

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) – количество атрибутов в шаблоне.

Получает значение одного или нескольких аттрибутов для указанного объекта.

Примечание

В данной функции предусмотрена компрессия данных. Для осуществления компрессии значение атрибута CKA_COMPRESSED для объекта должно быть CK_TRUE`. Подробнее смотрите в приложении.

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

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

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_COMPRESSED для объекта должно быть CK_TRUE`. Подробнее смотрите в приложении.

Примечание

Значение атрибута CKA_VALUE должно быть представлено в формате от младшего к старшему (little endian).

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

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

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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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_SESSION_HANDLE hSession, CK_OBJECT_HANDLE_PTR phObject, CK_ULONG ulMaxObjectCount, CK_ULONG_PTR pulObjectCount)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • phObject (out) – указатель, получающий дескрипторы найденых объектов.
  • ulMaxObjectCount (in) – максимальное кол-во дескрипторов объектов, которые необходимо вернуть.
  • pulObjectCount (out) – указатель, получающий количество найденных объектов.

C_FindObjects осуществляет поиск объектов, которые совпадают с заданным шаблоном.

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

См.также

C_FindObjectsInit() и C_FindObjectsFinal().

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

Завершает поиск объектов.

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

См.также

C_FindObjectsInit() и C_FindObjects().

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

Совет

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

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

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

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

// задаем шаблон поиска сертификата
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));
assert(rv == CKR_OK);
// нам нужен один объект
rv = C_FindObjects(session, &certHandle, 1, &certObjCount);
if (rv != CKR_OK || ulObjectCount == 0)
   break;
// завершаем поиск
rv = C_FindObjectsFinal(session);
assert(rv == CKR_OK);

Пример поиска объектов на языке Java под ОС Android:

// дескриптор сессии
LongRef session = new LongRef();
// атрибуты для поиска сертификатов
CKA[] certAttribs = new CKA[1];
certAttribs[0] = new CKA(CKA.CLASS, CKO.CERTIFICATE);
// массив указателей на сертификаты
long[] certificates = new long[128];
// количество найденых сертификатов
LongRef certsCount = new LongRef(0);

// инициализация поиска сертификатов
rv = C.FindObjectsInit(session.value, certAttribs);
if(rv != CKR.OK)
{
        throw new CKRException("C_FindObjectsInit", rv);
}

// поиск сертификатов
rv = C.FindObjects(session.value, certificates, certsCount);
if(rv != CKR.OK)
{
        throw new CKRException("C_FindObjects", rv);
}

// завершение операции поиска
rv = C.FindObjectsFinal(session.value);
if(rv != CKR.OK)
{
        throw new CKRException("C_FindObjectsFinal", rv);
}

Оглавление