Anchor

	1
	1

Table of Contents

maxLevel	2
outline	true
style	none

...

Code Block

language	cpp
title	Пример использования функции C_EX_SetLicense
collapse	true

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

...

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

...

Примечание

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

...

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

C_EX_

...

CreateCSR()

Назначение

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

Синтаксис

Code Block

CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7SignCreateCSR)(
	CK_SESSION_HANDLE 		hSession,
	CK_BYTEOBJECT_PTRHANDLE 			pDatahPublicKey,
	CK_CHAR_ULONGPTR 				ulDataLen*dn,
	CK_OBJECT_HANDLEULONG 			hCertdnLength,
	CK_BYTE_PTR 			*ppEnvelopepCsr,
	CK_ULONG_PTR 			pEnvelopeLenpulCsrLength,
	CK_OBJECT_HANDLE 		hPrivKey,
	CK_OBJECT_HANDLECHAR_PTR 		phCertificates*pAttributes,
	CK_ULONG 			ulAttributesLength,
	CK_CHAR_PTR 		ulCertificatesLen*pExtensions,
	CK_ULONG 				flagsulExtensionsLength
);

Параметры

hSession	[in]	дескриптор сессии
pData hPublicKey	[in]	указатель на байт-массив CK_BYTE, содержащий данные для подписи
ulDataLen	[in]	длина данных для подписи
hCert	[in]	дескриптор сертификата
ppEnvelope	[out]	указатель на байт-массив, в который передаются данные (сообщение)
дескриптор открытого ключа для создания сертификата
dn	[in]	уникальное имя - массив строк, где в первой строке располагается тип поля в текстовом формате или идентификатор объекта (CN или «2.5.4.3»). Во второй строке должно находиться значение поля в кодировке UTF8. Последующие поля передаются аналогично, количество строк должно быть кратно двум
dnLength	[in]	количество строк в массиве, на который ссылается параметр dn
pCsr	[in]	указатель на указатель на массив байт, в который будет записан созданный запрос на сертификат
pulCsrLength	[in]	указатель на переменную, в которой сохраняется размер массива.	pEnvelopeLen	[out]	указатель на длину созданного буфера с сообщением
hPrivKey	[in]	дескриптор закрытого ключа, соответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата
phCertificates	[in]	указатель на массив сертификатов, цепочку сертификатов (в текущей версии не используется)
закрытый ключ, соответствующий открытому ключу, на который ссылается параметр hPublicKey. Если значение установлено в «0», то поиск закрытого ключа будет осуществляться по ID открытого ключа.
pAttributes	[in]	дополнительные атрибуты для включения в запрос. Формат аналогичен формату параметра dn (например, «1.2.840.113549.1.9.7» или «challengePassword»).
ulAttributesLength ulCertificatesLen	[in]	количество сертификатов в параметре phCertificates (в текущей версии не используется)атрибутов в массиве, на который указывает параметр attributes.
pExtensions	[in]	расширения для включения в запрос. Формат аналогичен параметру dn
ulExtensionsLength flags	[in]	переменная типа CK_ULONG, может принимать следующие значения: 0 – исходные данные, на которые ссылается указатель pData, сохраняются вместе с подписанным сообщением; PKCS7_DETACHED_SIGNATURE – исходные данные, на которые ссылается указатель pData, не сохраняются вместе с подписанным сообщением.

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

Примечание

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

Примечание

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

Пример

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

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

C_EX_

...

PKCS7Sign()

Назначение

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

Синтаксис

Code Block

CK_DEFINE_FUNCTION(CK_RV, C_EX_CreateCSRPKCS7Sign)(
	CK_SESSION_HANDLE 		hSession,
	CK_OBJECTBYTE_HANDLEPTR 			hPublicKeypData,
	CK_CHAR_PTRULONG 				*dnulDataLen,
	CK_ULONGOBJECT_HANDLE 			dnLengthhCert,
	CK_BYTE_PTR 			*pCsrppEnvelope,
	CK_ULONG_PTR 		pulCsrLength	pEnvelopeLen,
	CK_OBJECT_HANDLE 		hPrivKey,
	CK_OBJECT_CHARHANDLE_PTR 		*pAttributesphCertificates,
	CK_ULONG 			ulAttributesLength,
	CK_CHAR_PTR 		*pExtensionsulCertificatesLen,
	CK_ULONG 				ulExtensionsLengthflags
);

Параметры

