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 7 Next »

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

C_EX_GetFunctionListExtended()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetFunctionListExtended)(
	CK_FUNCTION_LIST_EXTENDED_PTR_PTR	ppFunctionList 
);

Параметры

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

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

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

(question)

Пример

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

Пример

Пример использования функции 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_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_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, не сохраняются вместе с подписанным сообщением.

Возвращаемые данные

(question)

Примечание

Функция может быть вызвана только из состояний  "R/W User Functions" и  "R User Functions". Буфер ppEnvelope создается внутри функции. После окончания работы с ним необходимо освободить его, вызвав функцию 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

Возвращаемые данные

(question)

Примечание

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

Пример

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

C_EX_FreeBuffer()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_FreeBuffer)(
	CK_BYTE_PTR		pBuffer
);

Параметры

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

Возвращаемые данные

(question)

Пример

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

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

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-кода

Возвращаемые данные

(question)

Пример

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

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

  • No labels