Перейти к содержимому
Аладдин Р.Д.Аладдин Р.Д.Аладдин Р.Д.

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

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

C_GetSlotList

Заголовок раздела «C_GetSlotList»

CK_RV C_GetSlotList(CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList, CK_ULONG_PTR pulCount) Параметры:

  • tokenPresent (in) – определяет, что возвращаемый список содержит только слоты с подключенными токенами/ридерами со смарт-картами (CK_TRUE) или все слоты, в т. ч. подключенные ридеры без смарт-карт (CK_FALSE).
  • pSlotList (out) – массив слотов.
  • pulCount (in/out) – указатель на переменную типа CK_ULONG для записи количества слотов. Функция используется для получения списка слотов в системе. При этом возвращает список только слотов с поддерживаемыми апплетами. Работа с данной функцией осуществляется в два шага:
  1. Если pSlotList == NULL_PTR – функция возвращает количество слотов в pulCount.
  2. Если pSlotList != NULL_PTR – pulCount должен содержать размер (в элементах CK_SLOT_ID) буфера, указывающего на pSlotList. Если размер буфера достаточен, список слотов возвращается через pSlotList. Примечание: Поскольку в библиотеке всегда ровно 32 слота, подключение или отключение аппаратных устройств не влияет на список слотов, который функция C_GetSlotList записывает в массив CK_SLOT_ID, когда первый аргумент этой функции – tokenPresent – принимает значение CK_FALSE. Обратите внимание, что на каждый апплет выделятся отдельный слот, поэтому одному токену может соответствовать несколько слотов. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно. Совет: Полный список ошибок см. в приложении.

C_GetSlotInfo

Заголовок раздела «C_GetSlotInfo»

CK_RV C_GetSlotInfo(CK_SLOT_ID * slotID*, CK_SLOT_INFO_PTR pInfo) Параметры:

  • slotID (in) – идентификатор слота.
  • pInfo (out) – указатель на массив байт для записи информации о слоте. Получает информацию о заданном слоте. Согласно стандарту PKCS #11 функция C_GetSlotInfo записывает сведения о подключённом устройстве в структуру типа CK_SLOT_INFO. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно. Совет: Полный список ошибок см. в приложении.

C_GetTokenInfo

Заголовок раздела «C_GetTokenInfo»

CK_RV C_GetTokenInfo(CK_SLOT_ID * slotID*, CK_TOKEN_INFO_PTR * pInfo*) Параметры:

  • slotID (in) – идентификатор токена.
  • pInfo (out) – указатель на информацию об апплете. Возвращает указатель на структуру CK_TOKEN_INFO с информацией об апплете, соответствующем заданному слоту. В случае использования Антифрод-терминала возвращает значение флага CKF_PROTECTED_AUTHENTICATION_PATH. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат:
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_SLOT_ID_INVALID – недопустимый идентификатор слота.
  • CKR_TOKEN_NOT_PRESENT – в слоте отсутствует токен.
  • CKR_TOKEN_NOT_RECOGNIZED – токен не поддерживается.
  • CKR_ARGUMENTS_BAD – недопустимые аргументы. Совет: Полный список ошибок см. в приложении.

C_WaitForSlotEvent

Заголовок раздела «C_WaitForSlotEvent»

CK_RV C_WaitForSlotEvent(CK_FLAGS * flags*, CK_SLOT_ID_PTR * pSlot*, CK_VOID_PTR * pReserved*) Параметры:

  • flags (in) – флаги. На данный момент поддерживается только флаг CKF_DONT_BLOCK, который определяет, блокируется ли вызов C_WaitForSlotEvent.
  • pSlot (in) – указывает на объект, в который можно записать идентификатор слота.
  • pReserved (in) – зарезервирован для будущих версий. Для этой версии должен быть равен NULL_PTR. Отслеживает отключение и подключение устройств. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_NO_EVENT – возвращается, если C_WaitForSlotEvent вызвана в неблокирующемся режиме и новых событий слота нет.
  • CKR_OK – функция выполнена успешно. Совет: Полный список ошибок см. в приложении.

C_GetMechanismList

Заголовок раздела «C_GetMechanismList»

