Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 43 Next »

C_EX_TokenManage

Функции общего назначения

C_EX_GetFunctionListExtended()

Назначение

Функция возвращает список дополнительных функций, расширяющих библиотеку PKCS#11 для работы с Рутокен.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetFunctionListExtended)(
	CK_FUNCTION_LIST_EXTENDED_PTR_PTR	ppFunctionList 
);

Параметры

ppFunctionList[out]указатель на список функций расширения

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

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

Пример

HMODULE hModule;                                                 // дескриптор загруженной библиотеки PKCS #11
CK_FUNCTION_LIST_EXTENDED_PTR pFunctionListEx;                   // указатель на структуру CK_FUNCTION_LIST_EXTENDED, в которой хранится список функций расширения
CK_C_EX_GetFunctionListExtended pfGetFunctionListEx;             // указатель на функцию C_EX_GetFunctionListExtended
CK_RV rv;                                                        // вспомогательная переменная для хранения кода возврата
 
hModule = LoadLibrary("rtPKCS11.dll");                           // получение дескриптора загруженной библиотеки
pfGetFunctionListEx = (CK_C_EX_GetFunctionListExtended)
        GetProcAddress(hModule,"C_EX_GetFunctionListExtended");  // получение адреса функции C_EX_GetFunctionListExtended
if (pfGetFunctionListEx == NULL_PTR)                             // проверка результата
    printf ("Loading library -> Failed \n");
else
    printf ("Loading library -> OK \n");
        
rv = pfGetFunctionListEx(&pFunctionListEx);                      // получение структуры с указателями на функции расширения
if (rv == CKR_OK)                                                // проверка результата
    printf ("Getting extended function list -> OK \n");
else
    printf ("Getting extended function list -> Failed \n");
.
.
FreeLibrary(hModule);                                            // завершение работы с библиотекой

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

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

C_EX_GetTokenInfoExtended()

Назначение

Функция позволяет получить специфическую для устройств Рутокен информацию: класс токена, количество свободной и общей памяти, тип токена, номер протокола и т.д. По сравнению с похожей по назначению стандартной функции C_GetTokenInfo функция расширения предоставляет более полную информацию о токене.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetTokenInfoExtended)(
	CK_SLOT_ID					slotID,
	CK_TOKEN_INFO_EXTENDED_PTR	pInfo
);

Параметры

slotID[in]ID слота, к которому подключен токен
pInfo[out]указатель на структуру CK_TOKEN_INFO_EXTENDED, получающую расширенные данные токена

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_SLOT_ID_INVALID,

CKR_TOKEN_NOT_PRESENT.

Пример

CK_SLOT_ID				slotID;				// идентификатор слота
CK_TOKEN_INFO_EXTENDED  ckTokenInfoEx;		// структура расширенных данных токена
CK_RV 					rv; 				// вспомогательная переменная для хранения кода возврата

.
.
ckTokenInfoEx.ulSizeofThisStructure = sizeof(CK_TOKEN_INFO_EXTENDED);			// размер структуры CK_TOKEN_INFO_EXTENDED
rv = pfGetFunctionListEx -> C_EX_GetTokenInfoExtended(slotID, &ckTokenInfoEx);	// получение расширенной информации о токене		
if (rv == CKR_OK)																// проверка результата
	printf ("Getting Extended Token Info -> OK \n");
else
	printf ("Getting Extended Token Info -> Failed \n");

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

C_EX_InitToken()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_InitToken)(
	CK_SLOT_ID					slotID,
	CK_UTF8CHAR_PTR				pPin,
	CK_ULONG					ulPinLen,
	CK_RUTOKEN_INIT_PARAM_PTR	pInitInfo
);

Параметры

slotID[in]ID слота, к которому подключен токен для инициализации
pPin[in]указатель на PIN-код Администратора
ulPinLen[in]длина PIN-кода Администратора, в байтах
pInitInfo[in]указатель на структуру CK_RUTOKEN_INIT_PARAM, хранящую параметры инициализации

Примечание

Основное отличие функции C_EX_InitToken от похожей по назначению стандартной функции C_InitToken в том, что функция расширения полностью инициализирует память токена, а также предоставляет возможность задать политику смены PIN-кода пользователя, метку произвольной длины, а стандартная функция C_InitToken позволяет инициализировать только память, занятую объектами PKCS#11, и задать метку фиксированной длины.

Все параметры, необходимые для инициализации, передаются в структуре типа CK_RUTOKEN_INIT_PARAM.

Внимание! Для Рутокен S параметры ulMinAdminPinLen и ulMinUserPinLen из структуры CK_RUTOKEN_INIT_PARAM, не могут принимать значение больше 1.

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_CANCELED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_PIN_INCORRECT,

CKR_PIN_LOCKED,

CKR_SESSION_EXISTS,

CKR_SLOT_ID_INVALID,

CKR_TOKEN_NOT_PRESENT.

Пример

static CK_CHAR USER_PIN[] = {'1', '2', '3', '4', '5', '6', '7', '8'};	// PIN-код Пользователя Рутокен по умолчанию
static CK_CHAR SO_PIN[] = {'8', '7', '6', '5', '4', '3', '2', '1'};	 	// PIN-код Администратора Рутокен по умолчанию
CK_FUNCTION_LIST_PTR pFunctionList;										// указатель на структуру CK_FUNCTION_LIST, в которой хранится список стандартных функций
CK_C_EX_GetFunctionList pfGetFunctionList;								// указатель на функцию C_GetFunctionList
CK_SLOT_ID slots[100];													// массив идентификаторов слотов
CK_ULONG ulSlotCount = 100;												// количество идентификаторов слотов в массиве
CK_RUTOKEN_INIT_PARAM ckRtInitParams;									// структура, задающая параметры форматирования токена
CK_RV rv;																// вспомогательная переменная для хранения кода возврата

/* заполнение полей структуры CK_RUTOKEN_INIT_PARAM */
ckRtInitParams.ulSizeofThisStructure = sizeof(CK_RUTOKEN_INIT_PARAM);	// задаем размер структуры
ckRtInitParams.UseRepairMode = 0;										// требуем ввод PIN-кода Администратора (0 - да, режим восстановления выключен, !0 - нет, режим восстановления включен)
ckRtInitParams.pNewAdminPin = SO_PIN;									// задаем новый PIN-код Администратора (минимум (?), максимум 32 байта)
ckRtInitParams.ulNewAdminPinLen = sizeof(SO_PIN);						// указываем длину нового PIN-кода Администратора
ckRtInitParams.pNewUserPin = USER_PIN;									// задаем новый PIN-код Пользователя (минимум (?), максимум 32 байта)
ckRtInitParams.ulNewUserPinLen = sizeof (USER_PIN);						// указываем длину нового PIN-кода Пользователя
ckRtInitParams.ChangeUserPINPolicy = TOKEN_FLAGS_ADMIN_CHANGE_USER_PIN 
									| TOKEN_FLAGS_USER_CHANGE_USER_PIN; // задаем политику смены PIN-кода пользователя: Администратором и Пользователем