hSession	[in]	дескриптор сессии
pData	[in]	указатель на байт-массив CK_BYTE, содержащий данные для подписи
ulDataLen	[in]	длина данных для подписи
hCerthPublicKey	[in]	дескриптор открытого ключа для создания сертификата
dnppEnvelope	[inout]	уникальное имя указатель на байт-массив строк, где в первой строке располагается тип поля в текстовом формате или идентификатор объекта (CN или «2.5.4.3»). Во второй строке должно находиться значение поля в кодировке UTF8. Последующие поля передаются аналогично, количество строк должно быть кратно двум
dnLength	[in]	количество строк в массиве, на который ссылается параметр dn
pCsr	[in]	указатель на указатель на массив байт, в который будет записан созданный запрос на сертификат
в который передаются данные (сообщение)
pEnvelopeLen	[out]	указатель на длину созданного буфера с сообщением
hPrivKey	[in]	дескриптор закрытого ключа, соответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата
phCertificatespulCsrLength	[in]	указатель на переменную, в которой сохраняется размер массива.массив сертификатов, цепочку сертификатов (в текущей версии не используется)
ulCertificatesLen	[in]	количество сертификатов в параметре phCertificates (в текущей версии не используется)
flagshPrivKey	[in]	закрытый ключ, соответствующий открытому ключу, на который ссылается параметр hPublicKey. Если значение установлено в «0», то поиск закрытого ключа будет осуществляться по ID открытого ключа.
pAttributes	[in]	дополнительные атрибуты для включения в запрос. Формат аналогичен формату параметра dn (например, «1.2.840.113549.1.9.7» или «challengePassword»).
ulAttributesLength	[in]	количество атрибутов в массиве, на который указывает параметр attributes.
pExtensions	[in]	расширения для включения в запрос. Формат аналогичен параметру dn
ulExtensionsLength	[in]	количество расширений в параметрах extensions

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

...

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

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

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

Примечание

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

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

C_EX_PKCS7VerifyInit()

Назначение

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

Синтаксис

Code Block

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]	указатель на байт-массив CK_BYTE, содержащий сообщение в формате PKCS#7 для проверки
ulCmsSize	[in]	длина сообщения
pStore	[in]	структура типа CK_VENDOR_X509_STORE, содержащая указатели на доверенные сертификаты, цепочку сертификатов и списки отозванных сертификатов
ckMode	[in]	политика проверки списков отозванных сертификатов (CRLs), может принимать следующие значения: OPTIONAL_CRL_CHECK – отсутствие соответсвующего списка отозванных сертификатов не влияет на верификацию; LEAF_CRL_CHECK – проверяется актуальность сертификата удостоверяющего центра (центра сертификации, CA) подписывающей стороны; ALL_CRL_CHECK – проверяется актуальность сертификат каждого удостоверяющего центра из цепочки сертификатов.
flags	[in]	переменная типа CK_ULONG, может принимать следующие значения: CKF_VENDOR_DO_NOT_USE_INTERNAL_CMS_CERTS – не использовать для проверки подписи содержащиеся в CMS сообщении сертификаты; CKF_VENDOR_ALLOW_PARTIAL_CHAINS – для проверки подписи достаточно, чтобы хотя бы один сертификат удостоверяющего центра из цепочки сертификатов подписывающей стороны находился в списке доверенных.

Примечание

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

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

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

Стандартные коды ошибок:

CKR_ARGUMENTS_BAD,

CKR_OPERATION_ACTIVE,

CKR_FUNCTION_NOT_SUPPORTED.

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

C_EX_PKCS7Verify()

Назначение

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

Синтаксис

Code Block

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	[in]	указатель на байт-массив CK_BYTE, содержащий detached подпись в случае отсутствия подписи в CMS сообщении, заданном функцией C_EX_PKCS7VerifyInit
pulDataSize	[in]	длина detached подписи
ppSignerCertificates	[in]	указатель на массив, содержащий сертификаты подписанта
pulSignerCertificatesCount	[in]	количество сертификатов в массиве

Примечание

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

...

_PKCS7Verifyinit.

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

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

Стандартные коды ошибок:

CKR_SIGNATURE_INVALID

CKR_ARGUMENTS_BAD,

CKR_OPERATION_ACTIVE,

CKR_FUNCTION_NOT_SUPPORTED.

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

C_EX_FreeBuffer()

Назначение

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

Синтаксис

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_EX_FreeBuffer)( CK_BYTE_PTR pBuffer );

Параметры

pBuffer

[in]

указатель на буфер

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

Пример

Code Block

collapse	true

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-код, если он был установлен заранее.

Синтаксис

Code Block

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

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

Пример

Code Block

collapse	true

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

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

Page tree

Pages … Портал документации Рутокен Высокоуровневые программные интерфейсы PKCS#11 Справочник PKCS#11 Описание функций расширения Page History

Versions Compared

Old Version 8

New Version 9

Key

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

C_EX_GetCertificateInfoText()

Примечание

C_EX_

CreateCSR()

Назначение

Синтаксис

Параметры

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

Примечание

Примечание

Пример

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

C_EX_

PKCS7Sign()

Назначение

Синтаксис

Параметры

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

Примечание

C_EX_PKCS7VerifyInit()

Назначение

Синтаксис

Параметры

Примечание

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

C_EX_PKCS7Verify()

Назначение

Синтаксис

Параметры

Примечание

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

C_EX_FreeBuffer()

Назначение

Синтаксис

Параметры

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

Пример

C_EX_SetLocalPIN()

Назначение

Синтаксис

Параметры

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

Пример

Pages

Портал документации Рутокен
Высокоуровневые программные интерфейсы
PKCS#11
Справочник PKCS#11
Описание функций расширения

Page History