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

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.

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

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 ранее записанная лицензия удалена не будет.

Пример

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 возвращается указатель на длину буфера для требуемой лицензии.

Пример

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_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, не сохраняются вместе с подписанным сообщением.

Примечание

Функция может быть вызвана только из состояний  "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_PTR 			ppData,
	CK_ULONG_PTR 				pulDataSize
);

Параметры

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

ppData

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

pulDataSize

[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 – глобальный администратор;
CKU_LOCAL_X, где X – число от 1 до 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_SignInvisibleInit()

Назначение

Функция инициализирует процесс подписи сообщения без отображения на экране.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SignInvisibleInit)(
  CK_SESSION_HANDLE hSession,
  CK_MECHANISM_PTR  pMechanism,
  CK_OBJECT_HANDLE  hKey       
);

Параметры

hSession

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

pMechanism

[in]механизм подписи

hKey

[in]дескриптор ключа для подписи

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

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

Пример

/* Набор параметров КриптоПро алгоритма ГОСТ Р 34.11-1994 */
CK_BYTE     GOST3411params[]  = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x01 };
  
/*  Механизм подписи подписи по алгоритму ГОСТ Р 34.10-2001 с хешированием по алгоритму ГОСТ Р 34.11-94*/
CK_MECHANISM    HashSigVerMech = {CKM_GOSTR3410_WITH_GOSTR3411, GOST3411params, sizeof(GOST3411params)};
  
while(TRUE)
{
    ...
  
    /* Инициализировать операцию подписи данных */
    printf("C_EX_SignInvisibleInit");
    rv = pFunctionList->C_EX_SignInvisibleInit(hSession,         // Хэндл сессии
                                               &HashSigVerMech ,    // Механизм подписи
                                               hPrivateKey );       // Хэндл закрытого ключа
    if (rv != CKR_OK)
    {
        printf(" -> Failed\n");
        break;
    }
    printf(" -> OK\n");
} 

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

C_EX_SignInvisible()

Назначение

Функция осуществляет процесс подписи сообщения без отображения на экране, вызывается после функции C_EX_SignInvisibleInit.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SignInvisible)(
  CK_SESSION_HANDLE hSession,
  CK_BYTE_PTR       pData,
  CK_ULONG          ulDataLen,   
  CK_BYTE_PTR       pSignature, 
  CK_ULONG_PTR      pulSignatureLen
);

Параметры

hSession

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

pData

[in]указатель на буфер данных для подписи

ulDataLen

[in]размер данных для подписи в байтах

pSignature

[out]указатель на буфер с подписью

pulSignatureLen

[out]размер буфера с подписью 

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

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

 

Пример

 
/* Данные для подписи в виде двоичной строки */
CK_BYTE pbtData[] = { 0x3C, 0x21, 0x50, 0x49, 0x4E, 0x50, 0x41, 0x44, 0x46, 0x49, 0x4C, 0x45, 0x20, 0x52, 0x55, 0x3E,
                      0x3C, 0x21, 0x3E, 0xED, 0xE5, 0xE2, 0xE8, 0xE4, 0xE8, 0xEC, 0xFB, 0xE9, 0x20, 0xF2, 0xE5, 0xEA,
                      0xF1, 0xF2, 0x3C, 0x4E, 0x3E, 0xD4, 0xC8, 0xCE, 0x3A, 0x3C, 0x56, 0x3E, 0xCF, 0xE5, 0xF2, 0xF0,
                      0xEE, 0xE2, 0x20, 0xCF, 0xE5, 0xF2, 0xF0, 0x20, 0xCF, 0xE5, 0xF2, 0xF0, 0xEE, 0xE2, 0xE8, 0xF7,
                      0x20, 0xCC, 0xEE, 0xF1, 0xEA, 0xE2, 0xE0, 0x2C, 0x20, 0xCF, 0xE8, 0xEE, 0xED, 0xE5, 0xF0, 0xF1,
                      0xEA, 0xE0, 0xFF, 0x20, 0xF3, 0xEB, 0x2C, 0x20, 0xE4, 0x2E, 0x20, 0x33, 0x2C, 0x20, 0xEA, 0xE2,
                      0x2E, 0x20, 0x37, 0x32 };
  
CK_BYTE_PTR pbtSignature = NULL_PTR;                 // Указатель на буфер, содержащий подпись для исходных данных
CK_ULONG ulSignatureSize = 0;                        // Размер буфера, содержащего подпись для исходных данных, в байтах
  