ckRtInitParams.ulMinAdminPinLen = 6;									// задаем минимальную длину PIN-кода Администратора (минимум 6, максимум 32 байта)
ckRtInitParams.ulMinUserPinLen = 6;										// задаем минимальную длину PIN-кода Пользователя (минимум 6, максимум 32 байта)
ckRtInitParams.ulMaxAdminRetryCount = 10;								// задаем максимальное количество попыток доступа к PIN-коду Администратора (минимум 3, максимум 10)
ckRtInitParams.ulMaxUserRetryCount = 10;								// задаем максимальное количество попыток доступа к PIN-коду Пользователя (минимум 1, максимум 10)
ckRtInitParams.pTokenLabel = "Rutoken label";							// задаем метку пользователя
ckRtInitParams.ulLabelLen = 13;											// указываем длину метки пользователя

.
.
pfGetFunctionList = (CK_C_GetFunctionList)GetProcAddress(hModule,"C_GetFunctionList");	//получение списка стандартных функций
pfGetFunctionList(&pFunctionList);

rv = pfGetFunctionList -> C_GetSlotList(CK_TRUE, slots, &ulSlotCount);	// получение списка слотов с подключенными токенами
if (rv == CKR_OK )														// проверка результата
	printf("Getting connected slots list -> OK \n");
else
	printf("Getting connected slots list -> failed \n");
if (ulSlotCount == 0)
	printf("No Rutoken is available");

rv = pfGetFunctionListEx -> 
	C_EX_InitToken(slots[0], SO_PIN, sizeof(SO_PIN), &ckRtInitParams); 	// инициализация токена (считаем, что подключен один токен к первому слоту)
if (rv == CKR_OK)														// проверка результата
	printf("Token initialization -> OK \n");
else
	printf("Token initialization -> failed \n");

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

C_EX_UnblockUserPIN()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_UnblockUserPIN)(
	CK_SESSION_HANDLE hSession
);

Параметры

hSession[in]дескриптор сесии

Примечание

Функция сбрасывает счетчик неверных попыток ввода PIN-кода для CKU_USER. Функция может быть вызвана только из сессии, имеющей статус CKS_RW_SO_FUNCTIONS.

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

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

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_CANCELED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_PIN_INVALID,

CKR_PIN_LEN_RANGE,

CKR_SESSION_CLOSED,

CKR_SESSION_READ_ONLY,

CKR_SESSION_HANDLE_INVALID,

CKR_USER_NOT_LOGGED_IN,

CKR_ARGUMENTS_BAD.

Пример

static CK_CHAR SO_PIN[] = {'8', '7', '6', '5', '4', '3', '2', '1'};	 	// PIN-код Администратора Рутокен по умолчанию
CK_SESSION_HANDLE hSession; 											// дескриптор сессии
CK_SLOT_ID slots[100];													// массив идентификаторов слотов
CK_ULONG ulSlotCount = 100;												// количество идентификаторов слотов в массиве
CK_RV rv;																// вспомогательная переменная для хранения кода возврата

.
.
rv = pfGetFunctionList -> C_OpenSession(	// открытие сессии
	slots[0],								// выбор нулевого слота
	CKF_SERIAL_SESSION | CKF_RW_SESSION),	// флаги для сессии чтение/запись
	0, 										// не используется
	0, 										// не используется
	&hSession); 							// дескриптор сессии
if (rv != CKR_OK)							// проверка результата
	printf("Opening session -> failed \n");
else
	printf("Opening session -> OK \n"); 

rv = pfGetFunctionList -> C_Login(			// получение прав Администратора, необходимых для разблокировки
	hSession, 								// дескриптор сессии
	CKU_SO, 								// пользователь, с правами которого производится авторизация
	SO_PIN, 								// PIN-код указанного пользователя
	sizeof(SO_PIN)); 						// длина PIN-кода
if (rv != CKR_OK)							// проверка результата
	printf("Logining -> failed \n");
else
	printf("Logining -> OK \n"); 

rv = pfGetFunctionListEx -> C_EX_UnblockUserPIN(hSession);	// разблокировка PIN-кода			
if (rv != CKR_OK)							// проверка результата
	printf("Unblocking UserPIN -> failed \n");
else
	printf("Unblocking UserPIN -> OK \n");
.
.
pfGetFunctionList -> C_Logout(hSession);		// выход пользователя
pfGetFunctionList -> C_CloseSession(hSession);	// закрытие сессии

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

C_EX_SetTokenName()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SetTokenName)(
	CK_SESSION_HANDLE       hSession,
	CK_BYTE_PTR             pLabel,
	CK_ULONG                ulLabelLen
);

Параметры

hSession[in]дескриптор сессии
pLabel[in]указатель на буфер, содержащий новую метку токена
ulLabelLen[in]размер буфера с новой меткой токена, в байтах

Примечание

Функция позволяет установить метку токена произвольной длины, в отличии от стандартной функции C_InitToken, которая позволяет устанавливать метку токена фиксированного размера. Функция может быть вызвана только из сессии, имеющей статус CKS_RW_USER_FUNCTIONS.

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_SESSION_READ_ONLY,

CKR_USER_NOT_LOGGED_IN.

Пример

CK_SESSION_HANDLE hSession;					// дескриптор сессии
CK_CHAR ckcNewLabel[100];					// метка длиной 100 символов
CK_RV rv;									// вспомогательная переменная для хранения кода возврата

.
.
pfGetFunctionList -> C_OpenSession(slots[0], CKF_SERIAL_SESSION | CKF_RW_SESSION), 0, 0, &hSession);	// открытие сессии
pfGetFunctionList -> C_Login(hSession, CKU_USER, USER_PIN, sizeof(USER_PIN));							// авторизация  с правами пользователя

strcpy ((char *)ckcNewLabel, "Label is set by C_EX_SetTokenName from rtPKCS11ecp.dll");					// определяем имя метки
rv = pfGetFunctionList  -> C_EX_SetTokenName(hSession, ckcNewLabel, 32);								// задаем метку токена
if (rv != CKR_OK)																						// проверка результата
	printf("Changing of label -> failed \n");
else
	printf("Changing of label -> OK \n");
.
.
pfGetFunctionList -> C_Logout(hSession);																// выход пользователя
pfGetFunctionList -> C_CloseSession(hSession);															// закрытие сессии

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

C_EX_GetTokenName()

Назначение

Функция позволяет получить метку токена произвольной длины. Функция может быть вызвана из любой сессии.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetTokenName)( 
	CK_SESSION_HANDLE       hSession,
	CK_BYTE_PTR             pLabel,
	CK_ULONG_PTR            ulLabelLen
);