CK_RV C_GetMechanismList(CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR MechanismList, CK_ULONG_PTR pulCount) Параметры:

  • slotID (in) – идентификатор слота.
  • pMechanismList (out) – список механизмов.
  • pulCount (in/out) – указатель на переменную типа CK_ULONG для записи количества слотов. Получает список механизмов, поддерживаемых токеном. Работа с данной функцией осуществляется в два шага:
  1. Если pMechanismList == NULL_PTR – функция возвращает количество механизмов в pulCount.
  2. Если pMechanismList != NULL_PTR – pulCount должен содержать размер (в элементах CK_MECHANISM_TYPE) буфера, указывающего на pMechanismList. Если размер буфера достаточен, список слотов возвращается через pMechanismList. Функция C_GetMechanismList записывает в массив список доступных механизмов. Списки механизмов для поддерживаемых апплетов смотри в приложении. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_SLOT_ID_INVALID – недопустимый идентификатор слота.
  • CKR_TOKEN_NOT_PRESENT – в слоте отсутствует токен.
  • CKR_TOKEN_NOT_RECOGNIZED – токен не поддерживается. Совет: Полный список ошибок см. в приложении.

C_GetMechanismInfo

Заголовок раздела «C_GetMechanismInfo»

CK_RV C_GetMechanismInfo(CK_SLOT_ID slotID, CK_MECHANISM_TYPE type, CK_MECHANISM_INFO_PTR pInfo) Параметры:

  • slotID (in) – идентификатор слота.
  • type (in) – тип механизма.
  • pInfo (out) – указатель на объект для записи информации о механизме. Получает информацию о заданном механизме. Запускается в режимах:
  • Администратор;
  • Пользователь;
  • Гость. Результат::
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_OK – функция выполнена успешно.
  • CKR_SLOT_ID_INVALID – недопустимый идентификатор слота.
  • CKR_TOKEN_NOT_PRESENT – в слоте отсутствует токен.
  • CKR_TOKEN_NOT_RECOGNIZED – токен не поддерживается. Совет: Полный список ошибок см. в приложении.

C_InitToken

Заголовок раздела «C_InitToken»

CK_RV C_InitToken(CK_SLOT_ID slotID, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen, CK_UTF8CHAR_PTR pLabel) Параметры:

  • slotID (in) – идентификатор слота.

  • pPin (in) – указатель на PIN-код администратора.

  • ulPinLen (in) – длина PIN-кода в байтах.

  • pLabel (in) – указатель на метку токена. При указании нулевой метки токена (NULL_PTR) текущее значение метки сохраняется. Инициализирует поддерживаемые приложения и устанавливает метки.

  • Приложение GOST

    • Для GOST версий 2.5.5 не поддерживается. Воспользуйтесь функцией JC_KT2_InitToken
    • Для GOST версии 2.5.13 Функция работает стандартно.

  • Приложение PKI Процесс инициализации включает удаление всех объектов и последующее создание файловой системы в соответствии с заданными параметрами. Если токен не инициализирован (например, новый с завода), параметр pPin становится первоначальным значением ПИН-кода Администратора. Если токен уже инициализирован, параметр pPin служит для аутентификации Администратора при выполнении операции переинициализации. Примечание Текущие настройки инициализации можно получить с помощью функции JC_PKI_GetComplexity(), а задать — с помощью функции JC_PKI_SetComplexity().

  • Приложение LT Операция доступна, если для апплета инициализирован PUK-код пользователя (PIN-код администратора). Процесс инициализации предполагает удаление всех объектов. При этом:

  • значение PIN-кода администратора остаётся прежним,

    • значение PIN-кода пользователя удаляется. Запускается в режимах:

  • Администратор

  • Гость Результат:

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.

  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).

  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.

  • CKR_DEVICE_REMOVED – токен был изъят из слота.

  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.

  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.

  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.

  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.

  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.

  • CKR_OK – функция выполнена успешно.

  • CKR_PIN_LOCKED – указанный PIN-код заблокирован и не может быть использован.

  • CKR_SESSION_EXISTS – сеанс с данным токеном уже существует, следовательно, токен не может быть инициализирован.

  • CKR_SLOT_ID_INVALID – недопустимый идентификатор слота.

  • CKR_PIN_INCORRECT – неверный PIN-код.

  • CKR_TOKEN_NOT_PRESENT – в слоте отсутствует токен.

  • CKR_TOKEN_NOT_RECOGNIZED – токен не поддерживается.

  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи. Совет: Полный список ошибок см. в приложении.

C_InitPIN

Заголовок раздела «C_InitPIN»

