Функции для работы со слотами и токенами

C_GetSlotList()

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.

Расширенные коды ошибок.

Пример

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

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.

Расширенные коды ошибок.

Пример

к содержанию ↑

C_GetTokenInfo()

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.

Расширенные коды ошибок.

Пример

CK_ULONG ulCount;
CK_SLOT_ID_PTR pSlotList;
CK_SLOT_INFO slotInfo;
CK_TOKEN_INFO tokenInfo;
CK_RV rv;

rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulCount);
if ((rv == CKR_OK) && (ulCount > 0)) {
	pSlotList = (CK_SLOT_ID_PTR)malloc(ulCount*sizeof(CK_SLOT_ID));
	rv = C_GetSlotList(CK_FALSE, pSlotList, &ulCount);
	assert(rv == CKR_OK);
	
	/* Получение информации о первом слоте */
	rv = C_GetSlotInfo(pSlotList[0], &slotInfo);
	assert(rv == CKR_OK);

	/* Получение информации о токене в первом слоте */
	rv = C_GetTokenInfo(pSlotList[0], &tokenInfo);
	if (rv == CKR_TOKEN_NOT_PRESENT) {
		.
		.
	}
	.
	.
	free(pSlotList);
}

к содержанию ↑

C_WaitForSlotEvent()

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.

Пример

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()

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.

Расширенные коды ошибок.

Пример

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()

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.

Расширенные коды ошибок.

Пример

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()

CK_DEFINE_FUNCTION(CK_RV, C_InitToken)(
	CK_SLOT_ID			slotID,
	CK_UTF8CHAR_PTR		pPin,
	CK_ULONG			ulPinLen,
	CK_UTF8CHAR_PTR		pLabel
);

...

Данный стандарт позволяет значению PIN-кода содержать любой корректный UTF8 символ, но производители токена могут накладывать свои ограничения (только цифры?).

Назначение

Функция инициализирует память токена, а именно:

...

1. Если ulPinLen != 0 и pPin != NULL_PTR, то проверяется длина PIN-кода. Если длина не является допустимой, то возвращается значение CKR_ARGUMENTS_BAD. Если длина удовлетворяет условиям проверки, то проверяются права доступа для «CKU_SO» на основании предъявленных pPin и ulPinLen.
2. Если ulPinLen != 0 и pPin == NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
3. Если ulPinLen == 0 и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
4. Если ulPinLen == 0 и pPin == NULL_PTR, то отображается PIN Pad (в текущей реализации: возвращается ошибка CKR_ARGUMENTS_BAD).
5. Если pLabel == NULL_PTR и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.

Возвращаемые значения

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

...

CKR_TOKEN_WRITE_PROTECTED.

Расширенные коды ошибок.

Пример

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()

CK_DEFINE_FUNCTION(CK_RV, C_InitPIN)(
	CK_SESSION_HANDLE	hSession,
	CK_UTF8CHAR_PTR		pPin,
	CK_ULONG			ulPinLen
);

...

Данный стандарт позволяет значению PIN-кода содержать любой корректный UTF8 символ, но производители токена могут накладывать свои ограничения (только цифры?).

Назначение

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

...

Возвращаемые значения

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

...

CKR_USER_NOT_LOGGED_IN.

Расширенные коды ошибок.

Пример

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

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 (Пользователя).

...

Возвращаемые значения

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

...

CKR_TOKEN_WRITE_PROTECTED.

Расширенные коды ошибок.

Пример

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) {
  .
  .
}

к содержанию ↑