Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Anchor
1
1
Table of Contents
maxLevel2
outlinetrue
stylenone

...

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

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

(question)

Примечание

количество расширений в параметрах 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]указатель на буфер

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

(question)

Пример

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

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

(question)

Пример

Code Block
collapsetrue
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"); 

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