Anchor | ||||
---|---|---|---|---|
|
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Функции общего назначения
C_EX_GetFunctionListExtended()
Назначение
Функция возвращает список дополнительных функций, расширяющих библиотеку PKCS#11 для работы с Рутокен.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_GetFunctionListExtended)( CK_FUNCTION_LIST_EXTENDED_PTR_PTR ppFunctionList ); |
Параметры
ppFunctionList | [out] | указатель на список функций расширения |
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Пример
Code Block | ||
---|---|---|
| ||
HMODULE hModule; // дескриптор загруженной библиотеки PKCS #11 CK_FUNCTION_LIST_EXTENDED_PTR pFunctionListEx; // указатель на структуру CK_FUNCTION_LIST_EXTENDED, в которой хранится список функций расширения CK_C_EX_GetFunctionListExtended pfGetFunctionListEx; // указатель на функцию C_EX_GetFunctionListExtended CK_RV rv; // вспомогательная переменная для хранения кода возврата hModule = LoadLibrary("rtPKCS11.dll"); // получение дескриптора загруженной библиотеки pfGetFunctionListEx = (CK_C_EX_GetFunctionListExtended) GetProcAddress(hModule,"C_EX_GetFunctionListExtended"); // получение адреса функции C_EX_GetFunctionListExtended if (pfGetFunctionListEx == NULL_PTR) // проверка результата printf ("Loading library -> Failed \n"); else printf ("Loading library -> OK \n"); rv = pfGetFunctionListEx(&pFunctionListEx); // получение структуры с указателями на функции расширения if (rv == CKR_OK) // проверка результата printf ("Getting extended function list -> OK \n"); else printf ("Getting extended function list -> Failed \n"); . . FreeLibrary(hModule); // завершение работы с библиотекой |
Функции для работы со слотами и токенами
C_EX_GetTokenInfoExtended()
Назначение
Функция позволяет получить специфическую для устройств Рутокен информацию: класс токена, количество свободной и общей памяти, тип токена, номер протокола и т.д. По сравнению с похожей по назначению стандартной функции 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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_SLOT_ID_INVALID,
CKR_TOKEN_NOT_PRESENT.
Расширенные коды ошибок.
Пример
Code Block | ||||
---|---|---|---|---|
| ||||
CK_SLOT_ID slotID; // идентификатор слота CK_TOKEN_INFO_EXTENDED ckTokenInfoEx; // структура расширенных данных токена CK_RV rv; // вспомогательная переменная для хранения кода возврата . . ckTokenInfoEx.ulSizeofThisStructure = sizeof(CK_TOKEN_INFO_EXTENDED); // размер структуры CK_TOKEN_INFO_EXTENDED rv = pfGetFunctionListEx -> C_EX_GetTokenInfoExtended(slotID, &ckTokenInfoEx); // получение расширенной информации о токене if (rv == CKR_OK) // проверка результата printf ("Getting Extended Token Info -> OK \n"); else printf ("Getting Extended Token Info -> Failed \n"); |
C_EX_InitToken()
Назначение
Функция позволяет полностью инициализировать память токена. На этапе инициализации есть возможность задать политику смены PIN-кода пользователя, метки токена произвольной длины и т.д.
Синтаксис
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.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_CANCELED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_PIN_INCORRECT,
CKR_PIN_LOCKED,
CKR_SESSION_EXISTS,
CKR_SLOT_ID_INVALID,
CKR_TOKEN_NOT_PRESENT.
Расширенные коды ошибок.
Пример
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"); |
C_EX_UnblockUserPIN()
Назначение
Функция позволяет разблокировать PIN-код Пользователя.
Синтаксис
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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_CANCELED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_PIN_INVALID,
CKR_PIN_LEN_RANGE,
CKR_SESSION_CLOSED,
CKR_SESSION_READ_ONLY,
CKR_SESSION_HANDLE_INVALID,
CKR_USER_NOT_LOGGED_IN,
CKR_ARGUMENTS_BAD.
Расширенные коды ошибок.
Пример
Code Block | ||||
---|---|---|---|---|
| ||||
static CK_CHAR SO_PIN[] = {'8', '7', '6', '5', '4', '3', '2', '1'}; // PIN-код Администратора Рутокен по умолчанию CK_SESSION_HANDLE hSession; // дескриптор сессии CK_SLOT_ID slots[100]; // массив идентификаторов слотов CK_ULONG ulSlotCount = 100; // количество идентификаторов слотов в массиве CK_RV rv; // вспомогательная переменная для хранения кода возврата . . rv = pfGetFunctionList -> C_OpenSession( // открытие сессии slots[0], // выбор нулевого слота CKF_SERIAL_SESSION | CKF_RW_SESSION), // флаги для сессии чтение/запись 0, // не используется 0, // не используется &hSession); // дескриптор сессии if (rv != CKR_OK) // проверка результата printf("Opening session -> failed \n"); else printf("Opening session -> OK \n"); rv = pfGetFunctionList -> C_Login( // получение прав Администратора, необходимых для разблокировки hSession, // дескриптор сессии CKU_SO, // пользователь, с правами которого производится авторизация SO_PIN, // PIN-код указанного пользователя sizeof(SO_PIN)); // длина PIN-кода if (rv != CKR_OK) // проверка результата printf("Logining -> failed \n"); else printf("Logining -> OK \n"); rv = pfGetFunctionListEx -> C_EX_UnblockUserPIN(hSession); // разблокировка PIN-кода if (rv != CKR_OK) // проверка результата printf("Unblocking UserPIN -> failed \n"); else printf("Unblocking UserPIN -> OK \n"); . . pfGetFunctionList -> C_Logout(hSession); // выход пользователя pfGetFunctionList -> C_CloseSession(hSession); // закрытие сессии |
C_EX_SetTokenName()
Назначение
Функция позволяет задать метку токена (символьное имя) произвольной длины.
Синтаксис
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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_PIN_EXPIRED,
CKR_SESSION_CLOSED,
CKR_SESSION_HANDLE_INVALID,
CKR_SESSION_READ_ONLY,
CKR_USER_NOT_LOGGED_IN.
Расширенные коды ошибок.
Пример
Code Block | ||||
---|---|---|---|---|
| ||||
CK_SESSION_HANDLE hSession; // дескриптор сессии CK_CHAR ckcNewLabel[100]; // метка длиной 100 символов CK_RV rv; // вспомогательная переменная для хранения кода возврата . . pfGetFunctionList -> C_OpenSession(slots[0], CKF_SERIAL_SESSION | CKF_RW_SESSION), 0, 0, &hSession); // открытие сессии pfGetFunctionList -> C_Login(hSession, CKU_USER, USER_PIN, sizeof(USER_PIN)); // авторизация с правами пользователя strcpy ((char *)ckcNewLabel, "Label is set by C_EX_SetTokenName from rtPKCS11ecp.dll"); // определяем имя метки rv = pfGetFunctionList -> C_EX_SetTokenName(hSession, ckcNewLabel, 32); // задаем метку токена if (rv != CKR_OK) // проверка результата printf("Changing of label -> failed \n"); else printf("Changing of label -> OK \n"); . . pfGetFunctionList -> C_Logout(hSession); // выход пользователя pfGetFunctionList -> C_CloseSession(hSession); // закрытие сессии |
C_EX_GetTokenName()
Назначение
Функция позволяет получить метку токена произвольной длины. Функция может быть вызвана из любой сессии.
Синтаксис
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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_SESSION_CLOSED,
CKR_SESSION_HANDLE_INVALID,
CKR_BUFFER_TOO_SMALL.
Расширенные коды ошибок.
Пример
Code Block | ||||
---|---|---|---|---|
| ||||
CK_BYTE ckLabel[1000]; CK_ULONG ckulLabelLen = 0; . . rv = pfGetFunctionListEx -> C_EX_GetTokenName(hSession, ckLabel, &ckulLabelLen); // получение метки токена if (rv != CKR_OK) // проверка результата printf("Getting name of token -> failed \n"); else printf("Getting name of token -> OK \n"); |
C_EX_SetLicense()
Назначение
Функция предназначена для записи данных вендора в токен и позволяет записать лицензию на токен.
Синтаксис
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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_FAILED,
CKR_FUNCTION_NOT_SUPPORTED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_PIN_EXPIRED,
CKR_SESSION_CLOSED,
CKR_SESSION_HANDLE_INVALID,
CKR_SESSION_READ_ONLY,
CKR_USER_NOT_LOGGED_IN.
Расширенные коды ошибок.
Примечание
Формат данных (лицензии) определяет вендор, размер ограничивается 72 байтами. Всего может быть до двух лицензий.Функция может быть вызвана только из сессии, имеющей статус CKS_RW_USER_FUNCTIONS или CKS_RW_SO_FUNCTIONS.
При инициализации памяти токена с помощью функций C_InitToken или C_EX_InitToken ранее записанная лицензия удалена не будет.
Пример
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
CK_ULONG ckulLicenseNumber = 1; // идентификатор лицензии CK_BYTE ckbLicense[100]; // массив идентификаторов лицензий CK_ULONG ckulLicenseLen = 0; // длина лицензии . . pfGetFunctionList -> C_OpenSession(slots[0], (CKF_SERIAL_SESSION), 0, 0,&hSession); // открытие сессии pfGetFunctionList -> C_Login(hSession, CKU_SO, SO_PIN, sizeof(SO_PIN)); // авторизация с правами Администратора pfGetFunctionListEx -> C_EX_GetLicense(hSession, ckulLicenseNumber, ckbLicense, &ckulLicenseLen); // считываем текущую лицензию for (CK_ULONG ckulIndex=0; ckulIndex < ckulLicenseLen; ckulIndex++) // новое значение лицензии: ckbLicense[ckulIndex] = (72 - ckulIndex); rv = pfLstEx->C_EX_SetLicense(hSession, ckulLicenseNumber, ckbLicense, ckulLicenseLen); // записываем новое значение лицензии if (rv != CKR_OK) printf("C_EX_SetLicense() -> failed\n"); else printf("C_EX_SetLicense() -> OK\n"); . . pfGetFunctionList -> C_Logout(hSession); // выход пользователя pfGetFunctionList -> C_CloseSession(hSession); // закрытие сессии |
C_EX_GetLicense()
Назначение
Функция позволяет прочитать лицензию, записанную на токен.
Синтаксис
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 – функция выполнена успешно.
Стандартные коды ошибок:
CKR_ARGUMENTS_BAD,
CKR_CRYPTOKI_NOT_INITIALIZED,
CKR_DEVICE_ERROR,
CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED,
CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR,
CKR_HOST_MEMORY,
CKR_SESSION_CLOSED,
CKR_SESSION_HANDLE_INVALID,
CKR_FUNCTION_NOT_SUPPORTED.
Расширенные коды ошибок.
Примечание
Функция позволяет прочитать лицензию с токена. Функция может быть вызвана из сессии любого состояния. Длина лицензии может иметь единственное значение 72 байта, либо при передаче pLicense равного NULL_PTR в параметре pulLicenseLen возвращается указатель на длину буфера для требуемой лицензии.
Пример
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
CK_ULONG ckulLicenseNumber = 1; // идентификатор лицензии CK_BYTE ckbLicense[100]; // массив идентификаторов лицензий CK_ULONG ckulLicenseLen = 0; // длина лицензии . . pfGetFunctionList -> C_OpenSession(slots[0], (CKF_SERIAL_SESSION), 0, 0,&hSession); // открытие сессии rv = pfGetFunctionListEx -> C_EX_GetLicense(hSession, ckulLicenseNumber, ckbLicense, &ckulLicenseLen); // считываем текущую лицензию if (rv != CKR_OK) printf("C_EX_GetLicense() -> failed\n"); else printf("C_EX_GetLicense() -> OK\n"); . . pfGetFunctionList -> C_CloseSession(hSession); // закрытие сессии |
C_EX_GetCertificateInfoText()
Назначение
Функция позволяет получить информацию о сертификате из токена в текстовом виде.
Синтаксис
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_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, сохраняются вместе с подписанным сообщением; PKCS7_DETACHED_SIGNATURE – исходные данные, на которые ссылается указатель pData, не сохраняются вместе с подписанным сообщением. |
Возвращаемые данные
Примечание
Функция может быть вызвана только из состояний "R/W User Functions" и "R User Functions". Буфер ppEnvelope создается внутри функции. После окончания работы с ним необходимо освободить его, вызвав функцию 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().
Пример
C_EX_FreeBuffer()
Назначение
Функция высвобождает память, выделенную другими расширенными функциями, например C_EX_GetCertificateInfoText.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_FreeBuffer)( CK_BYTE_PTR pBuffer ); |
Параметры
pBuffer | [in] | указатель на буфер |
Возвращаемые данные
Пример
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"); |
C_EX_SetLocalPIN()
Назначение
Функция устанавливает локальный PIN-код для PinPad In, если он поддерживает эту операцию.
Синтаксис
Code Block |
---|
CK_DEFINE_FUNCTION(CK_RV, C_EX_SetLocalPIN)( CK_SLOT_ID slotID, CK_UTF8CHAR_PTR pUserPin, CK_ULONG ulUserPinLen, CK_UTF8CHAR_PTR pNewLocalPin, CK_ULONG ulNewLocalPinLen, CK_ULONG ulLocalID ); |
Параметры
slotID | [in] | идентификатор слота, к которому подключен токен |
pUserPin | [in] | указатель на текущий PIN-код Пользователя |
ulUserPinLen | [in] | длина текущего PIN-кода Пользователя |
pNewLocalPin | [in] | указатель на новый Локальный PIN-код |
ulNewLocalPinLen | [in] | длина нового Локального PIN-кода |
ulLocalID | [in] | идентификатор Локального PIN-кода |
Возвращаемые данные
Пример
Code Block | ||
---|---|---|
| ||
CK_BYTE Pin[] = {'1', '2', '3', '4', '5', '6', '7', '8'}; // текущий PIN-код Пользователя CK_SLOT_ID slots[100]; // массив идентификаторов слотов . . rv = pfGetFunctionListEx -> C_EX_SetLocalPIN( slots[0], // считаем, что токен подключен к первому слоту Pin, // текущий PIN-код Пользователя arraysize(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"); |