...
Функция позволяет получить специфическую для устройств Рутокен информацию: класс токена, количество свободной и общей памяти, тип токена, номер протокола, количество оставшихся попыток ввода пин-кода Пользователя и Администратора и т.д. По сравнению с похожей по назначению стандартной функции C_GetTokenInfo функция расширения предоставляет более полную информацию о токене.
...
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-кода пользователя.
...
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_
...
Для режима работы функции 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
:
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.
Синтаксис
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, |
Возвращаемые значения
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 hCerthPrivKey, CK_CHAR_PTR* pInfo*pAttributes, CK_ULONG_PTR pulInfoLen ulAttributesLength, CK_CHAR_PTR *pExtensions, CK_ULONG ulExtensionsLength ); |
Параметры
hSession | [in] | дескриптор сессии |
hCert hPublicKey | [in] | дескриптор объекта (сертификата) |
pInfo | [out] | указатель на буфер, содержащий текстовую информацию о сертификате |
pulInfoLen | [out] | размер буфера, в байтах |
Примечание
Функция может быть вызвана из любого состояния. Так как память для массива выделяется внутри функции, по окончании работы функции pInfo нужно высвободить функцией C_EX_FreeBuffer.
C_EX_CreateCSR()
Назначение
Создает запрос на выпуск сертификата в центр сертификации и упаковывает его в формат PKCS#10.
Синтаксис
открытого ключа для создания сертификата | ||
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 |
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 *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 ); |
Параметры
hSession | [in] | дескриптор сессии | |
pData | [in] | указатель на байт-массив CK_BYTE, содержащий данные для подписи | |
ulDataLen | [in] | длина данных для подписи | |
hCerthPublicKey | [in] | дескриптор открытого ключа для создания сертификата | |
dnppEnvelope | [inout] | уникальное имя – массив строк, где в первой строке располагается тип поля в текстовом формате или идентификатор объекта (CN или «2.5.4.3»). Во второй строке должно находиться значение поля в кодировке UTF8. Последующие поля передаются аналогично, количество строк должно быть кратно двум | |
dnLength | [in] | количество строк в массиве, на который ссылается параметр dn | |
указатель на байт-массив, в который передаются данные (сообщение) | |||
pEnvelopeLen | [out] | указатель на длину созданного буфера с сообщением | |
hPrivKey | [in] | дескриптор закрытого ключа, соответствующего указанному сертификату. Если равен 0, то закрытый ключ будет искаться по ID сертификата | |
phCertificatespCsr | [in] | указатель на указатель на массив байт, в который будет записан созданный запрос на сертификатсертификатов, цепочку сертификатов | |
ulCertificatesLenpulCsrLength | [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, сохраняются вместе с подписанным сообщением; |
Примечание
Функция может быть вызвана только из состояний "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.
Синтаксис
Code Block |
---|
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; // длина массива
}
|
Параметры
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".
Возвращаемые значения
CKR_OK – функция выполнена успешно,
CKR_ARGUMENTS_BAD,
CKR_OPERATION_ACTIVE,
CKR_FUNCTION_FAILED,
CKR_FUNCTION_NOT_SUPPORTED.
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
);
|
Примечание
Функция может быть вызвана только из состояний "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.
Синтаксис
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] | дескриптор сессии |
pCmsppData | [inout] | указатель на массив байтов, содержащий сообщение в формате 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".
Возвращаемые значения
CKR_OK – функция выполнена успешно.
CKR_ARGUMENTS_BAD,
CKR_OPERATION_ACTIVE,
CKR_FUNCTION_FAILED,
данные, которые были подписаны (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_INVALIDCKR_FUNCTION_NOT_SUPPORTED.
C_EX_
...
PKCS7VerifyUpdate()
Назначение
Выполняет проверкy присоединенной (attachedНачинает процесс проверки отсоединенной (detached) подписи в формате PKCS#7 и возвращает данные, которые были подписаны, и сертификаты подписантов.
Синтаксис
Code Block |
---|
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 ); |
Параметры
hSession | [in] | дескриптор сессии |
ppDatapData | [outin] | указатель на массив байтов, содержащий данныеблок данных, которые были подписаны (EncapsulatedContentInfo) |
pulDataSizeulDataSize | [outin] | размер данных |
ppSignerCertificates | [out] | указатель на массив, содержащий сертификаты подписантов |
pulSignerCertificatesCount | [out] | количество сертификатов в массиве |
Примечание
Примечание
Функция может быть вызвана только из состояний Функция может быть вызвана только из состояний "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 и возвращает сертификаты подписантов.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_PKCS7VerifyUpdatePKCS7VerifyFinal)( CK_SESSION_HANDLE hSession, CK_VENDOR_BYTEBUFFER_PTR_PTR pDatappSignerCertificates, CK_ULONG_PTR ulDataSizepulSignerCertificatesCount ); |
Параметры
hSession | [in] | дескриптор сессии |
pDatappSignerCertificates | [inout] | указатель на массив байтов, содержащий блок данных, которые были подписаны (EncapsulatedContentInfo)сертификаты подписантов |
pulSignerCertificatesCountulDataSize | [inout] | размер данных количество сертификатов в массиве |
Примечание
Функция может быть вызвана только из состояний "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.
Функции для работы с флеш-памятью
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_
...
GetDriveSize()
Назначение
Завершает процесс проверки отсоединенной (detached) подписи в формате PKCS#7 и возвращает сертификаты подписантовВозвращает размер флеш-памяти токена.
Синтаксис
Code Block |
---|
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 ); |
Параметры
hSession slotID | [in] | дескриптор сессии | идентификатор слота с подключенным токеном |
pulDriveSizeppSignerCertificates | [out] | указатель на массив, содержащий сертификаты подписантов | |
pulSignerCertificatesCount | [out] | количество сертификатов в массиве |
Примечание
...
возвращаемый размер флеш-памяти в Мб |
Возвращаемые значения
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] | возвращаемый размер флеш-памяти в Мб |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Пример
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()
Разбивает флеш-память токена на независимые разделы с разными правами доступа.
Info | ||
---|---|---|
| ||
После окончания работы этой функции происходит переподключение токена. Нет никаких гарантий, что работу с этим токеном можно производить по старому SLOT_ID: он может начать указывать на другой токен или не быть валидным вовсе. Новый SLOT_ID токена можно найти, например, по серийному номеру. |
Синтаксис
Code Block | ||
---|---|---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_FormatDrive) (
CK_SLOT_ID | ||
Code Block | ||
| ||
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()
Разбивает флеш-память токена на независимые разделы с разными правами доступа.
Синтаксис
Code Block |
---|
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 ; |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном |
userType | [in] | тип пользователя, допустимое значение только CKU_SO – глобальный администратор. |
pPin | [in] | PIN-код пользователя |
ulPinLen | [in] | длина PIN-кода пользователя |
pInitParams | [in] | указатель на массив структур типа CK_VOLUME_FORMAT_INFO_EXTENDED |
...
, содержащих детальную информацию о разделах |
Параметры
slotID | [in] | идентификатор слота с подключенным токеном | ||||||||||
userType | [in] | тип пользователя, допустимое значение только
| ||||||||||
pPin | [in] | PIN-код пользователя | ||||||||||
| ||||||||||||
ulInitParamsCountulPinLen | [in] | длина PIN-кода пользователя | pInitParams | [in] |
ulVolumeSize | размер раздела в Мб |
accessMode | флаги доступа к разделу: ACCESS_MODE_RW – доступ на чтение и запись; |
volumeOwner | владелец раздела, имеет права на изменение флага доступа к разделу: CKU_USER – глобальный пользователь; |
flags | остальные флаги |
ulInitParamsCount
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
количество записей в массиве |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
CK_ULONG VolumeRWSize = 0; // Размер раздела для чтения и записи
CK_ULONG VolumeROSize = 0; // Размер раздела только для чтения
CK_ULONG VolumeCDSize | ||
Code Block | ||
| ||
CK_ULONG VolumeRWSize = 0; // Размер раздела для чтения и записиCD-ROM CK_ULONG VolumeROSizeVolumeHISize = 0; // Размер раздела только для чтенияскрытого раздела CK_ULONG VolumeCDSize = 0; CKU_LOCAL_1 = 0x03; // Идентификатор // Размер раздела 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"); |
...
Функция измененяет флаг доступа к разделу.
Info |
---|
Синтаксис
| ||
После изменения доступа к разделу на постоянной основе происходит переподключение токена. Нет никаких гарантий, что работу с этим токеном можно производить по старому SLOT_ID: он может начать указывать на другой токен или не быть валидным вовсе. Новый SLOT_ID токена можно найти, например, по серийному номеру. |
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_ |
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
); |
...
Code Block | ||
---|---|---|
| ||
printf("\nChanging volume attributes"); rv = pFunctionListEx->C_EX_ChangeVolumeAttributes(aSlots[0], // Идентификатор слота с подключенным токеном CKU_SO, // Владелец раздела SO_PIN, // PIN-код владельца раздела \nChanging volume attributes"); rv = pFunctionListEx->C_EX_ChangeVolumeAttributes(aSlots[0], sizeof(SO_PIN), // Идентификатор Длинаслота PIN-кодас владельцаподключенным разделатокеном VolumeROCKU_SO, // ИдентификаторВладелец раздела ACCESSSO_MODE_RW, // Новые права доступа к разделу PIN, // PIN-код 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_GetJournal)( CK_SLOT_IDвладельца раздела slotID, sizeof(SO_PIN), // Длина PIN-кода владельца раздела CK_BYTE_PTR pJournal, CK_ULONG_PTR pulJournalSize ); |
Параметры
...
slotID
...
pJournal
...
pulJournalSize
...
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
Формат возвращаемой записи журнала и пример парсинга доступны по ссылке.
Пример
Code Block | ||
---|---|---|
| ||
CK_BYTE_PTR pJournal = NULL_PTR; VolumeRO, // Указатель на значение журнала CK_ULONG Идентификатор раздела ulJournalSize = 0; ACCESS_MODE_RW, // Размер журнала while(TRUE) { ... Новые права доступа к разделу /* Получить размер журнала */ printf("Getting journal size"); rv = pFunctionListEx->C_EX_GetJournal(aSlots[0], // Хэндл слота с подключенным токеном CK_TRUE); // CK_TRUE - постоянное изменение атрибутов, CK_FALSE - временное изменение атрибутов if (rv != CKR_OK) printf(" -> Failed\n"); else printf(" NULL_PTR, // Указатель на журнал -> OK\n"); |
Функции для работы с журналом
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_GetJournal()
Назначение
Функция возвращает журнал операций.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetJournal)( CK_SLOT_ID slotID, &ulJournalSize);// Размер журнала if (rv != CKR_OK) { printf(" -> Failed\n"); break; CK_BYTE_PTR } printf(" -> OK\n"); pJournal, pJournal = (CK_BYTE*)malloc(ulSlotCount * sizeof(CK_BYTE)); _ULONG_PTR ifpulJournalSize (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], // Хэндл слота с подключенным токеном pJournal, // Указатель на журнал &ulJournalSize);// Размер журнала if (rv != CKR_OK) { printf(" -> Failed %X\n", (int)rv); break; } printf(" -> OK\n"); ... break; } |
Функции для работы с беспроводным каналом связи
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_SetActivationPassword)(
CK_SLOT_ID slotID,
CK_UTF8CHAR_PTR password
); |
Параметры
hSession | [in] | дескриптор сессии |
password | [in] | пароль активации |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_GenerateActivationPassword()
Назначение
); |
Параметры
slotID | [in] | идентификатор слота |
pJournal | [out] | указатель на запись журнала |
pulJournalSize | [out] | размер записи журнала |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Примечания
Журнал позволяет хранить только одну запись с информацией о последней выполненной операции подписи. Неудачные попытки подписи в журнале не фиксируются. Описание формата записи журнала доступно по ссылке.
Для получения записи журнала необходимо вызвать функцию C_EX_GetJournal()
с переданными в нее значением слота, к которому подключен Рутокен ЭЦП, и данными буфера, в который будет возвращена запись журнала. Вызов функции C_EX_GetJournal()
с указателем на NULL
вместо буфера вернет длину записи журнала.
Перед запросом информации о журнале необходимо выполнить аутентификацию Пользователем.
Получение значения журнала
|
Функции для работы с беспроводным каналом связи
AUI Button | ||||||
---|---|---|---|---|---|---|
|
C_EX_LoadActivationKey()
Назначение
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается только в 20-й версии прошивки)Генерирует пароль для активации защищенного канала связи с токеном.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GenerateActivationPasswordLoadActivationKey)( CK_SESSION_HANDLE hSession, CK_ULONG ulPasswordNumber, CK_UTF8CHARBYTE_PTR pPassword, CK_ULONG_PTR pulPasswordSizekey, CK_ULONG ulPasswordCharacterSet ); |
Параметры
...
hSession
...
ulPasswordNumber
...
порядковый номер генерируемого пароля. Допустимые значения от 1 до 6 и
GENERATE_NEXT_PASSWORD
– генерировать следующий пароль (только для 21-й версии микропрограммы)
...
pPassword
...
pulPasswordSize
...
ulPasswordCharacterSet
...
набор допустимых символов:
CAPS_AND_DIGITS
– заглавные буквы латинского алфавита без O и цифры без 0CAPS_ONLY
– заглавные буквы латинского алфавита
keySize
); |
Параметры
hSession | [in] | дескриптор сессии |
key | [in] | указатель на пароль |
keySize | [in] | длина пароля |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
C_EX_
...
SetActivationPassword()
Назначение
Управляет режимом работы токена и таймаутом беспроводного соединения Рутокен Bluetooth.
...
Активирует защищенный канал связи с токеном с использованием пароля (поддерживается с 21-й версии прошивки).
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_TokenManageSetActivationPassword)( CK_SESSION_HANDLE hSession, CK_ULONG SLOT_ID ulModeslotID, CK_VOIDUTF8CHAR_PTR pValuepassword ); |
Параметры
...
hSession | [in] | дескриптор сессии |
password | [in] | пароль активации |
hSession | [in] | дескриптор сессии |
ulMode | [in] | режим работы функции:
|
pValue | [in] |
1 .. 0х46 – произвольное значение в минутах, от 1 минуты до 70 минут
CHANNEL_TYPE_USB – по шине USBCHANNEL_TYPE_BLUETOOTH – по Bluetooth |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Функции для работы с ключами в оперативной памяти
C_EX_
...
GenerateActivationPassword()
Назначение
Генерирует сессионный ключ, вычисляет ключ согласования, шифрует сессионный ключ ключом согласования и возвращает указатель на дескриптор сессионного ключа, хранящегося в оперативной памяти токенапароль для активации защищенного канала связи с токеном.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_WrapKey)( CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pGenerationMechanism, CK_ATTRIBUTE_PTR pKeyTemplate, CK_ULONG ulKeyAttributeCount, GenerateActivationPassword)( CK_MECHANISM_PTR pDerivationMechanismSESSION_HANDLE hSession, CK_OBJECT_HANDLE hBaseKey, ULONG ulPasswordNumber, CK_MECHANISMUTF8CHAR_PTR pWrappingMechanism pPassword, CK_BYTEULONG_PTR pWrappedKey pulPasswordSize, CK_ULONG_PTR pulWrappedKeyLen, CK_OBJECT_HANDLE_PTR phKey ulPasswordCharacterSet ); |
Параметры
hSession | [in] | дескриптор сессии | ||
pGenerationMechanism | [in] | механизм генерации сессионного ключа. Допустимое значение: CKM_GOST28147_KEY_GEN – по стандарту ГОСТ 28147-89 | ||
ulPasswordNumber | порядковый номер генерируемого пароля. Допустимые значения от 1 до 6 и
| |||
pPassword | [out | pKeyTemplate | [in] | указатель на буфер, содержащий шаблон сессионого ключасгенерированный пароль |
pulPasswordSizeulKeyAttributeCount | [inout] | количество атрибутов сессионого ключа в шаблоне | размер буфера | |
ulPasswordCharacterSetpDerivationMechanism | [in] | набор допустимых символовмеханизм выработки ключа согласования. Допустимые значения: CKM | ||
hBaseKey | [in] | дескриптор закрытого ключа для формирования ключа согласования | ||
pWrappingMechanism | [in] | механизм шифрования сессионного ключа | ||
pWrappedKey | [in] | указатель на зашифрованный сессионный ключ | ||
pulWrappedKeyLen | [in] | длина зашифрованного сессионного ключа | ||
phKey | [out] | указатель на сессионый ключ (CEK) |
...
|
Возвращаемые значения
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] | дескриптор сессии | |
pDerivationMechanismulMode | [in] | механизм выработки ключа согласования (KEK). Допустимые значения: CKM_GOSTR3410_DERIVE – по стандарту ГОСТ Р 34.10-2001 | режим работы функции:
|
pValuehBaseKey | [in] | дескриптор закрытого ключа для формирования ключа согласования | |
pUnwrappingMechanism | [in] | механизм расшифрования зашифрованного сессионного ключа | |
pWrappedKey | [in] | указатель на зашифрованный сессионный ключ | |
ulWrappedKeyLen | [in] | длина зашифрованного сессионного ключа | |
pKeyTemplate | [in] | указатель на буфер, содержащий шаблон сессионного ключа | |
ulKeyAttributeCount | [in] | количество атрибутов сессионного ключа в шаблоне | phKey | [out] | указатель на дескриптор сессионного ключа (CEK)
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"); |
...