Параметры

hSession[in]дескриптор сессии
pLabel[out]указатель на буфер, содержащий метку токена
ulLabelLen[in, out]размер буфера с меткой токена, в байтах

Примечание

Функция позволяет получить метку токена произвольной длины, в отличии от стандартной функции C_GetTokenInfo, которая позволяет получить метку токена фиксированного размера.

Для определения необходимого количества памяти для хранения метки токена, необходимо вызвать функцию C_EX_GetTokenName с параметром pLabel равным NULL_PTR, тогда в параметре pulLabelLen будет возвращен указатель на переменную с требуемым размером буфера.

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_BUFFER_TOO_SMALL.

Пример

CK_BYTE ckLabel[1000];
CK_ULONG ckulLabelLen = 0;

.
.
rv = pfGetFunctionListEx -> C_EX_GetTokenName(hSession, ckLabel, &ckulLabelLen);				// получение метки токена
if (rv != CKR_OK)																				// проверка результата
	printf("Getting name of token -> failed \n");
else
	printf("Getting name of token -> OK \n");

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

C_EX_SetLicense()

Назначение

Функция предназначена для записи данных вендора в токен и позволяет записать лицензию на токен.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SetLicense)(
	CK_SESSION_HANDLE       hSession,
	CK_ULONG                ulLicenseNum,
	CK_BYTE_PTR             pLicense,
	CK_ULONG                ulLicenseLen
);

Параметры

hSession[in]дескриптор сессии
ulLicenseNum[in]идентификатор лицензии. Параметр может принимать одно из двух значений: 1 или 2
pLicense[in]указатель на буфер, содержащий лицензию
ulLicenseLen[in]размер буфера с лицензией, в байтах. Параметр может принимать только одно значение: 72

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_FUNCTION_NOT_SUPPORTED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_SESSION_READ_ONLY,

CKR_USER_NOT_LOGGED_IN.

Примечание

Формат данных (лицензии) определяет вендор, размер ограничивается 72 байтами. Всего может быть до двух лицензий.Функция может быть вызвана только из сессии, имеющей статус CKS_RW_USER_FUNCTIONS или CKS_RW_SO_FUNCTIONS.

При инициализации памяти токена с помощью функций C_InitToken или C_EX_InitToken ранее записанная лицензия удалена не будет.

Пример

Пример использования функции C_EX_SetLicense
CK_ULONG	ckulLicenseNumber = 1; 								// идентификатор лицензии
CK_BYTE		ckbLicense[100];									// массив идентификаторов лицензий
CK_ULONG	ckulLicenseLen = 0;									// длина лицензии

.
.
pfGetFunctionList -> C_OpenSession(slots[0], (CKF_SERIAL_SESSION), 0, 0,&hSession);		// открытие сессии
pfGetFunctionList -> C_Login(hSession, CKU_SO, SO_PIN, sizeof(SO_PIN));					// авторизация с правами Администратора

pfGetFunctionListEx -> 
	C_EX_GetLicense(hSession, ckulLicenseNumber, ckbLicense, &ckulLicenseLen);	// считываем текущую лицензию

for (CK_ULONG ckulIndex=0; ckulIndex < ckulLicenseLen; ckulIndex++)	// новое значение лицензии:
	ckbLicense[ckulIndex] = (72 - ckulIndex);

rv = pfLstEx->C_EX_SetLicense(hSession, ckulLicenseNumber, ckbLicense, ckulLicenseLen); // записываем новое значение лицензии
if (rv != CKR_OK)
	printf("C_EX_SetLicense() -> failed\n");
else 
	printf("C_EX_SetLicense() -> OK\n");
.
.
pfGetFunctionList -> C_Logout(hSession);						// выход пользователя
pfGetFunctionList -> C_CloseSession(hSession);					// закрытие сессии

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

C_EX_GetLicense()

Назначение

Функция позволяет прочитать лицензию, записанную на токен.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetLicense)(
	CK_SESSION_HANDLE       hSession,
	CK_UKONG                ulLicenseNum,
	CK_BYTE_PTR             pLicense,
	CK_ULONG_PTR            pulLicenseLen
);

Параметры

hSession[in]дескриптор сессии
ulLicenseNum[in]идентификатор лицензии. Параметр может принимать одно из двух значений: 1 или 2
pLicense[out]указатель на буфер для получения лицензии
ulLicenseLen[in, out]размер буфера с лицензией, в байтах. Параметр может принимать только одно значение: 72

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_FUNCTION_NOT_SUPPORTED.

Примечание

Функция позволяет прочитать лицензию с токена. Функция может быть вызвана из сессии любого состояния. Длина лицензии может иметь единственное значение 72 байта, либо при передаче pLicense равного NULL_PTR в параметре pulLicenseLen возвращается указатель на длину буфера для требуемой лицензии.

Пример

Пример использования функции C_EX_SetLicense
CK_ULONG	ckulLicenseNumber = 1; 								// идентификатор лицензии
CK_BYTE		ckbLicense[100];									// массив идентификаторов лицензий
CK_ULONG	ckulLicenseLen = 0;									// длина лицензии

.
.
pfGetFunctionList -> C_OpenSession(slots[0], (CKF_SERIAL_SESSION), 0, 0,&hSession);		// открытие сессии

rv = pfGetFunctionListEx -> C_EX_GetLicense(hSession, ckulLicenseNumber, ckbLicense, &ckulLicenseLen);	// считываем текущую лицензию
if (rv != CKR_OK)
	printf("C_EX_GetLicense() -> failed\n");
else 
	printf("C_EX_GetLicense() -> OK\n");
.
.
pfGetFunctionList -> C_CloseSession(hSession);					// закрытие сессии

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

C_EX_SetLocalPIN()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SetLocalPIN)(
	CK_SLOT_ID 			slotID,
	CK_UTF8CHAR_PTR 	pUserPin,      // или pOldLocalPin
	CK_ULONG 			ulUserPinLen,  // или pOldLocalPinLen
	CK_UTF8CHAR_PTR 	pNewLocalPin,
	CK_ULONG 			ulNewLocalPinLen,
	CK_ULONG 			ulLocalID
);

Параметры

slotID[in]

идентификатор слота, к которому подключен токен

pUserPin или pOldLocalPin[in]указатель на текущий PIN-код Пользователя или на текущий локальный PIN-код
ulUserPinLen или pOldLocalPinLen[in]длина текущего PIN-кода Пользователя или длина текущего локального PIN-кода
pNewLocalPin[in]указатель на новый Локальный PIN-код

ulNewLocalPinLen

[in]длина нового Локального PIN-кода

ulLocalID

[in]идентификатор Локального PIN-кода

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

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

Пример

CK_BYTE Pin[] = {'1', '2', '3', '4', '5', '6', '7', '8'};		// текущий PIN-код Пользователя или локальный PIN-код
CK_SLOT_ID slots[100];											// массив идентификаторов слотов

