C_EX_TokenManage
Anchor | ||||
---|---|---|---|---|
|
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
...
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetFunctionListExtended)( CK_FUNCTION_LIST_EXTENDED_PTR_PTR ppFunctionList ); |
Параметры
ppFunctionList | [out] | указатель на список функций расширения |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
Функция позволяет получить специфическую для устройств Рутокен информацию: класс токена, количество свободной и общей памяти, тип токена, номер протокола, количество оставшихся попыток ввода пин-кода Пользователя и Администратора и т.д. По сравнению с похожей по назначению стандартной функции C_GetTokenInfo функция расширения предоставляет более полную информацию о токене.
...
Code Block |
---|
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 – функция выполнена успешно.
...
Code Block |
---|
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.
Внимание! Для Рутокен S параметры ulMinAdminPinLen и ulMinUserPinLen из структуры CK_RUTOKEN_INIT_PARAM, не могут принимать значение больше 1.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
Code Block | ||||
---|---|---|---|---|
| ||||
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"); |
...
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_UnblockUserPIN)( CK_SESSION_HANDLE hSession ); |
Параметры
hSession | [in] | дескриптор сесии |
Примечание
Функция сбрасывает счетчик неверных попыток ввода PIN-кода для CKU_USER. Функция может быть вызвана только из сессии, имеющей статус CKS_RW_SO_FUNCTIONS.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
Code Block |
---|
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 – функция выполнена успешно.
...
Code Block |
---|
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 – функция выполнена успешно.
...
Code Block |
---|
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 – функция выполнена успешно.
...
Code Block |
---|
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 – функция выполнена успешно.
...
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-кода в пределах от 0x03 до 0x1E |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
Code Block | ||
---|---|---|
| ||
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 |
---|
Назначение
Функция позволяет получить информацию о сертификате из токена в текстовом виде.
|
Назначение
Предоставляет механизм принудительной смены PIN-кода пользователя.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetCertificateInfoTextTokenManage)( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hCert, CK_CHAR_PTR* pInfo, CK_ULONG_PTR pulInfoLen hSession, CK_ULONG ulMode, CK_VOID_PTR pValue ); |
Параметры
hSession | [in] | дескриптор сессии |
ulMode | [in] |
Примечание
Функция может быть вызвана из любого состояния. Так как память для массива выделяется внутри функции, по окончании работы функции pInfo нужно высвободить функцией C_EX_FreeBuffer.
C_EX_CreateCSR()
Назначение
Создает запрос на выпуск сертификата в центр сертификации и упаковывает его в формат PKCS#10.
Синтаксис
Code Block |
---|
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 |
Примечание
Функция может быть вызвана только из состояний "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.
Синтаксис
Code Block |
---|
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, сохраняются вместе с подписанным сообщением; |
Примечание
Функция может быть вызвана только из состояний "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()
Назначение
режим работы функции:
| ||
pValue | [in] |
|
Возвращаемые значения
CKR_OK
– функция выполнена успешно.
CKR_ARGUMENTS_BAD
– неправильно переданы параметры функции
CKR_USER_NOT_LOGGED_IN
– пользователь SKU_SO не авторизован на токене (режимы)
Info | ||
---|---|---|
| ||
Здесь описаны не все возможные параметры функции. Описание других параметров функции можно найти здесь |
C_EX_SlotManage
Назначение
Позволяет:
- получить расширенную информацию о всех локальных PIN-кодах токена.
- получить информацию об установленном флаге принудительной смене PIN-кода
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SlotManage) (
CK_SLOT_ID slotID,
CK_ULONG ulMode,
CK_VOID_PTR pValue
) |
Параметры
hSession | [in] | дескриптор сессии |
ulMode | [in] | режим работы функции:
|
pValue | [out] |
|
Для режима работы функции MODE_GET_LOCAL_PIN_INFO
в pValue возвращается указатель массив структур типа CK_LOCAL_PIN_INFO
:
ulPinID | [in] | идентификатор PIN-кода |
ulMinSize | [out] | заданная минимальная длина PIN-кода |
ulMaxSize | [out] | заданная максимальная длина PIN-кода |
ulMaxRetryCount | [out] | заданное максимальное значение счетчика неверных попыток ввода пароля |
ulCurrentRetryCount | [out] | текущее значение счетчика оставшихся попыток ввода пароля: 0 – PIN-код заблокирован |
flags | [out] | информационные флаги:
|
Возвращаемые значения
CKR_OK
– функция выполнена успешно.
CKR_PIN_EXPIRED
– если PIN-код нужно сменить смене (MODE_GET_PIN_SET_TO_BE_CHANGED
).
CKR_ARGUMENTS_BAD
– неверно указаны аргументы функции.
Функции для работы с сертификатами
C_EX_GetCertificateInfoText()
Назначение
Функция позволяет получить информацию о сертификате из токена в текстовом виде.
Синтаксис
Code Block |
---|
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_CreateCSR()
Назначение
Создает запрос на выпуск сертификата в центр сертификации и упаковывает его в формат PKCS#10Инициализирует процесс проверки подписи переданных на вход данных в формате PKCS#7.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyInitCreateCSR)( CK_SESSION_HANDLE hSession, hSessionCK_OBJECT_HANDLE hPublicKey, CK_BYTECHAR_PTR pCms*dn, CK_ULONG ulCmsSizednLength, CK_VENDOR_X509BYTE_STORE_PTR pStore*pCsr, CK_VENDORULONG_CRL_MODEPTR ckModepulCsrLength, CK_OBJECT_FLAGS flags ); typedef struct CK_VENDOR_X509_STORE {HANDLE hPrivKey, CK_VENDORCHAR_BUFFER_PTR pTrustedCertificates; // указатель на массив доверенных сертификатов *pAttributes, CK_ULONG ulTrustedCertificateCount; // количество доверенных сертификатов в массивеulAttributesLength, CK_VENDOR_BUFFERCHAR_PTR pCertificates; // указатель на массив, содержащий сертификаты для проверки подписи *pExtensions, 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] | указатель на массив байтов, содержащий сообщение в формате PKCS#7 для проверки |
ulCmsSize | [in] | длина сообщения |
pStore | [in] | указатель на структуру типа CK_VENDOR_X509_STORE, которая содержит указатели на необходимые для проверки подписи доверенные сертификаты, сертификаты подписывающей стороны и списки отозванных сертификатов |
ckMode | [in] | политика проверки списков отозванных сертификатов (CRLs), может принимать следующие значения: OPTIONAL_CRL_CHECK – отсутствие списка отозванных сертификатов не вызывает ошибку при проверке подписи; |
flags | [in] | опции проверки подписи, могут принимать следующие значения: CKF_VENDOR_DO_NOT_USE_INTERNAL_CMS_CERTS – не использовать содержащиеся в CMS сообщении сертификаты для поиска сертификатов подписантов (сертификаты должны быть заданы в структуре CK_VENDOR_X509_STORE); |
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions".
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 |
Примечание
Функция может быть вызвана только из состояний "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 – функция выполнена успешно.
CKR_ARGUMENTS_BAD,
CKR_OPERATION_ACTIVE,
CKR_FUNCTION_FAILED,
CKR_FUNCTION_NOT_SUPPORTED.
Пример
Функции для работы с CMS/PKCS#7 сообщениями
C_EX_
...
PKCS7Sign()
Назначение
Выполняет проверкy присоединенной (attached) подписи Подписывает переданные на вход данные в формате PKCS#7 и возвращает данные, которые были подписаны, и сертификаты подписантов.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyPKCS7Sign)( CK_SESSION_HANDLE hSession, CK_BYTE_PTR_PTR ppDatapData, CK_ULONG_PTR pulDataSizeulDataLen, CK_VENDOR_BUFFER_PTROBJECT_HANDLE hCert, CK_BYTE_PTR ppSignerCertificates *ppEnvelope, CK_ULONG_PTR pulSignerCertificatesCount ); typedef struct CK_VENDOR_BUFFER {pEnvelopeLen, CK_OBJECT_HANDLE hPrivKey, CK_BYTEOBJECT_HANDLE_PTR pData; // указатель на массив байтовphCertificates, CK_ULONG ulCertificatesLen, CK_ULONG ulSize; // длина массива } flags ); |
Параметры
hSession | [in] | дескриптор сессии |
pData | [ |
in] | указатель на байт-массив |
CK_BYTE, содержащий данные |
для подписи | ||
ulDataLen | [in] | длина данных для подписи |
hCert | [in] | дескриптор сертификата |
ppEnvelope | [out] | указатель на байт-массив, в который передаются данные (сообщение) |
pEnvelopeLen | [out] | указатель на длину созданного буфера с сообщением |
hPrivKey | [in] | дескриптор закрытого ключа, соответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата |
phCertificates | [in |
pulDataSize
ppSignerCertificates
] | указатель на массив сертификатов, |
цепочку сертификатов | |
ulCertificatesLen | [ |
in] | количество сертификатов в |
Примечание
параметре phCertificates | ||
flags | [in] | переменная типа CK_ULONG, может принимать следующие значения: 0 – хеширование программное, исходные данные, на которые ссылается указатель pData, сохраняются вместе с подписанным сообщением; |
Примечание
Функция может быть Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions", после вызова функции . Буфер ppEnvelope создается внутри функции. После окончания работы с ним необходимо освободить его, вызвав функцию C_EX_PKCS7VerifyinitFreeBuffer().
Функция поддерживает подпись по следующим алгоритмам: ГОСТ 34.10-2012 с длиной закрытого ключа 256 бит и ГОСТ 34.10-2001 (механизм CKM_GOSTR3410).
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_
...
EX_PKCS7VerifyInit()
Назначение
Инициализирует процесс проверки подписи переданных на вход данных
...
CKR_CERT_CHAIN_NOT_VERIFIED,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_HOST_MEMORY,
CKR_OPERATION_NOT_INITIALIZED,
CKR_SIGNATURE_INVALID.
C_EX_PKCS7VerifyUpdate()
Назначение
Начинает процесс проверки отсоединенной (detached) подписи в формате PKCS#7.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyUpdatePKCS7VerifyInit)( CK_SESSION_HANDLE hSession, CK_BYTE_PTR_PTR pCms, CK_ULONG ppDataulCmsSize, CK_VENDOR_X509_ULONGSTORE_PTR pStore, pulDataSizeCK_VENDOR_CRL_MODE ckMode, CK_FLAGS flags ); |
Параметры
hSession | [in] | дескриптор сессии |
ppData | [in] | указатель на массив байтов, содержащий блок данных, которые были подписаны (EncapsulatedContentInfo) |
pulDataSize | [in] | размер данных |
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions", после вызова функции C_EX_PKCS7VerifyInit. Для завершения процесса проверки подписи необходим вызов функции C_EX_PKCS7Verifyfinal.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
CKR_ARGUMENTS_BAD,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_HOST_MEMORY,
CKR_OPERATION_NOT_INITIALIZED.
C_EX_PKCS7VerifyFinal()
Назначение
Завершает процесс проверки отсоединенной (detached) подписи в формате PKCS#7 и возвращает сертификаты подписантов.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyFinal)( CK_SESSION_HANDLE hSession, CK_VENDOR_BUFFER_PTR_PTR ppSignerCertificates, CK_ULONG_PTR pulSignerCertificatesCount ); 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] | указатель на массив байтов, содержащий |
сообщение в формате PKCS#7 для проверки | |
ulCmsSize | [ |
in] |
количество сертификатов в массиве
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions", после вызова функции C_EX_PKCS7VerifyUpdate.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
CKR_SIGNATURE_INVALID,
CKR_ARGUMENTS_BAD,
CKR_CERT_CHAIN_NOT_VERIFIED,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_HOST_MEMORY,
CKR_OPERATION_NOT_INITIALIZED.
Функции для работы с флеш-памятью
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_GetDriveSize()
Назначение
Возращает размер флеш-памяти токена.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetDriveSize)(
CK_SLOT_ID slotID,
CK_ULONG_PTR pulDriveSize
); |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном |
pulDriveSize | [out] | возвращаемый размер флеш-памяти в Мб |
длина сообщения | ||
pStore | [in] | указатель на структуру типа CK_VENDOR_X509_STORE, которая содержит указатели на необходимые для проверки подписи доверенные сертификаты, сертификаты подписывающей стороны и списки отозванных сертификатов |
ckMode | [in] | политика проверки списков отозванных сертификатов (CRLs), может принимать следующие значения: OPTIONAL_CRL_CHECK – отсутствие списка отозванных сертификатов не вызывает ошибку при проверке подписи; |
flags | [in] | опции проверки подписи, могут принимать следующие значения: CKF_VENDOR_DO_NOT_USE_INTERNAL_CMS_CERTS – не использовать содержащиеся в CMS сообщении сертификаты для поиска сертификатов подписантов (сертификаты должны быть заданы в структуре CK_VENDOR_X509_STORE); |
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions".
Возвращаемые значения
CKR_OK – функция выполнена успешно,
CKR_ARGUMENTS_BAD,
CKR_OPERATION_ACTIVE,
CKR_FUNCTION_FAILED,
CKR_FUNCTION_NOT_SUPPORTED.
Пример
Code Block | ||
---|---|---|
| ||
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()
Разбивает флеш-память токена на независимые разделы с разными правами доступа.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_FormatDrive) (
CK_SLOT_ID slotID,
CK_USER_TYPE userType,
CK_UTF8CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_VOLUME_FORMAT_INFO_EXTENDED_PTR pInitParams,
CK_ULONG ulInitParamsCount
);
typedef struct CK_VOLUME_FORMAT_INFO_EXTENDED
{
CK_ULONG ulVolumeSize;
CK_ACCESS_MODE_EXTENDED accessMode;
CK_OWNER_EXTENDED volumeOwner;
CK_FLAGS flags;
} CK_VOLUME_FORMAT_INFO_EXTENDED; |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном | ||||||||
userType | [in] | тип пользователя, допустимое значение только CKU_SO – глобальный администратор. | ||||||||
pPin | [in] | PIN-код пользователя | ||||||||
ulPinLen | [in] | длина PIN-кода пользователя | ||||||||
pInitParams | [in] | указатель на массив структур типа CK_VOLUME_FORMAT_INFO_EXTENDED, содержащих детальную информацию о разделах
| ||||||||
ulInitParamsCount | [in] | количество записей в массиве |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
CK_ULONG VolumeRWSize = 0; // Размер раздела для чтения и записи
CK_ULONG VolumeROSize = 0; // Размер раздела только для чтения
CK_ULONG VolumeCDSize = 0; // Размер раздела CD-ROM
CK_ULONG VolumeHISize = 0; // Размер раздела скрытого раздела
CK_ULONG CKU_LOCAL_1 = 0x03; // Идентификатор локального пользователя
CK_ULONG CKU_LOCAL_2 = 0x1E; // Идентификатор локального пользователя
/* Шаблон для разметки разделов */
CK_VOLUME_FORMAT_INFO_EXTENDED InitParams[] =
{
{ VolumeRWSize, ACCESS_MODE_RW, CKU_USER, 0 },
{ VolumeROSize, ACCESS_MODE_RO, CKU_SO, 0 },
{ VolumeHISize, ACCESS_MODE_HIDDEN, CKU_LOCAL_1, 0 },
{ VolumeCDSize, ACCESS_MODE_CD, CKU_LOCAL_2, 0 }
};
...
InitParams[0].ulVolumeSize = ulDriveSize / 2;
InitParams[1].ulVolumeSize = ulDriveSize / 4;
InitParams[2].ulVolumeSize = ulDriveSize / 8;
InitParams[3].ulVolumeSize = ulDriveSize - (ulDriveSize / 2) - (ulDriveSize / 4) - (ulDriveSize / 8);
printf("\nFormatting flash memory");
rv = pFunctionListEx->C_EX_FormatDrive( aSlots[0], // Идентификатор слота с подключенным токеном
CKU_SO, // Форматирование выполняется только с правами Администратора
SO_PIN, // Текущий PIN-код Администратора
sizeof(SO_PIN), // Длина PIN-кода Администратора
InitParams, // Массив с информацией о разделах
arraysize(InitParams)); // Размер массива
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n"); |
C_EX_GetVolumesInfo()
Назначение
Возвращает информацию о существующих на флеш-памяти разделах.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetVolumesInfo)(
CK_SLOT_ID slotID,
CK_VOLUME_INFO_EXTENDED_PTR pInfo,
CK_ULONG_PTR pulInfoCount
);
typedef struct CK_VOLUME_INFO_EXTENDED
{
CK_VOLUME_ID_EXTENDED idVolume;
CK_ULONG ulVolumeSize;
CK_ACCESS_MODE_EXTENDED accessMode;
CK_OWNER_EXTENDED volumeOwner;
CK_FLAGS flags;
} CK_VOLUME_INFO_EXTENDED;
|
Параметры
...
slotID
...
[in]
...
идентификатор слота с подключенным токеном
...
pInfo
...
указатель на массива структур типа CK_VOLUME_INFO_EXTENDED
с информацией о разделах:
idVolume | идентификатор раздела, может принимать значения от 1 до 9 |
ulVolumeSize | размер раздела в Мб (не больше общего объема носителя) |
accessMode | флаги доступа к разделу: ACCESS_MODE_RW – доступ на чтение и запись; |
volumeOwner | владелец раздела, имеет права на изменение флага доступа к разделу: CKU_USER – глобальный пользователь; |
flags | остальные флаги |
...
pulInfoCount
...
размер массива
C_EX_PKCS7Verify()
Назначение
Выполняет проверкy присоединенной (attached) подписи в формате 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 | [out] | указатель на массив байтов, содержащий данные, которые были подписаны (EncapsulatedContentInfo) |
pulDataSize | [out] | размер данных |
ppSignerCertificates | [out] | указатель на массив, содержащий сертификаты подписантов |
pulSignerCertificatesCount | [out] | количество сертификатов в массиве |
Примечание
Функция может быть вызвана только из состояний "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_INVALID.
C_EX_PKCS7VerifyUpdate()
Назначение
Начинает процесс проверки отсоединенной (detached) подписи в формате PKCS#7.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyUpdate)(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pData,
CK_ULONG ulDataSize
);
|
Параметры
hSession | [in] | дескриптор сессии |
pData | [in] | указатель на массив байтов, содержащий блок данных, которые были подписаны (EncapsulatedContentInfo) |
ulDataSize | [in] | размер данных |
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions", после вызова функции C_EX_PKCS7VerifyInit. Для завершения процесса проверки подписи необходим вызов функции C_EX_PKCS7Verifyfinal.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
CKR_ARGUMENTS_BAD,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_HOST_MEMORY,
CKR_OPERATION_NOT_INITIALIZED.
C_EX_PKCS7VerifyFinal()
Назначение
Завершает процесс проверки отсоединенной (detached) подписи в формате PKCS#7 и возвращает сертификаты подписантов
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
При вызове функции с пустым указателем pInfo функция возвращает размер массива в pulInfoCount.
Пример
Code Block | ||
---|---|---|
| ||
CK_VOLUME_INFO_EXTENDED_PTR pVolumesInfo = NULL_PTR; // Указатель на массив структур с информацией о разделах
CK_ULONG ulVolumesInfoСount = 0; // Размер массива
printf("\nGetting volumes info");
rv = pFunctionListEx->C_EX_GetVolumesInfo( aSlots[0], // Идентификатор слота с подключенным токеном
NULL_PTR, // Указатель на массив с возвращаемой информацией о разделах
&ulVolumesInfoСount); // Размер массива
pVolumesInfo = (CK_VOLUME_INFO_EXTENDED*)malloc(ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED));
memset(pVolumesInfo,
0,
(ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED)));
rv = pFunctionListEx->C_EX_GetVolumesInfo(aSlots[0], // Идентификатор слота с подключенным токеном
pVolumesInfo, // Указатель на массив с возвращаемой информацией о разделах
&ulVolumesInfoСount); // Размер массива
if (rv != CKR_OK)
{
printf(" -> Failed\n");
}
else
{
printf(" -> OK\n");
for (i = 0; i < (int)ulVolumesInfoСount; i++)
{
printf("\nPrinting volume %1.2d info:\n", (int)i+1);
printf(" Volume id: %2.2d \n", pVolumesInfo[i].idVolume); // Идентификатор раздела
printf(" Volume size: %d Mb \n", pVolumesInfo[i].ulVolumeSize); // Объем раздела
printf(" Access mode: %2.2d \n", pVolumesInfo[i].accessMode); // Права доступа к разделу
printf(" Volume owner: %2.2d \n", pVolumesInfo[i].volumeOwner); // Владелец раздела
printf(" Flags: 0x%8.8X \n", pVolumesInfo[i].flags); // Флаги раздела
}
} |
C_EX_ChangeVolumeAttributes()
Назначение
Функция измененяет флаг доступа к разделу.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_ChangeVolumeAttributes)(
CK_SLOT_ID slotID,
CK_USER_TYPE userType,
CK_UTF8CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_VOLUME_ID_EXTENDED idVolume,
CK_ACCESS_MODE_EXTENDED newAccessMode,
CK_BBOOL bPermanent
); |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном |
userType | [in] | владелец раздела, допустимые значения: CKU_USER – глобальный пользователь; |
pPin | [in] | PIN-код пользователя |
ulPinLen | [in] | длина PIN-кода пользователя |
idVolume | [in] | идентификатор раздела |
newAccessMode | [in] | новые флаги доступа к разделу |
bPermanent | [in] | флаг режима измения атрибута: CK_TRUE – постоянное изменение атрибута доступа, действует вплоть до следующего изменения атрибутов; |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
printf("\nChanging volume attributes");
rv = pFunctionListEx->C_EX_ChangeVolumeAttributes(aSlots[0], // Идентификатор слота с подключенным токеном
CKU_SO, // Владелец раздела
SO_PIN, // PIN-код владельца раздела
sizeof(SO_PIN), // Длина PIN-кода владельца раздела
VolumeRO, // Идентификатор раздела
ACCESS_MODE_RW, // Новые права доступа к разделу
CK_TRUE); // CK_TRUE - постоянное изменение атрибутов, CK_FALSE - временное изменение атрибутов
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n"); |
Функции для работы с журналом
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_GetJournal()
Назначение
Функция возвращает журнал операций.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetJournalPKCS7VerifyFinal)( CK_SLOTSESSION_ID slotID, CK_BYTE_PTR pJournal, CK_ULONG_PTR pulJournalSize ); |
Параметры
HANDLE hSession,
CK_VENDOR_BUFFER_PTR_PTR ppSignerCertificates,
CK_ULONG_PTR pulSignerCertificatesCount
);
|
Параметры
hSession | [in] | дескриптор сессии |
ppSignerCertificates |
slotID
[out] | указатель на |
массив, содержащий сертификаты подписантов | |
pulSignerCertificatesCount | [out] |
количество сертификатов в массиве |
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions", после вызова функции C_EX_PKCS7VerifyUpdate.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
Перед выполнением функции должна быть выполнена авторизация пользователя с правами владельца ключевой пары журнала (Пользователь). Формат возвращаемой записи журнала и пример парсинга доступны по ссылке.
Пример
выполнена успешно.
CKR_SIGNATURE_INVALID,
CKR_ARGUMENTS_BAD,
CKR_CERT_CHAIN_NOT_VERIFIED,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_HOST_MEMORY,
CKR_OPERATION_NOT_INITIALIZED.
Функции для работы с флеш-памятью
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_GetDriveSize()
Назначение
Возвращает размер флеш-памяти токена.
Синтаксис
Code Block | ||
---|---|---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetDriveSize)(
CK_SLOT_ID | ||
Code Block | ||
| ||
CK_BYTE_PTR pJournal = NULL_PTR; // Указатель на значение журнала CK_ULONG ulJournalSize = 0; // Размер журнала while(TRUE) { ... /* Получить размер журнала */ printf("Getting journal size"); rv = pFunctionListEx->C_EX_GetJournal(aSlots[0], // Хэндл слота с подключенным токеном NULL_PTR, // Указатель на журнал slotID, CK_ULONG_PTR pulDriveSize &ulJournalSize);// Размер журнала if (rv != CKR_OK) { ); |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном |
pulDriveSize | [out] | возвращаемый размер флеш-памяти в Мб |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
CK_ULONG ulDriveSize = 0; printf(" -> Failed\n"); break; // Общий объем }флеш-памяти printf("Get Flash -> OK\nmemory size"); rv = pFunctionListEx->C_EX_GetDriveSize(aSlots[0], // pJournalИдентификатор слота с подключенным токеном &ulDriveSize); // Возвращаемый размер флеш-памяти в Мб if (rv != CKR_OK) printf(" -> Failed\n"); else { printf(" -> OK\n"); printf("Memory size: %d Mb\n", (int)ulDriveSize); } |
C_EX_FormatDrive()
Разбивает флеш-память токена на независимые разделы с разными правами доступа.
Info | ||
---|---|---|
| ||
После окончания работы этой функции происходит переподключение токена. Нет никаких гарантий, что работу с этим токеном можно производить по старому SLOT_ID: он может начать указывать на другой токен или не быть валидным вовсе. Новый SLOT_ID токена можно найти, например, по серийному номеру. |
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_FormatDrive) ( CK_SLOT_ID slotID, CK_USER_TYPE = (CK_BYTE*)malloc(ulSlotCount * sizeof(CK_BYTE)); if (pJournal == NULL) { printf("Memory allocation for pJournal failed! \n"); break; } memset(pJournal, 0, (ulJournalSize * sizeof(CK_BYTE))); /* Получить журнал */ printf("Getting journal"); rv = pFunctionListEx->C_EX_GetJournal(aSlots[0], // Хэндл слота с подключенным токеном userType, CK_UTF8CHAR_PTR pPin, CK_ULONG pJournal, // Указатель на журнал ulPinLen, CK_VOLUME_FORMAT_INFO_EXTENDED_PTR pInitParams, CK_ULONG &ulJournalSizeulInitParamsCount );// Размер журнала typedef struct CK_VOLUME_FORMAT_INFO_EXTENDED { CK_ULONG if (rv != CKR_OK) { ulVolumeSize; CK_ACCESS_MODE_EXTENDED accessMode; printf(" -> Failed %X\n", (int)rv); CK_OWNER_EXTENDED breakvolumeOwner; } CK_FLAGS printf(" -> OK\n"); ... breakflags; } |
Функции для работы с подписью без отображения
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_SignInvisibleInit()
Назначение
Функция инициализирует процесс подписи сообщения без отображения на экране.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SignInvisibleInit)(
CK_SESSION_HANDLE hSession,
CK_MECHANISM_PTR pMechanism,
CK_OBJECT_HANDLE hKey
);
|
Параметры
CK_VOLUME_FORMAT_INFO_EXTENDED; |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном | ||||||||
userType | [in] | тип пользователя, допустимое значение только CKU_SO – глобальный администратор. | ||||||||
pPin | [in] | PIN-код пользователя | ||||||||
ulPinLen | [in] | длина PIN-кода пользователя | ||||||||
pInitParams | [in] | указатель на массив структур типа CK_VOLUME_FORMAT_INFO_EXTENDED, содержащих детальную информацию о разделах
| ||||||||
ulInitParamsCount | [in] | количество записей в массиве |
hSession
pMechanism
hKey
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
/* Набор параметров КриптоПро алгоритма ГОСТ Р 34.11-1994 */ CK_BYTECK_ULONG VolumeRWSize = 0; // Размер раздела для чтения и записи CK_ULONG VolumeROSize = 0; GOST3411params[] = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x01 }; /* Механизм подписи подписи по алгоритму ГОСТ Р 34.10-2001 с хешированием по алгоритму ГОСТ Р 34.11-94*/ CK_MECHANISM HashSigVerMech = {CKM_GOSTR3410_WITH_GOSTR3411, GOST3411params, sizeof(GOST3411params)}; while(TRUE) { ... /* Инициализировать операцию подписи данных */ printf("C_EX_SignInvisibleInit"); rv = pFunctionList->C_EX_SignInvisibleInit(hSession, // Хэндл сессии // Размер раздела только для чтения CK_ULONG VolumeCDSize = 0; // Размер раздела CD-ROM CK_ULONG VolumeHISize = 0; // Размер раздела скрытого раздела CK_ULONG CKU_LOCAL_1 = 0x03; // Идентификатор локального пользователя CK_ULONG CKU_LOCAL_2 = 0x1E; // Идентификатор локального пользователя /* Шаблон для разметки разделов */ CK_VOLUME_FORMAT_INFO_EXTENDED InitParams[] = { { VolumeRWSize, ACCESS_MODE_RW, CKU_USER, 0 }, { VolumeROSize, ACCESS_MODE_RO, CKU_SO, 0 &HashSigVerMech , // Механизм подписи hPrivateKey ); // Хэндл закрытого ключа }, { VolumeHISize, ACCESS_MODE_HIDDEN, CKU_LOCAL_1, 0 }, { VolumeCDSize, ACCESS_MODE_CD, CKU_LOCAL_2, 0 } }; ... InitParams[0].ulVolumeSize = ulDriveSize / 2; InitParams[1].ulVolumeSize = ulDriveSize / 4; InitParams[2].ulVolumeSize = ulDriveSize / 8; InitParams[3].ulVolumeSize = ulDriveSize - (ulDriveSize / 2) - (ulDriveSize / 4) - (ulDriveSize / 8); printf("\nFormatting flash memory"); rv = pFunctionListEx->C_EX_FormatDrive( aSlots[0], // Идентификатор слота с подключенным токеном CKU_SO, // Форматирование выполняется только с правами Администратора SO_PIN, // Текущий PIN-код Администратора sizeof(SO_PIN), // Длина PIN-кода Администратора InitParams, // Массив с информацией о разделах arraysize(InitParams)); // Размер массива if (rv != CKR_OK) { printf(" -> Failed\n"); break; } else printf(" -> OK\n"); } |
C_EX_
...
GetVolumesInfo()
Назначение
Функция осуществляет процесс подписи сообщения без отображения на экране, вызывается после функции C_EX_SignInvisibleInit.
Возвращает информацию о существующих на флеш-памяти разделах.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SignInvisibleGetVolumesInfo)( CK_SESSIONSLOT_HANDLEID hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pSignatureslotID, CK_VOLUME_INFO_ULONGEXTENDED_PTR pulSignatureLen ); |
Параметры
hSession | [in] | дескриптор сессии |
pData | [in] | указатель на буфер данных для подписи |
ulDataLen | [in] | размер данных для подписи в байтах |
pSignature | [out] | указатель на буфер с подписью |
pulSignatureLen | [out] | размер буфера с подписью |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
...
collapse | true |
---|
...
pInfo, CK_ULONG_PTR pulInfoCount ); typedef struct CK_VOLUME_INFO_EXTENDED { CK_VOLUME_ID_EXTENDED idVolume; CK_ULONG |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
ulVolumeSize; CK_ACCESS_MODE_EXTENDED accessMode; CK_OWNER_EXTENDED volumeOwner; CK_FLAGS |
...
|
...
|
...
|
...
|
...
|
...
|
...
flags; |
...
|
...
} CK_VOLUME_INFO_EXTENDED;
|
Параметры
slotID | [in] | идентификатор слота с подключенным токеном | ||||||||||
pInfo | [out] | указатель на массива структур типа
| ||||||||||
pulInfoCount | [out] | размер массива |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
При вызове функции с пустым указателем pInfo функция возвращает размер массива в pulInfoCount.
Пример
Code Block | ||
---|---|---|
| ||
CK_VOLUME_INFO_EXTENDED_PTR pVolumesInfo = NULL_PTR; // Указатель на массив структур с информацией о разделах CK_ULONG |
...
ulVolumesInfoСount |
...
= 0; // Размер массива printf("\nGetting volumes info"); rv = pFunctionListEx->C_EX_GetVolumesInfo( aSlots[0], // Идентификатор слота с подключенным токеном NULL_PTR, // Указатель на массив с возвращаемой информацией о разделах &ulVolumesInfoСount); // Размер массива pVolumesInfo = (CK_VOLUME_INFO_EXTENDED*)malloc(ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED)); memset(pVolumesInfo, 0, (ulVolumesInfoСount * sizeof(CK_VOLUME_INFO_EXTENDED))); rv = pFunctionListEx->C_EX_GetVolumesInfo(aSlots[0], // Идентификатор слота с подключенным токеном pVolumesInfo, // Указатель на массив с возвращаемой информацией о разделах &ulVolumesInfoСount); // Размер массива if (rv != CKR_OK) { printf(" -> Failed\n"); } else { printf(" -> OK\n"); for (i = 0; i < (int)ulVolumesInfoСount; i++) { printf("\nPrinting volume %1.2d info:\n", (int)i+1); printf(" Volume id: %2.2d \n", pVolumesInfo[i].idVolume); // |
...
Идентификатор раздела |
...
|
...
|
...
printf(" Volume size: %d Mb \n", pVolumesInfo[i].ulVolumeSize); // Объем раздела printf(" Access mode: %2.2d \n", pVolumesInfo[i].accessMode); // Права доступа к разделу printf(" Volume owner: %2.2d |
...
\n", pVolumesInfo[i].volumeOwner); // |
...
Владелец |
...
раздела printf(" Flags: 0x%8.8X \n", pVolumesInfo[i].flags); // |
...
Флаги раздела
}
} |
C_EX_ChangeVolumeAttributes()
Назначение
Функция измененяет флаг доступа к разделу.
Info | ||
---|---|---|
| ||
После изменения доступа к разделу на постоянной основе происходит переподключение токена. Нет никаких гарантий, что работу с этим токеном можно производить по старому SLOT_ID: он может начать указывать на другой токен или не быть валидным вовсе. Новый SLOT_ID токена можно найти, например, по серийному номеру. |
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_ChangeVolumeAttributes)( CK_SLOT_ID slotID, CK_USER_TYPE |
...
userType, CK_UTF8CHAR_PTR pPin, CK_ULONG |
...
ulPinLen, CK_VOLUME_ID_EXTENDED |
...
|
...
|
...
|
...
idVolume, |
...
CK_ACCESS_MODE_EXTENDED newAccessMode, CK_BBOOL |
...
bPermanent
); |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном |
userType | [in] | владелец раздела, допустимые значения: CKU_USER – глобальный пользователь; |
pPin | [in] | PIN-код пользователя |
ulPinLen | [in] | длина PIN-кода пользователя |
idVolume | [in] | идентификатор раздела |
newAccessMode | [in] | новые флаги доступа к разделу |
bPermanent | [in] | флаг режима измения атрибута: CK_TRUE – постоянное изменение атрибута доступа, действует вплоть до следующего изменения атрибутов; |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
printf("\nChanging volume attributes"); rv = pFunctionListEx->C_EX_ChangeVolumeAttributes(aSlots[0], // Идентификатор слота с подключенным токеном |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
CKU_SO, // Владелец раздела |
...
|
...
|
...
|
...
SO_PIN, // |
...
PIN-код владельца раздела |
...
sizeof( |
...
SO_PIN), |
...
// Длина |
...
PIN-кода владельца раздела |
...
VolumeRO, // |
...
Идентификатор раздела |
...
ACCESS_MODE_RW, // |
...
Новые права доступа к разделу |
...
...
|
...
...
|
...
|
...
|
...
|
...
|
...
CK_TRUE); // CK_TRUE - постоянное изменение атрибутов, CK_FALSE - временное изменение атрибутов
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n"); |
Функции для работы с журналом
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_GetJournal()
Назначение
Функция возвращает журнал операций
...
Функции для работы с беспроводным каналом связи
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_LoadActivationKey()
Назначение
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается только в 20-й версии прошивки)
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_LoadActivationKey)(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR key,
CK_ULONG keySize
); |
Параметры
hSession | [in] | дескриптор сессии |
key | [in] | указатель на пароль |
keySize | [in] | длина пароля |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_SetActivationPassword()
Назначение
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается с 21-й версии прошивки).
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SetActivationPasswordGetJournal)( CK_SLOT_ID slotID, CK_UTF8CHAR_PTR password ); |
Параметры
hSession | [in] | дескриптор сессии |
password | [in] | пароль активации |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_GenerateActivationPassword()
Назначение
Генерирует пароль для активации защищенного канала связи с токеном.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GenerateActivationPassword)( CK_SESSION_HANDLEBYTE_PTR hSession,pJournal, CK_ULONG_PTR pulJournalSize ulPasswordNumber, CK_UTF8CHAR_PTR pPassword, CK_ULONG_PTR pulPasswordSize, CK_ULONG ulPasswordCharacterSet ); |
Параметры
hSession | [in] | дескриптор сессии |
ulPasswordNumber | порядковый номер генерируемого пароля. Допустимые значения от 1 до 6 и
| |
pPassword | [out] | указатель на буфер, содержащий сгенерированный пароль |
pulPasswordSize | [out] | размер буфера |
ulPasswordCharacterSet | [in] | набор допустимых символов:
|
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_TokenManage()
Назначение
Управляет режимом работы токена и таймаутом беспроводного соединения Рутокен Bluetooth.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_TokenManage)(
CK_SESSION_HANDLE hSession,
CK_ULONG ulMode,
CK_VOID_PTR pValue
); |
Параметры
hSession | [in] | дескриптор сессии |
ulMode | [in] | режим работы функции:
|
pValue | [in] |
1 .. 0х46 – произвольное значение в минутах, от 1 минуты до 70 минут
|
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Функции системного назначeния
C_EX_SlotManage
Назначение
); |
Параметры
slotID | [in] | идентификатор слота |
pJournal | [out] | указатель на запись журнала |
pulJournalSize | [out] | размер записи журнала |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
Журнал позволяет хранить только одну запись с информацией о последней выполненной операции подписи. Неудачные попытки подписи в журнале не фиксируются. Описание формата записи журнала доступно по ссылке.
Для получения записи журнала необходимо вызвать функцию C_EX_GetJournal()
с переданными в нее значением слота, к которому подключен Рутокен ЭЦП, и данными буфера, в который будет возвращена запись журнала. Вызов функции C_EX_GetJournal()
с указателем на NULL
вместо буфера вернет длину записи журнала.
Перед запросом информации о журнале необходимо выполнить аутентификацию Пользователем.
Получение значения журнала
|
Функции для работы с беспроводным каналом связи
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_LoadActivationKey()
Назначение
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается только в 20-й версии прошивки)Позволяет выполнить расширенную инициализацию токена, получить значение имитовставки токена и расширенную информацию о всех локальных PIN-кодах токена.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SlotManageLoadActivationKey)( CK_SESSION_HANDLE hSession, CK_ULONGBYTE_PTR ulModekey, CK_VOID_PTRULONG pValuekeySize ); |
Параметры
hSession |
ulMode
режим работы функции:
MODE_GET_LOCAL_PIN_INFO
– получение информации о локальных PIN-кодах
pValue
Для режима работы функции MODE_GET_LOCAL_PIN_INFO
в pValue возвращается указатель массив структур типа CK_LOCAL_PIN_INFO
:
[in] |
идентификатор PIN-кода
дескриптор сессии | |
key | [ |
in] |
заданная минимальная длина PIN-кода
указатель на пароль | |
keySize | [ |
in] |
заданная максимальная длина PIN-кода
ulMaxRetryCount
ulCurrentRetryCount
текущее значение счетчика оставшихся попыток ввода пароля:
0 – PIN-код заблокирован
flags
информационные флаги:
LOCAL_PIN_FLAGS_NOT_DEFAULT
– локальный PIN-код не является PIN-кодом по умолчаниюLOCAL_PIN_FLAGS_FROM_SCREEN
– PIN-код может введен только с экрана
длина пароля |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_SetActivationPassword()
Назначение
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается с 21-й версии прошивки).
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SetActivationPassword)(
CK_SLOT_ID slotID,
CK_UTF8CHAR_PTR password
); |
Параметры
hSession | [in] | дескриптор сессии |
password | [in] | пароль активации |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
C_EX_
...
GenerateActivationPassword()
Назначение
Генерирует сессионный ключ, вычисляет ключ согласования, шифрует сессионный ключ ключом согласования и возвращает указатель на дескриптор сессионного ключа, хранящегося в оперативной памяти токенапароль для активации защищенного канала связи с токеном.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_WrapKeyGenerateActivationPassword)( CK_SESSION_HANDLE hSession, CK_MECHANISMSESSION_PTR pGenerationMechanism, CK_ATTRIBUTE_PTR pKeyTemplate, HANDLE hSession, CK_ULONG ulKeyAttributeCount ulPasswordNumber, CK_MECHANISMUTF8CHAR_PTR pDerivationMechanism, CK_OBJECT_HANDLE hBaseKey, pPassword, CK_MECHANISMULONG_PTR pWrappingMechanism, CK_BYTE_PTR pWrappedKey pulPasswordSize, CK_ULONG_PTR pulWrappedKeyLen, CK_OBJECT_HANDLE_PTR phKey ulPasswordCharacterSet ); |
Параметры
hSession | [in] | дескриптор сессии |
pGenerationMechanism
механизм генерации сессионного ключа. Допустимое значение:
CKM_GOST28147_KEY_GEN – по стандарту ГОСТ 28147-89
ulPasswordNumber | порядковый номер генерируемого пароля. Допустимые значения от 1 до 6 и
| |
pPassword | [out |
pKeyTemplate
] | указатель на буфер, содержащий |
сгенерированный пароль | |
pulPasswordSize | [ |
out] |
размер буфера | |
ulPasswordCharacterSet | [in] |
набор допустимых символов |
: |
|
|
CKM_GOSTR3410_12_DERIVE – по стандарту ГОСТ Р 34.10-2012
hBaseKey
pWrappingMechanism
pWrappedKey
pulWrappedKeyLen
длина зашифрованного сессионного ключа
phKey
...
|
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_TokenManage()
Anchor | ||||
---|---|---|---|---|
|
...
|
Назначение
Вычисляет ключ согласования, расшифровывает зашифрованный сессионный ключ и возвращает указатель на дескриптор расшифрованного сессионного ключа, хранящего в оперативной памяти токена.
Управляет режимом работы токена и таймаутом беспроводного соединения Рутокен Bluetooth.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_UnwrapKeyTokenManage)( CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pDerivationMechanism, CK_OBJECT_HANDLE hBaseKey, CK_MECHANISM_PTR pUnwrappingMechanism, CK_BYTE_PTR pWrappedKey, CK_ULONG ulWrappedKeyLen, CK_ATTRIBUTE_PTR pKeyTemplate, CK_ULONG ulKeyAttributeCount, CK_OBJECT_HANDLE_PTR phKeyULONG ulMode, CK_VOID_PTR pValue ); |
Параметры
hSession | [in] | дескриптор сессии |
ulMode | [in] |
механизм выработки ключа согласования (KEK). Допустимые значения:
CKM_GOSTR3410_DERIVE – по стандарту ГОСТ Р 34.10-2001
CKM_GOSTR3410_12_DERIVE – по стандарту ГОСТ Р 34.10-2012
режим работы функции:
| |
pValue | [in] |
pUnwrappingMechanism
механизм расшифрования зашифрованного сессионного ключа
pWrappedKey
ulWrappedKeyLen
pKeyTemplate
ulKeyAttributeCount
phKey
1 .. 0х46 – произвольное значение в минутах, от 1 минуты до 70 минут
|
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Info | ||
---|---|---|
| ||
Здесь описаны не все возможные параметры функции. Описание других параметров функции можно найти здесь |
Вспомогательные функции
C_EX_FreeBuffer()
Назначение
Функция освобождает память, выделенную другими расширенными функциями, например C_EX_GetCertificateInfoText.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_FreeBuffer)( CK_BYTE_PTR pBuffer ); |
Параметры
pBuffer | [in] | указатель на буфер |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
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"); |