while(TRUE)
{
    ...
  
    /* Определить размер подписи*/
    printf("C_EX_SignInvisible step 1");
    rv = pFunctionList->C_EX_SignInvisible(hSession,            // Хэндл сессии
                                           pbtData,             // Буфер с данными для подписи
                                           arraysize(pbtData),  // Длина подписываемых данных
                                           pbtSignature,        // Буфер с подписью
                                           &ulSignatureSize);   // Длина подписи
    if (rv != CKR_OK)
    {
        printf(" -> Failed\n");
        break;
    }
    printf(" -> OK\n");
 
    pbtSignature = (CK_BYTE*)malloc(ulSignatureSize);
    if (pbtSignature  == NULL)
    {
        printf("Memory allocation for pbtSignature failed! \n");
        break;
    }
    memset( pbtSignature,
            0,
            ulSignatureSize * sizeof(CK_BYTE));
 
    /* Подписать исходные данные */
    printf("C_EX_SignInvisible step 2");
    rv = pFunctionList->C_EX_SignInvisible(hSession,            // Хэндл сессии
                                           pbtData,             // Буфер с данными для подписи
                                           arraysize(pbtData),  // Длина подписываемых данных
                                           pbtSignature,        // Буфер с подписью
                                           &ulSignatureSize);   // Длина подписи
    if (rv != CKR_OK)
    {
        printf(" -> Failed\n");
        break;
    }
    printf(" -> OK\n");
} 
к содержанию ↑

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

 

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 – функция выполнена успешно.

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

Функции системного назначeния

C_EX_SlotManage

Назначение

Позволяет выполнить расширенную инициализацию токена, получить значение имитовставки токена и расширенную информацию о всех локальных PIN-кодах токена.

Синтаксис

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

Параметры

hSession

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

ulMode

[in]

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

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

pValue

[out] указатель на буфер с возвращаемым значением (зависит от значения аргумента ulMode).

Для режима работы функции 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 – функция выполнена успешно.

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

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

C_EX_WrapKey

Назначение

Генерирует сессионный ключ, вычисляет ключ согласования, шифрует сессионный ключ ключом согласования и возвращает указатель на дескриптор сессионного ключа, хранящегося в оперативной памяти токена.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_WrapKey)(
 CK_SESSION_HANDLE hSession,
 CK_MECHANISM_PTR pGenerationMechanism,
 CK_ATTRIBUTE_PTR pKeyTemplate,
 CK_ULONG ulKeyAttributeCount,
 CK_MECHANISM_PTR pDerivationMechanism,
 CK_OBJECT_HANDLE hBaseKey,
 CK_MECHANISM_PTR pWrappingMechanism,
 CK_BYTE_PTR pWrappedKey,
 CK_ULONG_PTR pulWrappedKeyLen,
 CK_OBJECT_HANDLE_PTR phKey
);

Параметры

hSession

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

pGenerationMechanism

[in]

механизм генерации сессионного ключа. Допустимое значение:

CKM_GOST28147_KEY_GEN – по стандарту ГОСТ 28147-89

pKeyTemplate

[in] указатель на буфер, содержащий шаблон сессионого ключа

ulKeyAttributeCount

[in] количество атрибутов сессионого ключа в шаблоне

pDerivationMechanism

[in] 

механизм выработки ключа согласования. Допустимые значения:

CKM_GOSTR3410_DERIVE – по стандарту ГОСТ Р 34.10-2001
CKM_GOSTR3410_12_DERIVE – по стандарту ГОСТ Р 34.10-2012

hBaseKey

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

pWrappingMechanism

[in] механизм шифрования сессионного ключа

pWrappedKey

[in] указатель на зашифрованный сессионный ключ

pulWrappedKeyLen

[in] 

длина зашифрованного сессионного ключа

phKey

[out] указатель на сессионый ключ (CEK)

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

C_EX_UnwrapKey

Назначение

Вычисляет ключ согласования, расшифровывает зашифрованный сессионный ключ и возвращает указатель на дескриптор расшифрованного сессионного ключа, хранящего в оперативной памяти токена.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_UnwrapKey)(
 CK_SESSION_HANDLE hSession,
 CK_MECHANISM_PTR pDerivationMechanism,
 CK_OBJECT_HANDLE hBaseKey,
 CK_MECHANISM_PTR pUnwrappingMechanism,
 CK_BYTE_PTR pWrappedKey,
 CK_ULONG ulWrappedKeyLen,
 CK_ATTRIBUTE_PTR pKeyTemplate,
 CK_ULONG ulKeyAttributeCount,
 CK_OBJECT_HANDLE_PTR phKey
);

Параметры

hSession

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

pDerivationMechanism

[in]

механизм выработки ключа согласования (KEK). Допустимые значения:

CKM_GOSTR3410_DERIVE – по стандарту ГОСТ Р 34.10-2001
CKM_GOSTR3410_12_DERIVE – по стандарту ГОСТ Р 34.10-2012

hBaseKey

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

pUnwrappingMechanism

[in] 

механизм расшифрования зашифрованного сессионного ключа

pWrappedKey

[in]указатель на зашифрованный сессионный ключ

ulWrappedKeyLen

[in]
длина зашифрованного сессионного ключа

pKeyTemplate

[in]указатель на буфер, содержащий шаблон сессионного ключа

ulKeyAttributeCount

[in]количество атрибутов сессионного ключа в шаблоне

phKey

[out]указатель на дескриптор сессионного ключа (CEK)

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


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

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"); 

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