.
.
rv = pfGetFunctionListEx -> C_EX_SetLocalPIN(
	slots[0], 													// считаем, что токен подключен к первому слоту
	Pin, 														// текущий PIN-код Пользователя или текущий локальный PIN-код
	arraysize(Pin),												// длина текущего PIN-кода Пользователя или локального PIN-кода
	"000000000000000000000000000000",							// указатель на новый Локальный PIN-код
	30,															// длина нового Локального PIN-кода
	0x1F														// идентификатор Локального PIN-кода
);
if (rv != CKR_OK)												// проверка результата
	printf("C_EX_SetLocalPIN() -> failed \n");
else
	printf("C_EX_SetLocalPIN() -> OK \n"); 

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

C_EX_TokenManage() 

Назначение

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

 Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_TokenManage)(
  CK_SESSION_HANDLE     hSession,
  CK_ULONG              ulMode,
  CK_VOID_PTR           pValue
);

Параметры

hSession

[in]дескриптор сессии

ulMode

[in]

режим работы функции:

MODE_RESET_CUSTOM_PIN_TO_STANDARD – сбросить кастомизированный PIN-код по-умолчанию на стандартный.
MODE_RESET_PIN_TO_DEFAULT – сброс PIN-кода на PIN-код по-умолчанию
MODE_CHANGE_DEFAULT_PIN – установить кастомизированный PIN-код по-умолчанию.
MODE_FORCE_USER_TO_CHANGE_PIN – установить флаг принудительной смены PIN-кода.

pValue

[in] 
  • при режиме MODE_RESET_CUSTOM_PIN_TO_STANDARD в качестве параметра pValue передается указатель на тип пользователя (CKU_USER или CKU_SO), для которого сбрасывается PIN-код по-умолчанию
  • при режиме MODE_RESET_PIN_TO_DEFAULT в качестве параметра pValue передается указатель на тип пользователя (CKU_USER или CKU_SO или локальные пользователи), для которого сбрасывается PIN-код
  • при режиме MODE_CHANGE_DEFAULT_PIN в качестве параметра pValue передается указатель на структуру CK_VENDOR_PIN_PARAMS:
    typedef struct CK_VENDOR_PIN_PARAMS {
        CK_USER_TYPE userType;
        CK_UTF8CHAR_PTR pPinValue;
        CK_ULONG ulPinLength;
    } CK_VENDOR_PIN_PARAMS;
    userType – тип пользователя, для которого устанавливаем кастомизированный PIN-код (CKU_USER или CKU_SO)
    pPinValue – массив байт содержащий кастомизированный PIN-код по-умолчанию
  • при режиме MODE_FORCE_USER_TO_CHANGE_PIN в качестве параметра pValue передается указатель на тип пользователя (CKU_USER или CKU_SO), которого мы хотим заставить сменить PIN-код:

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

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

CKR_ARGUMENTS_BAD – неправильно переданы параметры функции

CKR_USER_NOT_LOGGED_IN – пользователь SKU_SO не авторизован на токене (режимы)


Мультифункциональная функция

Здесь описаны не все возможные параметры функции. Описание других параметров функции можно найти здесь

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

C_EX_SlotManage

Назначение

Позволяет:

  1. получить расширенную информацию о всех локальных PIN-кодах токена.
  2. получить информацию об установленном флаге принудительной смене PIN-кода

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SlotManage) (
  CK_SLOT_ID slotID,
  CK_ULONG ulMode,
  CK_VOID_PTR pValue
)

Параметры

hSession

[in]дескриптор сессии

ulMode

[in]

режим работы функции:

MODE_GET_LOCAL_PIN_INFO – получение информации о локальных PIN-кодах

MODE_GET_PIN_SET_TO_BE_CHANGED – получение информации об принудительной смене PIN-кода

pValue

[out] 
  • При режиме MODE_GET_LOCAL_PIN_INFO – указатель, на структуру CK_LOCAL_PIN_INFO:
    typedef struct CK_LOCAL_PIN_INFO {
        CK_ULONG ulPinID;
        CK_ULONG ulMinSize;
        CK_ULONG ulMaxSize;
        CK_ULONG ulMaxRetryCount;
        CK_ULONG ulCurrentRetryCount;
        CK_FLAGS flags;
    } CK_LOCAL_PIN_INFO;

    ulPinID – идентификатор локального PIN-кода (входной параметр).
  • При режиме MODE_GET_PIN_SET_TO_BE_CHANGED – указатель тип пользователя (CKU_USER или CKU_SO), для которого хотим узнать установлен ли флаг принудительной смены PIN-кода.

Для режима работы функции MODE_GET_LOCAL_PIN_INFO в pValue возвращается указатель массив структур типа CK_LOCAL_PIN_INFO:

ulPinID

[in]

идентификатор PIN-кода

ulMinSize

[out]

заданная минимальная длина PIN-кода

ulMaxSize

[out] 

заданная максимальная длина PIN-кода

ulMaxRetryCount

[out] заданное максимальное значение счетчика неверных попыток ввода пароля

ulCurrentRetryCount

[out] 

текущее значение счетчика оставшихся попыток ввода пароля:

0 – PIN-код заблокирован

flags

[out] 

информационные флаги:

LOCAL_PIN_FLAGS_NOT_DEFAULT – локальный PIN-код не является PIN-кодом по умолчанию
LOCAL_PIN_FLAGS_FROM_SCREENPIN-код может введен только с экрана

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

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

CKR_PIN_EXPIRED – если PIN-код нужно сменить смене (MODE_GET_PIN_SET_TO_BE_CHANGED).

CKR_ARGUMENTS_BAD – неверно указаны аргументы функции.

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

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

C_EX_GetCertificateInfoText()

Назначение

Функция позволяет получить информацию о сертификате из токена в текстовом виде.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetCertificateInfoText)(
	CK_SESSION_HANDLE	hSession, 
	CK_OBJECT_HANDLE 	hCert,
	CK_CHAR_PTR* 		pInfo, 
	CK_ULONG_PTR 		pulInfoLen
);

Параметры

hSession[in]дескриптор сессии
hCert[in]дескриптор объекта (сертификата)
pInfo[out]указатель на буфер, содержащий текстовую информацию о сертификате
pulInfoLen[out]размер буфера, в байтах

Примечание

Функция может быть вызвана из любого состояния. Так как память для массива выделяется внутри функции, по окончании работы функции pInfo нужно высвободить функцией C_EX_FreeBuffer.

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

C_EX_CreateCSR()

Назначение