CK_RV C_InitPIN(CK_SESSION_HANDLE * hSession*, CK_UTF8CHAR_PTR * pPin*, CK_ULONG * ulPinLen*) Параметры:

  • hSession (in) – дескриптор сеанса.
  • pPin (in) – новый PIN-код пользователя.
  • ulPinLen (in) – длина нового PIN-кода пользователя в байтах. Инициализирует значение PIN-кода пользователя. PIN-код может содержать символы в кодировке UTF-8 из следующего набора:
  • Буквы: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z А Б В Г Д Е Ё Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ъ Ы Ь Э Ю Я а б в г д е ё ж з и й к л м н о п р с т у ф х ц ч ш щ ъ ы ь э ю я
  • Цифры: 0 1 2 3 4 5 6 7 8 9
  • Спец. символы: ! “ # % & ‘ ( ) * + , - . / : ; < = > ? [ \ ] ^ _ { | } ~ Особенности приложений:
  • приложение GOST версий 2.5.5 Операция не поддерживается.
  • приложение GOST версии 2.5.13 Операция поддерживается при наличии соответствующего полномочия Администратора. Длина PIN-кода – от 4 до 32 символов
  • приложение PKI Операция доступна всегда. Длина PIN-кода – от 4 до 16 символов.
  • приложение LT Операция доступна, если для апплета инициализирован PUK-код пользователя (PIN-код администратора) и не инициализирован PIN-код пользователя. Длина PIN-кода – от 6 до 32 символов. Запускается в режимах:
  • Администратор.

Результат:

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

C_SetPIN

Заголовок раздела «C_SetPIN»

CK_RV C_SetPIN(CK_SESSION_HANDLE * hSession*, CK_UTF8CHAR_PTR * pOldPin*, CK_ULONG * ulOldLen*, CK_UTF8CHAR_PTR * pNewPin*, CK_ULONG * ulNewLen*) Параметры:

  • hSession (in) – дескриптор сеанса.

  • pOldPin (in) – старый PIN-код.

  • ulOldLen (in) – длина старого PIN-кода в байтах.

  • pNewPin (in) – новый PIN-код.

  • ulNewLen (in) – длина нового PIN-кода в байтах. Меняет PIN-код пользователя/администратора/подписи. PIN-код пользователя должен быть предварительно инициализирован (см. C_InitPIN()). PIN-код может содержать символы в кодировке UTF-8 из следующего набора:

  • Буквы: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z А Б В Г Д Е Ё Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ъ Ы Ь Э Ю Я а б в г д е ё ж з и й к л м н о п р с т у ф х ц ч ш щ ъ ы ь э ю я

  • Цифры: 0 1 2 3 4 5 6 7 8 9

  • Спец. символы: ! “ # % & ‘ ( ) * + , - . / : ; < = > ? [ \ ] ^ _ { | } ~ Особенности апплетов:

  • Приложение GOST версий 2.5.5

    • Функция меняет PIN-коды пользователя и подписи.
    • Длина PIN-кодов пользователя/подписи – от 6 до 32 символов.

  • Приложение GOST версии 2.5.13

    • Функция меняет PIN-коды пользователя, подписи и администратора.
    • Длина PIN-кодов пользователя/подписи – от 6 до 32 символов.

  • Приложение PKI

    • Функция меняет PIN-коды пользователя и администратора.
    • Длина PIN-кодов пользователя/администратора – от 4 до 16 символов.

  • Приложение LT

    • Функция меняет PIN-коды пользователя и администратора.
    • Длина PIN-кодов пользователя/администратора – от 6 до 32 символов. Запускается в режимах:

  • Администратор

  • Пользователь Результат:

  • CKR_ARGUMENTS_BAD – недопустимые аргументы.

  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).

  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.

  • CKR_DEVICE_REMOVED – токен был изъят из слота.

  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.

  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.

  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.

  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.

  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.

  • CKR_OK – функция выполнена успешно.

  • CKR_PIN_INVALID – недопустимый PIN-код.

  • CKR_PIN_LEN_RANGE – недопустимый размер PIN-кода.

  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.

  • CKR_PIN_LOCKED – указанный PIN-код заблокирован и не может быть использован.

  • CKR_SLOT_ID_INVALID – недопустимый идентификатор слота.

  • CKR_TOKEN_NOT_PRESENT – в слоте отсутствует токен.

  • CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.

  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.

  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

  • CKR_TOKEN_NOT_RECOGNIZED – токен не поддерживается.

  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи. Совет: Полный список ошибок см. в приложении.