Навигация

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

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

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

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

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

CK_RV C_GetMechanismList(CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR pMechanismList, 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

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

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) текущее значение метки сохраняется.

Инициализирует поддерживаемые апплеты и устанавливает метки токена.

  • Криптотокен

    Процесс инициализации предполагает удаление всех объектов, за исключением информации о ДСЧ. При этом:

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

  • Криптотокен 2 ЭП

    Предупреждение

    Согласно правилам пользования сертифицированного устройства JaCarta-2 ГОСТ данная операция должна выполняться с использованием ПО «АРМ администратора безопасности JaCarta-2 ГОСТ».
    Для облегчения процесса интеграции JaCarta-2 ГОСТ в прикладное ПО в ходе работ по разработке и тестированию допускается использовать облегчённую версию этого АРМа – «АРМ разработчика JaCarta-2 ГОСТ», входящего в состав комплекта разработчика JaCarta-2 SDK.

  • Laser

    Для устройств модели JXXX v2.0 операция может выполняться в режимах администратора и гостя. Для всех остальных – только в режиме администратора. Процесс инициализации включает удаление всех объектов и последующую персонализацию апплета согласно установленным настройкам. При этом значения PIN-кодов администратора и пользователя устанавливаются на заданные. Если настройки не были установлены, то используются настройки по умолчанию:

    • PIN-код администратора – 00000000,
    • PIN-код пользователя – 11111111.

    Примечание

    Можно произвести полную очистку содержимого смарт-карты/токена, если в качестве значения PIN-кода администратора передать NULL_PTR, а его длину указать как ноль.

  • Datastore

    Операция доступна, если для апплета инициализирован 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

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

Особенности апплетов:

  • Криптотокен

    По умолчанию PIN-кода пользователя не установлен. Операция доступна, если для апплета не инициализирован PIN-код пользователя. При использовании Антифрод-терминала функция запрашивает PIN-код пользователя с подтверждением на клавиатуре терминала (в этом случае функция вызывается с любым значением параметра pPin).

    Длина PIN-кода – от 6 до 32 символов.

  • Криптотокен 2 ЭП

    Предупреждение

    Согласно правилам пользования сертифицированного устройства JaCarta-2 ГОСТ данная операция должна выполняться с использованием ПО «АРМ администратора безопасности JaCarta-2 ГОСТ».
    Для облегчения процесса интеграции JaCarta-2 ГОСТ в прикладное ПО в ходе работ по разработке и тестированию допускается использовать облегчённую версию этого АРМа – «АРМ разработчика JaCarta-2 ГОСТ», входящего в состав комплекта разработчика JaCarta-2 SDK.

  • Laser

    По умолчанию для PIN-кода пользователя установлено значение 11111111. Операция доступна всегда, при её выполнении изменяется текущий PIN-код пользователя.

    Длина PIN-кода – от 4 до 16 символов.

  • Datastore

    По умолчанию для PIN-кода пользователя установлено значение 1234567890. Операция доступна, если для апплета инициализирован 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

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

Особенности апплетов:

  • Криптотокен

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

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

    При работе апплета Криптотокен с использованием Антифрод-терминала для смены PIN-кода (как пользователя, так и администратора) требуется ввести на терминале текущее значение PIN-кода и новое значение. При этом для подтверждения нового значения PIN-кода запрашивается его повторный ввод.

  • Криптотокен 2 ЭП

    Функция меняет PIN-коды пользователя и подписи.

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

    Смена ключа администратора безопасности возможна с помощью ПО «АРМ администратора безопасности JaCarta-2 ГОСТ» или «АРМ разработчика JaCarta-2 ГОСТ».

  • Laser

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

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

  • Datastore

    Функция меняет 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 – данный токен защищен от записи.

Совет

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

Оглавление