Создает запрос на выпуск сертификата в центр сертификации и упаковывает его в формат PKCS#10.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_CreateCSR)(
	CK_SESSION_HANDLE 	hSession,
	CK_OBJECT_HANDLE 	hPublicKey,
	CK_CHAR_PTR 		*dn,
	CK_ULONG 			dnLength,
	CK_BYTE_PTR 		*pCsr,
	CK_ULONG_PTR 		pulCsrLength,
	CK_OBJECT_HANDLE 	hPrivKey,
	CK_CHAR_PTR 		*pAttributes,
	CK_ULONG 			ulAttributesLength,
	CK_CHAR_PTR 		*pExtensions,
	CK_ULONG 			ulExtensionsLength
);

Параметры

hSession[in]дескриптор сессии

hPublicKey

[in]дескриптор открытого ключа для создания сертификата

dn

[in]

уникальное имя – массив строк, где в первой строке располагается тип поля в текстовом формате или идентификатор объекта (CN или «2.5.4.3»). Во второй строке должно находиться значение поля в кодировке UTF8.

Последующие поля передаются аналогично, количество строк должно быть кратно двум

dnLength

[in]количество строк в массиве, на который ссылается параметр dn

pCsr

[in]

указатель на указатель на массив байт, в который будет записан созданный запрос на сертификат

pulCsrLength

[in]указатель на переменную, в которой сохраняется размер массива.

hPrivKey

[in]

закрытый ключ, соответствующий открытому ключу, на который ссылается параметр hPublicKey. Если значение установлено в «0», то поиск закрытого ключа будет осуществляться по ID открытого ключа.

pAttributes

[in]

дополнительные атрибуты для включения в запрос. Формат аналогичен формату параметра dn (например, «1.2.840.113549.1.9.7» или «challengePassword»).

ulAttributesLength

[in]количество атрибутов в массиве, на который указывает параметр attributes.

pExtensions

[in]расширения для включения в запрос. Формат аналогичен параметру dn

ulExtensionsLength

[in]количество расширений в параметрах extensions

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions". Память для массива pCsr выделяется внутри функции, поэтому после окончания работы память необходимо освободить, вызвав функцию C_EX_FreeBuffer(). 

Функция поддерживает генерацию запроса на сертификат для следующих типов ключей: ГОСТ 34.10-2012 с длиной закрытого ключа 256 бит, ГОСТ 34.10-2001 и RSA (типы ключей CKK_GOSTR3410 и CKK_RSA).

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

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

Пример

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

Функции для работы с CMS/PKCS#7 сообщениями

C_EX_PKCS7Sign()

Назначение

Подписывает переданные на вход данные в формате PKCS#7.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7Sign)(
	CK_SESSION_HANDLE 		hSession,
	CK_BYTE_PTR 			pData,
	CK_ULONG 				ulDataLen,
	CK_OBJECT_HANDLE 		hCert,
	CK_BYTE_PTR 			*ppEnvelope,
	CK_ULONG_PTR 			pEnvelopeLen,
	CK_OBJECT_HANDLE 		hPrivKey,
	CK_OBJECT_HANDLE_PTR 	phCertificates,
	CK_ULONG 				ulCertificatesLen,
	CK_ULONG 				flags
);

Параметры

hSession[in]дескриптор сессии
pData[in]указатель на байт-массив CK_BYTE, содержащий данные для подписи
ulDataLen[in]длина данных для подписи
hCert[in]дескриптор сертификата
ppEnvelope[out]указатель на байт-массив, в который передаются данные (сообщение)
pEnvelopeLen[out]указатель на длину созданного буфера с сообщением
hPrivKey[in]дескриптор закрытого ключа, соответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата
phCertificates[in]указатель на массив сертификатов, цепочку сертификатов
ulCertificatesLen[in]количество сертификатов в параметре phCertificates
flags[in]

переменная типа CK_ULONG, может принимать следующие значения:

0 – хеширование программное, исходные данные, на которые ссылается указатель pData, сохраняются вместе с подписанным сообщением;
PKCS7_DETACHED_SIGNATURE – исходные данные, на которые ссылается указатель pData, не сохраняются вместе с подписанным сообщением.
USE_HARDWARE_HASH - использовать аппаратное хеширование.

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions". Буфер ppEnvelope создается внутри функции. После окончания работы с ним необходимо освободить его, вызвав функцию C_EX_FreeBuffer().

Функция поддерживает подпись по следующим алгоритмам: ГОСТ 34.10-2012 с длиной закрытого ключа 256 бит и ГОСТ 34.10-2001 (механизм CKM_GOSTR3410).

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

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

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

C_EX_PKCS7VerifyInit()

Назначение

Инициализирует процесс проверки подписи переданных на вход данных в формате PKCS#7.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyInit)(
	CK_SESSION_HANDLE 			hSession,
	CK_BYTE_PTR 				pCms,
	CK_ULONG 					ulCmsSize,
	CK_VENDOR_X509_STORE_PTR 	pStore,
	CK_VENDOR_CRL_MODE 			ckMode,
	CK_FLAGS 					flags 
);
 
typedef struct CK_VENDOR_X509_STORE {
	CK_VENDOR_BUFFER_PTR 	pTrustedCertificates; 		// указатель на массив доверенных сертификатов	
	CK_ULONG 				ulTrustedCertificateCount;	// количество доверенных сертификатов в массиве
	CK_VENDOR_BUFFER_PTR 	pCertificates; 				// указатель на массив, содержащий сертификаты для проверки подписи
	CK_ULONG 				ulCertificateCount;			// количество сертификатов в цепочке сертификатов
	CK_VENDOR_BUFFER_PTR 	pCrls;						// указатель на массив списков отзыва сертификатов
	CK_ULONG 				ulCrlCount;					// количество списков отзыва сертификатов в массиве
} CK_VENDOR_X509_STORE; 


typedef struct CK_VENDOR_BUFFER {
	CK_BYTE_PTR pData;		// указатель на массив байтов
	CK_ULONG ulSize;		// длина массива
}

Параметры

hSession[in]дескриптор сессии

pCms

[in]указатель на массив байтов, содержащий сообщение в формате PKCS#7 для проверки

ulCmsSize

[in]длина сообщения

pStore

[in]

указатель на структуру типа CK_VENDOR_X509_STORE, которая содержит указатели на необходимые для проверки подписи доверенные сертификаты, сертификаты подписывающей стороны и списки отозванных сертификатов

ckMode

[in]

политика проверки списков отозванных сертификатов (CRLs), может принимать следующие значения:

OPTIONAL_CRL_CHECK – отсутствие списка отозванных сертификатов не вызывает ошибку при проверке подписи;
LEAF_CRL_CHECK – требуется наличие списка отозванных сертификатов для проверки сертификата подписанта;
ALL_CRL_CHECK требуется наличие списка отозванных сертификатов для проверки каждого сертификата из цепочки

flags[in]

опции проверки подписи, могут принимать следующие значения:

