Page tree

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

Compare with Current View Page History

Version 1 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 -> failed \n");
else
	printf("Getting connected slots list -> OK \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 -> failed \n");
else
	printf("Token initialization -> OK \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 = pfLstEx -> 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){
	pfLst->C_Logout(hSession);
	pfLst->C_CloseSession(hSession);
	pfLst->C_Finalize(NULL_PTR);
	FreeLibrary(hModule);
	printf("C_EX_SetLicense() failed\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_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](question)дескриптор закрытого ключа, сответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата
phCertificates[in](question)указатель на массив сертификатов, цепочку сертификатов (в текущей версии не используется)
ulCertificatesLen[in](question)количество сертификатов в параметре 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-код для PinPad In, если он поддерживает эту операцию.

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_SetLocalPIN)(
	CK_SLOT_ID 			slotID,
	CK_UTF8CHAR_PTR 	pUserPin,
	CK_ULONG 			ulUserPinLen,
	CK_UTF8CHAR_PTR 	pNewLocalPin,
	CK_ULONG 			ulNewLocalPinLen,
	CK_ULONG 			ulLocalID
);

Параметры

slotID[in]

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

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

ulNewLocalPinLen

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

ulLocalID

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

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

(question)

Пример

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

.
.
rv = pfGetFunctionListEx -> C_EX_SetLocalPIN(
	slots[0], 													// считаем, что токен подключен к первому слоту
	Pin, 														// текущий PIN-код Пользователя
	arraysize(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