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

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

  • Приложение GOST
    • Для GOST версий 2.5.5 и 2.5.9 не поддерживается. Воспользуйтесь функцией 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

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, 2.5.9

Операция не поддерживается.

  • приложение 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

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, 2.5.9

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

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