CKF_VENDOR_DO_NOT_USE_INTERNAL_CMS_CERTS – не использовать содержащиеся в CMS сообщении сертификаты для поиска сертификатов подписантов (сертификаты должны быть заданы в структуре CK_VENDOR_X509_STORE);
CKF_VENDOR_ALLOW_PARTIAL_CHAINS – для проверки подписи достаточно, чтобы хотя бы один сертификат удостоверяющего центра из цепочки сертификатов подписывающей стороны находился в списке доверенных.

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions". 

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

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

CKR_ARGUMENTS_BAD,

CKR_OPERATION_ACTIVE,

CKR_FUNCTION_FAILED,

CKR_FUNCTION_NOT_SUPPORTED.

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

C_EX_PKCS7Verify()

Назначение

Выполняет проверкy присоединенной (attached) подписи в формате PKCS#7 и возвращает данные, которые были подписаны, и сертификаты подписантов.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7Verify)(
	CK_SESSION_HANDLE 			hSession,
	CK_BYTE_PTR_PTR 			ppData,
	CK_ULONG_PTR 				pulDataSize,
	CK_VENDOR_BUFFER_PTR_PTR 	ppSignerCertificates,
	CK_ULONG_PTR 				pulSignerCertificatesCount 
);

typedef struct CK_VENDOR_BUFFER {
	CK_BYTE_PTR pData;		// указатель на массив байтов
	CK_ULONG ulSize;		// длина массива
}

Параметры

hSession[in]дескриптор сессии

ppData

[out]указатель на массив байтов, содержащий данные, которые были подписаны (EncapsulatedContentInfo)

pulDataSize

[out]размер данных

ppSignerCertificates

[out]

указатель на массив, содержащий сертификаты подписантов

pulSignerCertificatesCount

[out]

количество сертификатов в массиве

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions", после вызова функции C_EX_PKCS7Verifyinit.

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

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

CKR_ARGUMENTS_BAD,

CKR_CERT_CHAIN_NOT_VERIFIED,

CKR_FUNCTION_NOT_SUPPORTED,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED,

CKR_SIGNATURE_INVALID.

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

C_EX_PKCS7VerifyUpdate()

Назначение

Начинает процесс проверки отсоединенной (detached) подписи в формате PKCS#7.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyUpdate)(
	CK_SESSION_HANDLE 			hSession,
	CK_BYTE_PTR     			pData,
	CK_ULONG 	       			ulDataSize
);

Параметры

hSession[in]дескриптор сессии

pData

[in]указатель на массив байтов, содержащий блок данных, которые были подписаны (EncapsulatedContentInfo)

ulDataSize

[in]размер данных

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions",  после вызова функции C_EX_PKCS7VerifyInit. Для завершения процесса проверки подписи необходим вызов функции C_EX_PKCS7Verifyfinal.

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

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

CKR_ARGUMENTS_BAD,

CKR_FUNCTION_NOT_SUPPORTED,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED.

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

C_EX_PKCS7VerifyFinal()

Назначение

Завершает процесс проверки отсоединенной (detached) подписи в формате PKCS#7 и возвращает сертификаты подписантов.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyFinal)(
	CK_SESSION_HANDLE 			hSession,
	CK_VENDOR_BUFFER_PTR_PTR 	ppSignerCertificates,
	CK_ULONG_PTR 				pulSignerCertificatesCount 
);

Параметры

hSession[in]дескриптор сессии

ppSignerCertificates

[out]

указатель на массив, содержащий сертификаты подписантов

pulSignerCertificatesCount

[out]

количество сертификатов в массиве

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions",  после вызова функции C_EX_PKCS7VerifyUpdate.

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

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

CKR_SIGNATURE_INVALID,

CKR_ARGUMENTS_BAD,

CKR_CERT_CHAIN_NOT_VERIFIED,

CKR_FUNCTION_NOT_SUPPORTED,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED.

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

Функции для работы с флеш-памятью 

 

C_EX_GetDriveSize()

Назначение

Возращает размер флеш-памяти токена.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetDriveSize)(
  CK_SLOT_ID            slotID,
  CK_ULONG_PTR          pulDriveSize 
);

Параметры

slotID

[in]

идентификатор слота с подключенным токеном

pulDriveSize

[out]

возвращаемый размер флеш-памяти в Мб

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

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

Пример

CK_ULONG ulDriveSize = 0;                               // Общий объем флеш-памяти
 
printf("Get Flash memory size");
rv = pFunctionListEx->C_EX_GetDriveSize(aSlots[0],      // Идентификатор слота с подключенным токеном
										&ulDriveSize);  // Возвращаемый размер флеш-памяти в Мб
if (rv != CKR_OK)
	printf(" -> Failed\n");
else
{
	printf(" -> OK\n");
	printf("Memory size: %d Mb\n", (int)ulDriveSize);
}

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

C_EX_FormatDrive()

Разбивает флеш-память токена на независимые разделы с разными правами доступа.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_FormatDrive)  (
  CK_SLOT_ID                    slotID, 
  CK_USER_TYPE                  userType,  
  CK_UTF8CHAR_PTR               pPin,    
  CK_ULONG                      ulPinLen,  
  CK_VOLUME_FORMAT_INFO_EXTENDED_PTR   pInitParams,
  CK_ULONG                      ulInitParamsCount
);
 
typedef struct CK_VOLUME_FORMAT_INFO_EXTENDED
{
  CK_ULONG                ulVolumeSize; 
  CK_ACCESS_MODE_EXTENDED accessMode;      
  CK_OWNER_EXTENDED       volumeOwner;
  CK_FLAGS                flags;
} CK_VOLUME_FORMAT_INFO_EXTENDED;

Параметры

slotID

[in]

идентификатор слота с подключенным токеном

userType

[in]

тип пользователя, допустимое значение только

CKU_SO – глобальный администратор.

pPin

[in]PIN-код пользователя

ulPinLen

[in]длина PIN-кода пользователя

pInitParams

[in]

указатель на массив структур типа CK_VOLUME_FORMAT_INFO_EXTENDED, содержащих детальную информацию о разделах

ulVolumeSize

размер раздела в Мб

accessMode

флаги доступа к разделу:

ACCESS_MODE_RW – доступ на чтение и запись;
ACCESS_MODE_RO – доступ только на чтение;
ACCESS_MODE_HIDDEN – скрытый раздел, защищенный от отображения в операционной системе, чтения, записи и любого другого типа доступа;
ACCESS_MODE_CD – раздел, эмулирующий CD-ROM.

volumeOwner

владелец раздела, имеет права на изменение флага доступа к разделу:

CKU_USER – глобальный пользователь;
CKU_SO – глобальный администратор;
CKU_LOCAL_X, где X – число от 1 до 8 – локальный пользователь X

flags

остальные флаги

ulInitParamsCount

[in]количество записей в массиве

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

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

Пример

