Технический портал

`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:

<pre>// задаем шаблон поиска сертификата
CK_ATTRIBUTE certSearchAttribs[] =
{
  { CKA_CLASS, &amp;certClass, sizeof(certClass) },                     // тип объекта
  { CKA_TOKEN, &amp;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(&quot;C_FindObjectsInit&quot;, rv);
  return;
}
 
// нам нужен один объект
rv = C_FindObjects(session, &amp;certHandle, 1, &amp;certObjCount);
if (rv != CKR_OK || ulObjectCount == 0)
{
  PrintError(&quot;C_FindObjects&quot;, rv);
}
 
// завершаем поиск
rv = C_FindObjectsFinal(session);
if (rv != CKR_OK)
{
  PrintError(&quot;C_FindObjectsFinal&quot;, rv);
  return;
}</pre>