...

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

...

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

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

...

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

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

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

C_EX_TokenManage() 

Anchor
C_EX_TokenManageSlotAndToken C_EX_TokenManageSlotAndToken

Назначение

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

...

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

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

C_EX_SlotManage

...

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

Синтаксис

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

...

Для режима работы функции MODE_GET_LOCAL_PIN_

...

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

...

ulPinID

...

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

...

ulMinSize

...

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

...

ulMaxSize

...

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

...

ulMaxRetryCount

...

ulCurrentRetryCount

...

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

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

...

flags

...

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

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

INFO в pValue возвращается указатель массив структур типа CK_LOCAL_PIN_INFO:

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

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

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

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

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

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

C_EX_GetCertificateInfoText()

Назначение

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

Синтаксис

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

Параметры

Примечание

Функция может быть вызвана из любого состояния. Так как память для массива выделяется внутри функции, по окончании работы функции 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,

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

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

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

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

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

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

C_EX_GetCertificateInfoText()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_GetCertificateInfoText)(
	CK_SESSION_HANDLE	hSession, 
	CK_OBJECT_HANDLE 	hCerthPrivKey,
	CK_CHAR_PTR* 		pInfo*pAttributes, 
	CK_ULONG_PTR 			pulInfoLen
ulAttributesLength,
	CK_CHAR_PTR 		*pExtensions,
	CK_ULONG 			ulExtensionsLength
);

Параметры

Примечание

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

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

C_EX_CreateCSR()

Назначение

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

Синтаксис

Примечание

Функция может быть вызвана только из состояний  "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_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 			*pCsrpData,
	CK_ULONG_PTR 		pulCsrLength		ulDataLen,
	CK_OBJECT_HANDLE 		hPrivKeyhCert,
	CK_CHARBYTE_PTR 			*pAttributesppEnvelope,
	CK_ULONG_PTR 			ulAttributesLengthpEnvelopeLen,
	CK_OBJECT_HANDLE 		hPrivKey,
	CK_OBJECT_CHARHANDLE_PTR 		*pExtensionsphCertificates,
	CK_ULONG 				ulCertificatesLen,
	CK_ULONG 			ulExtensionsLength	flags
);

Параметры

Примечание

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

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

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

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

Пример

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

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

C_EX_

...

PKCS7VerifyInit()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7SignPKCS7VerifyInit)(
	CK_SESSION_HANDLE 			hSession,
	CK_BYTE_PTR 				pDatapCms,
	CK_ULONG 					ulDataLenulCmsSize,
	CK_VENDOR_OBJECTX509_STORE_HANDLEPTR 		hCertpStore,
	CK_VENDOR_BYTECRL_PTRMODE 			*ppEnvelopeckMode,
	CK_ULONG_PTRFLAGS 					pEnvelopeLen,
	CK_OBJECT_HANDLE 		hPrivKey,flags 
);
 
typedef struct CK_VENDOR_X509_STORE {
	CK_OBJECTVENDOR_HANDLEBUFFER_PTR 	phCertificates,
	CK_ULONGpTrustedCertificates; 				ulCertificatesLen,// указатель на массив доверенных сертификатов	
	CK_ULONG 					flags
);

Параметры

...

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

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

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;		// длина массива
}

Параметры

Примечание

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

Примечание

Функция может быть вызвана только из состояний  "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;		// длина массива
}

Параметры

Примечание

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

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

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

CKR_ARGUMENTS_BAD,

CKR_OPERATION_ACTIVE,

CKR_FUNCTION_FAILED,

Примечание

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

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

CKR_OK – функция выполнена успешно.
CKR_CERT_CHAIN_NOT_VERIFIED – функция выполнена успешно, но цепочка сертификации не проверялась,

CKR_ARGUMENTS_BAD,

CKR_CERT_CHAIN_NOT_VERIFIED,

CKR_FUNCTION_NOT_SUPPORTED,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED,

CKR_SIGNATURE_INVALIDCKR_FUNCTION_NOT_SUPPORTED.

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

C_EX_

...

PKCS7VerifyUpdate()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyPKCS7VerifyUpdate)(
	CK_SESSION_HANDLE 			hSession,
	CK_BYTE_PTR_PTR 			ppData,
	CK_ULONG_PTR     				pulDataSizepData,
	CK_VENDOR_BUFFER_PTR_PTR 	ppSignerCertificates,
	CK_ULONG_PTR 				pulSignerCertificatesCount 
);

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

ulDataSize
);

Параметры

Примечание

Примечание

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

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

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_

...

PKCS7VerifyFinal()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyUpdatePKCS7VerifyFinal)(
	CK_SESSION_HANDLE 			hSession,
	CK_VENDOR_BYTEBUFFER_PTR_PTR     			pDatappSignerCertificates,
	CK_ULONG_PTR 	       			ulDataSizepulSignerCertificatesCount 
);

Параметры

Примечание

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

...

PKCS7VerifyUpdate.

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

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

CKR_SIGNATURE_INVALID,

CKR_ARGUMENTS_BAD,

CKR_CERT_CHAIN_NOT_VERIFIED,

CKR_FUNCTION_NOT_SUPPORTED,

...

CKR_OPERATION_NOT_INITIALIZED.

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

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

C_EX_

...

GetDriveSize()

Назначение

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

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyFinalGetDriveSize)(
	  CK_SESSION_HANDLE 			hSession,
	CK_VENDOR_BUFFER_PTR_PTR 	ppSignerCertificates,
	SLOT_ID            slotID,
  CK_ULONG_PTR 				pulSignerCertificatesCount          pulDriveSize 
);

Параметры

Примечание

...

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

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

Параметры

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

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

CK_ULONG ulDriveSize = 0;                      slotID, 
  CK_USER_TYPE      // Общий объем флеш-памяти
 
printf("Get Flash memory size");
rv = pFunctionListEx->C_EX_GetDriveSize(aSlots[0],   userType,  
 // Идентификатор слота с подключенным токеном
										&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 CK_UTF8CHAR_PTR               pPin,    
  CK_ULONG                      ulPinLen,  
  CK_VOLUME_FORMAT_INFO_EXTENDED_PTR   pInitParams,
  CK_ULONG                     slotID, ulInitParamsCount
);
 
typedef struct CK_VOLUME_FORMAT_USER_TYPEINFO_EXTENDED
{
  CK_ULONG                userType,ulVolumeSize;  
  CK_UTF8CHARACCESS_MODE_PTREXTENDED accessMode;      
    CK_OWNER_EXTENDED    pPin,    volumeOwner;
  CK_ULONGFLAGS                      ulPinLen,  
 flags;
} CK_VOLUME_FORMAT_INFO_EXTENDED_PTR   pInitParams,
  CK_ULONG                      ulInitParamsCount
);
 
typedef struct ;

Параметры

...

Параметры

ulInitParamsCount