CK_ULONG				VolumeRWSize = 0;              // Размер раздела для чтения и записи
CK_ULONG				VolumeROSize = 0;              // Размер раздела только для чтения
CK_ULONG				VolumeCDSize = 0;              // Размер раздела CD-ROM
CK_ULONG				VolumeHISize = 0;              // Размер раздела скрытого раздела

CK_ULONG			    CKU_LOCAL_1 = 0x03;			   // Идентификатор локального пользователя
CK_ULONG			    CKU_LOCAL_2 = 0x1E;            // Идентификатор локального пользователя
	
/* Шаблон для разметки разделов */
CK_VOLUME_FORMAT_INFO_EXTENDED InitParams[] =
{
	{ VolumeRWSize, ACCESS_MODE_RW, CKU_USER, 0 },
	{ VolumeROSize, ACCESS_MODE_RO, CKU_SO, 0 },
	{ VolumeHISize, ACCESS_MODE_HIDDEN, CKU_LOCAL_1, 0 },
	{ VolumeCDSize, ACCESS_MODE_CD, CKU_LOCAL_2, 0 }
};
 
...

InitParams[0].ulVolumeSize = ulDriveSize / 2;
InitParams[1].ulVolumeSize = ulDriveSize / 4;
InitParams[2].ulVolumeSize = ulDriveSize / 8;
InitParams[3].ulVolumeSize = ulDriveSize - (ulDriveSize / 2) - (ulDriveSize / 4) - (ulDriveSize / 8);
 
printf("\nFormatting flash memory");
rv = pFunctionListEx->C_EX_FormatDrive( aSlots[0],				// Идентификатор слота с подключенным токеном
										CKU_SO,					// Форматирование выполняется только с правами Администратора
										SO_PIN,					// Текущий PIN-код Администратора
										sizeof(SO_PIN),			// Длина PIN-кода Администратора
										InitParams,				// Массив с информацией о разделах
										arraysize(InitParams)); // Размер массива
if (rv != CKR_OK)
	printf(" -> Failed\n");
else
	printf(" -> OK\n");

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

C_EX_GetVolumesInfo()

Назначение

Возвращает информацию о существующих на флеш-памяти разделах. 

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetVolumesInfo)(
  CK_SLOT_ID                    slotID,
  CK_VOLUME_INFO_EXTENDED_PTR   pInfo,
  CK_ULONG_PTR                  pulInfoCount
);

typedef struct CK_VOLUME_INFO_EXTENDED
{
  CK_VOLUME_ID_EXTENDED   idVolume;     
  CK_ULONG                ulVolumeSize;
  CK_ACCESS_MODE_EXTENDED accessMode;   
  CK_OWNER_EXTENDED       volumeOwner;  
  CK_FLAGS                flags;  
} CK_VOLUME_INFO_EXTENDED;

Параметры

slotID

[in]

идентификатор слота с подключенным токеном

pInfo

[out]

указатель на массива структур типа CK_VOLUME_INFO_EXTENDED с информацией о разделах:

idVolume

идентификатор раздела, может принимать значения от 1 до 9

ulVolumeSize

размер раздела в Мб (не больше общего объема носителя)

accessMode

флаги доступа к разделу:

ACCESS_MODE_RW – доступ на чтение и запись;
ACCESS_MODE_RO – доступ только на чтение;
ACCESS_MODE_HIDDEN – скрытый раздел, защищенный от отображения в операционной системе, чтения, записи и любого другого типа доступа;
ACCESS_MODE_CD – раздел, эмулирующий CD-ROM.

volumeOwner

владелец раздела, имеет права на изменение флага доступа к разделу:

CKU_USER – глобальный пользователь;
CKU_SO – глобальный администратор;
CKU_LOCAL_X, где X – число от 1 до 8 – локальный пользователь X

flags

остальные флаги


pulInfoCount

[out]

размер массива

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

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

Примечания

При вызове функции с пустым указателем pInfo функция возвращает размер массива в pulInfoCount.

Пример

CK_VOLUME_INFO_EXTENDED_PTR   pVolumesInfo = NULL_PTR;  // Указатель на массив структур с информацией о разделах
CK_ULONG                      ulVolumesInfoСount = 0;   // Размер массива
 
printf("\nGetting volumes info");
rv = pFunctionListEx->C_EX_GetVolumesInfo( aSlots[0],			// Идентификатор слота с подключенным токеном
										   NULL_PTR,			// Указатель на массив с возвращаемой информацией о разделах
										   &ulVolumesInfoСount); // Размер массива

pVolumesInfo = (CK_VOLUME_INFO_EXTENDED*)malloc(ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED));
memset(pVolumesInfo,
		0,
		(ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED)));

rv = pFunctionListEx->C_EX_GetVolumesInfo(aSlots[0],			// Идентификатор слота с подключенным токеном
										  pVolumesInfo,			// Указатель на массив с возвращаемой информацией о разделах
										  &ulVolumesInfoСount); // Размер массива
if (rv != CKR_OK)
{
	printf(" -> Failed\n");
}
else
{
	printf(" -> OK\n");
	for (i = 0; i < (int)ulVolumesInfoСount; i++)
	{   
		printf("\nPrinting volume %1.2d info:\n", (int)i+1);
		printf(" Volume id:         %2.2d \n", pVolumesInfo[i].idVolume);    	// Идентификатор раздела
	    printf(" Volume size:       %d Mb \n", pVolumesInfo[i].ulVolumeSize);	// Объем раздела
		printf(" Access mode:       %2.2d \n", pVolumesInfo[i].accessMode);		// Права доступа к разделу
		printf(" Volume owner:      %2.2d \n", pVolumesInfo[i].volumeOwner);	// Владелец раздела
		printf(" Flags:             0x%8.8X \n", pVolumesInfo[i].flags);		// Флаги раздела
	}
}

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

C_EX_ChangeVolumeAttributes()

Назначение

Функция измененяет флаг доступа к разделу.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_ChangeVolumeAttributes)(
  CK_SLOT_ID                    slotID,
  CK_USER_TYPE                  userType,
  CK_UTF8CHAR_PTR               pPin,
  CK_ULONG                      ulPinLen,
  CK_VOLUME_ID_EXTENDED         idVolume,
  CK_ACCESS_MODE_EXTENDED       newAccessMode,
  CK_BBOOL                      bPermanent
);

Параметры

slotID

[in]

идентификатор слота с подключенным токеном

userType

[in]

владелец раздела, допустимые значения:

CKU_USER – глобальный пользователь;
CKU_SO – глобальный администратор;
число X от 3 до 8 – локальный пользователь X

pPin

[in]PIN-код пользователя

ulPinLen

[in]длина PIN-кода пользователя

idVolume

[in]

идентификатор раздела

newAccessMode

[in]новые флаги доступа к разделу

bPermanent

[in]

флаг режима измения атрибута:

