Функции для работы со слотами и токенами
Table of Contents | ||||||||
---|---|---|---|---|---|---|---|---|
|
C_GetSlotList()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_GetSlotList)( CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList, CK_ULONG_PTR pulCount ); |
Назначение
Функция позволяет получить список зарегистрированных слотов в системе. Список идентификаторов слотов возвращается в массиве типа CK_SLOT_ID. Параметр tokenPresent указывает, должен ли список включать слоты только с подключенным токенами (CK_TRUE) или все слоты (CK_FALSE); pSlotList указывает на переменную, в которую возвращается количество слотов.
...
Все слоты, переданные C_GetSlotList, должны быть доступны для запросов C_GetSlotInfo в качестве корректных слотов. Слоты, доступные через библиотеку PKCS #11, проверяются все время выполнения C_GetSlotList для прогнозирования длины списка. Если приложение вызывает C_GetSlotList с не-NULL значением pSlotList, и затем пользователь подключает или отключает устройство, изменившийся список слотов будут видим и корректен лишь в том случае, если функция C_GetSlotList будет вызвана снова со значением NULL. Слоты при отключении токенов не удаляются, а помечаются как пустые (tokenPresent == CK_FALSE). Текущее количество слотов при подключении новых токенов может быть увеличено, уменьшение доступно только после вызова C_Finalize.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_HOST_MEMORY.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_ULONG ulSlotCount, ulSlotWithTokenCount; CK_SLOT_ID_PTR pSlotList, pSlotWithTokenList; CK_RV rv; /* Получение списка всех слотов */ rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulSlotCount); if (rv == CKR_OK) { pSlotList = (CK_SLOT_ID_PTR) malloc(ulSlotCount*sizeof(CK_SLOT_ID)); rv = C_GetSlotList(CK_FALSE, pSlotList, &ulSlotCount); if (rv == CKR_OK) { /* Работа со списком всех слотов */ . . } free(pSlotList); } /* Получение списка слотов с подключенными токенами */ pSlotWithTokenList = (CK_SLOT_ID_PTR) malloc(0); ulSlotWithTokenCount = 0; while (1) { rv = C_GetSlotList(CK_TRUE, pSlotWithTokenList, ulSlotWithTokenCount); if (rv != CKR_BUFFER_TOO_SMALL) break; pSlotWithTokenList = realloc(pSlotWithTokenList, ulSlotWithTokenList*sizeof(CK_SLOT_ID)); } if (rv == CKR_OK) { /* Работа со списком слотов с подключенными токенами*/ . . } free(pSlotWithTokenList); |
C_GetSlotInfo
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_GetSlotInfo)( CK_SLOT_ID slotID, CK_SLOT_INFO_PTR pInfo ); |
Назначение
Функция позволяет получить информацию о данном слоте. Информация о слоте возвращается в структуре типа CK_SLOT_INFO. slotID - ID слота, к которому подключен токен, pInfo указывает на переменную, которая получает информацию о слоте.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_SLOT_ID_INVALID.
Расширенные коды ошибок.
Пример
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
C_GetTokenInfo()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_GetTokenInfo)( CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo ); |
Назначение
Функция возвращает указатель на структуру CK_TOKEN_INFO, в которой хранится информация о токене: модель, метка, название компании-производителя и т.д. slotID - ID слота, к которому подключен токен, pInfo указывает на место размещения полученной информации о токене.
...
CKF_SO_PIN_COUNT_LOW
CKF_SO_PIN_TO_BE_CHANGED
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_TOKEN_NOT_RECOGNIZED.
Расширенные коды ошибок.
Пример
Excerpt | |||||
---|---|---|---|---|---|
|
C_WaitForSlotEvent()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_WaitForSlotEvent)( CK_FLAGS flags, CK_SLOT_ID_PTR pSlot, CK_VOID_PTR pReserved ); |
Назначение
Функция отслеживает события, происходящие со слотами системы (подключение или отключение токена). Параметр flags определяет, заблокирован ли вызов C_WaitForSlotEvent (т.е. находится ли функция в режиме ожидания события); pSlot указывает на переменную типа CK_SLOT_ID, получающую ID слота, с которым произошло событие. Для получения подробной информации о событии необходимо вызвать функцию C_GetSlotInfo. Параметр pReserved зарезервирован для следующих версий библиотеки, и для данной версии должен иметь значение NULL_PTR.
...
Если требуется получить все события, то C_WaitForSlotEvent требуется вызвать столько раз, пока очередной вызов не вернет ошибку CKR_NO_EVENT, это указывает на то, что очередь событий пуста и новых больше не приходило.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_HOST_MEMORY,
CKR_NO_EVENT.
Пример
Code Block | ||
---|---|---|
| ||
CK_FLAGS flags = 0; CK_SLOT_ID slotID; CK_SLOT_INFO slotInfo; . . /* Блокировка функции и ожидание события в слоте */ rv = C_WaitForSlotEvent(flags, &slotID, NULL_PTR); assert(rv == CKR_OK); /* Получение информации о состоянии слота */ rv = C_GetSlotInfo(slotID, &slotInfo); assert(rv == CKR_OK); . . |
C_GetMechanismList()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismList)( CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR pMechanismList, CK_ULONG_PTR pulCount ); |
Назначение
Функция позволяет получить список механизмов, поддерживаемых токеном. SlotID - ID слота, к которому подключен токен; pulCount указывает на переменную типа CK_ULONG, куда возвращается количество механизмов. Список механизмов возвращается в структуре типа CK_MECHANISM_TYPE.
...
Различные типы токенов поддерживают разное количество механизмов, более подробная информация доступна в 3.2.6 Механизмы стандарта PKCS#11 и 3.2.7 Механизмы расширения стандарта PKCS#11.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_TOKEN_NOT_RECOGNIZED.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_SLOT_ID slotID; CK_ULONG ulCount; CK_MECHANISM_TYPE_PTR pMechanismList; CK_RV rv; . . rv = C_GetMechanismList(slotID, NULL_PTR, &ulCount); if ((rv == CKR_OK) && (ulCount > 0)) { pMechanismList = (CK_MECHANISM_TYPE_PTR) malloc(ulCount*sizeof(CK_MECHANISM_TYPE)); rv = C_GetMechanismList(slotID, pMechanismList, &ulCount); if (rv == CKR_OK) { . . } free(pMechanismList); } |
C_GetMechanismInfo()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismInfo)( CK_SLOT_ID slotID, CK_MECHANISM_TYPE type, CK_MECHANISM_INFO_PTR pInfo ); |
Назначение
Функция позволяет получить информацию о данном механизме для данного токена. Информация о механизме возвращается в структуре типа CK_MECHANISM_INFO. slotID - ID слота, к которому подключен токен, type - тип механизма, pInfo указывает на переменную, которая получает информацию о механизме.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_TOKEN_NOT_RECOGNIZED.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_SLOT_ID slotID; CK_MECHANISM_INFO info; CK_RV rv; . . /* Получение информации о механизме CKM_MD5 для данного токена */ rv = C_GetMechanismInfo(slotID, CKM_MD5, &info); if (rv == CKR_OK) { if (info.flags & CKF_DIGEST) { . . } } |
C_InitToken()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_InitToken)( CK_SLOT_ID slotID, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen, CK_UTF8CHAR_PTR pLabel ); |
...
Данный стандарт позволяет значению PIN-кода содержать любой корректный UTF8 символ, но производители токена могут накладывать свои ограничения (только цифры?).
Назначение
Функция инициализирует память токена, а именно:
...
- Если ulPinLen != 0 и pPin != NULL_PTR, то проверяется длина PIN-кода. Если длина не является допустимой, то возвращается значение CKR_ARGUMENTS_BAD. Если длина удовлетворяет условиям проверки, то проверяются права доступа для «CKU_SO» на основании предъявленных pPin и ulPinLen.
- Если ulPinLen != 0 и pPin == NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
- Если ulPinLen == 0 и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
- Если ulPinLen == 0 и pPin == NULL_PTR, то отображается PIN Pad (в текущей реализации: возвращается ошибка CKR_ARGUMENTS_BAD).
- Если pLabel == NULL_PTR и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_TOKEN_WRITE_PROTECTED.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_SLOT_ID slotID; CK_UTF8CHAR_PTR pin = "MyPIN"; CK_UTF8CHAR label[32]; CK_RV rv; . . memset(label, ' ', sizeof(label)); memcpy(label, "My first token", strlen("My first token")); rv = C_InitToken(slotID, pin, strlen(pin), label); if (rv == CKR_OK) { . . } |
C_InitPIN()
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_InitPIN)( CK_SESSION_HANDLE hSession, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen ); |
...
Данный стандарт позволяет значению PIN-кода содержать любой корректный UTF8 символ, но производители токена могут накладывать свои ограничения (только цифры?).
Назначение
Функция производит инициализацию PIN-кода Пользователя токена.
...
Note |
---|
При форматировании устройств Рутокен из Rutoken Control Panel можно задать политику смены PIN-кода пользователя – «PIN-код пользователя может менять только пользователь». Стандарт PKCS#11 не предполагает такой политики смены PIN-кода пользователя, поэтому при попытке инициализации PIN-кода будет возвращена ошибка CKR_DEVICE_ERROR. Для инициализации токена с возможность задать политику смены PIN-кода следует использовать функцию C_EX_InitToken из расширения стандарта PKCS #11. |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_USER_NOT_LOGGED_IN.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_SESSION_HANDLE hSession; CK_UTF8CHAR newPin[]= {"NewPIN"}; CK_RV rv; rv = C_InitPIN(hSession, newPin, sizeof(newPin)-1); if (rv == CKR_OK) { . . } |
C_SetPIN
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_SetPIN)( CK_SESSION_HANDLE hSession, CK_UTF8CHAR_PTR pOldPin, CK_ULONG ulOldLen, CK_UTF8CHAR_PTR pNewPin, CK_ULONG ulNewLen ); |
...
Данный стандарт позволяет значению PIN-кода содержать любой корректный UTF8 символ, но производители токена могут накладывать свои ограничения (только цифры?).
Назначение
Функция изменяет PIN-код пользователя, выполнившего авторизацию на токене. Если авторизация не выполнена, то функция производит смену PIN-кода CKU_USER (Пользователя).
...
Note |
---|
При форматировании устройств Рутокен из Rutoken Control Panel можно задать политику смены PIN-кода пользователя – «PIN-код пользователя может менять только пользователь». Стандарт PKCS#11 не предполагает такой политики смены PIN-кода пользователя, поэтому при попытке смены PIN-кода будет возвращена ошибка CKR_DEVICE_ERROR. Для инициализации токена с возможность задать политику смены PIN-кода следует использовать функцию C_EX_InitToken из расширения стандарта PKCS #11. |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_TOKEN_WRITE_PROTECTED.
Расширенные коды ошибок.
Пример
Code Block | ||
---|---|---|
| ||
CK_SESSION_HANDLE hSession; CK_UTF8CHAR oldPin[] = {"OldPIN"}; CK_UTF8CHAR newPin[] = {"NewPIN"}; CK_RV rv; rv = C_SetPIN(hSession, oldPin, sizeof(oldPin), newPin, sizeof(newPin)); if (rv == CKR_OK) { . . } |