CK_TRUE – постоянное изменение атрибута доступа, действует вплоть до следующего изменения атрибутов;
СK_FALSE – временное изменение прав доступа, действует до первого отключения устройства из USB-порта, после чего права доступа сбрасываются на прежние.

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

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

Пример

printf("\nChanging volume attributes");
rv = pFunctionListEx->C_EX_ChangeVolumeAttributes(aSlots[0],        // Идентификатор слота с подключенным токеном
                                                    CKU_SO,         // Владелец раздела
                                                    SO_PIN,         // PIN-код владельца раздела
                                                    sizeof(SO_PIN), // Длина PIN-кода владельца раздела
                                                    VolumeRO,       // Идентификатор раздела
                                                    ACCESS_MODE_RW, // Новые права доступа к разделу
                                                    CK_TRUE);       // CK_TRUE - постоянное изменение атрибутов, CK_FALSE - временное изменение атрибутов
if (rv != CKR_OK)
    printf(" -> Failed\n");
else
    printf(" -> OK\n");

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

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

C_EX_GetJournal()

Назначение

Функция возвращает журнал операций.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetJournal)(
  CK_SLOT_ID            slotID,          
  CK_BYTE_PTR           pJournal,        
  CK_ULONG_PTR          pulJournalSize   
);

Параметры

slotID

[in]идентификатор слота

pJournal

[out]указатель на запись журнала

pulJournalSize

[out]размер записи журнала

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

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

Примечания

Формат возвращаемой записи журнала и пример парсинга доступны по ссылке.

Пример

CK_BYTE_PTR           pJournal = NULL_PTR;          // Указатель на значение журнала
CK_ULONG              ulJournalSize = 0;            // Размер журнала
  
while(TRUE)
{
...
    /* Получить размер журнала */
    printf("Getting journal size");
    rv = pFunctionListEx->C_EX_GetJournal(aSlots[0],      // Хэндл слота с подключенным токеном
                                          NULL_PTR,       // Указатель на журнал
                                          &ulJournalSize);// Размер журнала
    if (rv != CKR_OK)
    {
        printf(" -> Failed\n");
        break;
    }
    printf(" -> OK\n");
  
    pJournal = (CK_BYTE*)malloc(ulSlotCount * sizeof(CK_BYTE));
    if (pJournal == NULL)
    {
        printf("Memory allocation for pJournal failed! \n");
        break;
    }
    memset(pJournal, 0, (ulJournalSize * sizeof(CK_BYTE)));
  
    /* Получить журнал */
    printf("Getting journal");
    rv = pFunctionListEx->C_EX_GetJournal(aSlots[0],       // Хэндл слота с подключенным токеном
                                          pJournal,       // Указатель на журнал
                                          &ulJournalSize);// Размер журнала
    if (rv != CKR_OK)
    {
        printf(" -> Failed %X\n", (int)rv);
        break;
    }
    printf(" -> OK\n");
  
    ...
    break;
}

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

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

 

C_EX_LoadActivationKey()

Назначение

Активирует защищенный канал связи с токеном с использованием пароля (поддерживается только в 20-й версии прошивки)

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_LoadActivationKey)(
  CK_SESSION_HANDLE hSession,
  CK_BYTE_PTR       key,
  CK_ULONG          keySize
);

Параметры

hSession

[in]дескриптор сессии

key

[in]указатель на пароль

keySize

[in]длина пароля

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

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

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

C_EX_SetActivationPassword()

Назначение

Активирует защищенный канал связи с токеном с использованием пароля (поддерживается с 21-й версии прошивки).

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SetActivationPassword)(
  CK_SLOT_ID        slotID,
  CK_UTF8CHAR_PTR   password
);

Параметры

hSession

[in]дескриптор сессии

password

[in]пароль активации

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

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

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

C_EX_GenerateActivationPassword()

Назначение

Генерирует пароль для активации защищенного канала связи с токеном.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GenerateActivationPassword)(
  CK_SESSION_HANDLE     hSession,
  CK_ULONG              ulPasswordNumber,
  CK_UTF8CHAR_PTR       pPassword,
  CK_ULONG_PTR          pulPasswordSize,
  CK_ULONG              ulPasswordCharacterSet
);

Параметры

hSession

[in]дескриптор сессии

ulPasswordNumber


порядковый номер генерируемого пароля. Допустимые значения от 1 до 6 и

GENERATE_NEXT_PASSWORD – генерировать следующий пароль (только для 21-й версии микропрограммы)

pPassword

[out] указатель на буфер, содержащий сгенерированный пароль

pulPasswordSize

[out]размер буфера

ulPasswordCharacterSet

[in]

набор допустимых символов:

CAPS_AND_DIGITS – заглавные буквы латинского алфавита без O и цифры без 0
CAPS_ONLY – заглавные буквы латинского алфавита

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

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

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

C_EX_TokenManage() 

Назначение

Управляет режимом работы токена и таймаутом беспроводного соединения Рутокен Bluetooth.

 Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_TokenManage)(
  CK_SESSION_HANDLE     hSession,
  CK_ULONG              ulMode,
  CK_VOID_PTR           pValue
);

Параметры

hSession

[in]дескриптор сессии

ulMode

[in]

режим работы функции:

MODE_SET_BLUETOOTH_POWEROFF_TIMEOUT – установить таймаут для беспроводного канала связи
MODE_SET_CHANNEL_TYPE – установить тип используемого канала связи

pValue

[in] 
  • значение таймаута для режима MODE_SET_BLUETOOTH_POWEROFF_TIMEOUT:

1 .. 0х46 – произвольное значение в минутах, от 1 минуты до 70 минут
BLUETOOTH_POWEROFF_TIMEOUT_DEFAULT – по умолчанию
BLUETOOTH_POWEROFF_TIMEOUT_MAX – максимальное значение (70 минут)

  • канал связи для режима MODE_SET_CHANNEL_TYPE:

CHANNEL_TYPE_USB – по шине USB
CHANNEL_TYPE_BLUETOOTH – по Bluetooth

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

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

Мультифункциональная функция

Здесь описаны не все возможные параметры функции. Описание других параметров функции можно найти здесь


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

Вспомогательные функции

C_EX_FreeBuffer()

Назначение

Функция освобождает память, выделенную другими расширенными функциями, например C_EX_GetCertificateInfoText.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_FreeBuffer)(
	CK_BYTE_PTR		pBuffer
);

Параметры

pBuffer[in]указатель на буфер

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

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

Пример

CK_BYTE_PTR		pInfo

.
.
rv = pfGetFunctionListEx -> C_EX_FreeBuffer(pInfo);				// очистка буфера, использующегося функцией C_EX_GetCertificateInfoText()
if (rv != CKR_OK)												// проверка результата
	printf("C_EX_FreeBuffer() -> failed \n");
else
	printf("C_EX_FreeBuffer() -> OK \n"); 

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



  • No labels