Предназначение устройств Рутокен
Рутокен PINPad представляет собой решение класса TrustScreen, которое позволяет визуализировать подписываемый документ на экране доверенного устройства перед наложением электронной подписи. Устройство позволяет реализовать следующие незаменимые в PKI-инфраструктуре возможности:
Кроме того, Рутокен PINPad поддерживает национальные стандарты в полном объеме:
Для работы с устройствами Рутокен по стандарту PKCS#11 приложение предварительно должно динамически загрузить библиотеку, реализующую интерфейс стандарта. Рутокен SDK предоставляет две библиотеки rtPKCS11.dll и rtPKCS11ECP.dll, подробнее об особенностях выбора и использования которых можно ознакомиться в разделе Использование библиотек rtPKCS11 и rtPKCS11ECP. Основная разница заключается в том, что российские алгоритмы доступны в библиотеке rtPKCS11ECP.dll, а зарубежные - в rtPKCS11.dll.
После загрузки библиотеки нужно получить адрес экспортируемой библиотекой функции C_GetFunctionList и вызвать ее для получения списка функций PKCS#11. Теперь все готово для работы с библиотекой.
Для работы с функциями расширения необходимо получить адрес функции CK_C_EX_GetFunctionListExtended и вызвать ее для получения списка функций расширения PKCS#11.
После работы с библиотекой ее нужно выгрузить из памяти.
/* Имя библиотеки PKCS#11 */
#ifdef _WIN32
/* Библиотека для Рутокен S, Рутокен Lite и Рутокен ЭЦП, поддерживает только алгоритмы RSA */
#define PKCS11_LIBRARY_NAME "rtPKCS11.dll"
/* Библиотека для Рутокен Lite, Рутокен ЭЦП, Рутокен PINPad, поддерживает алгоритмы ГОСТ и RSA */
#define PKCS11ECP_LIBRARY_NAME "rtPKCS11ECP.dll"
#endif
#ifdef __unix__
/* Библиотека для Рутокен Lite, Рутокен ЭЦП, Рутокен PINPad, поддерживает алгоритмы ГОСТ и RSA */
#define PKCS11_LIBRARY_NAME "librtpkcs11ecp.so"
#define PKCS11ECP_LIBRARY_NAME "librtpkcs11ecp.so"
#endif
#ifdef __APPLE__
/* Библиотека для Рутокен Lite, Рутокен ЭЦП, Рутокен PINPad, поддерживает алгоритмы ГОСТ и RSA */
#define PKCS11_LIBRARY_NAME "librtpkcs11ecp.dylib"
#define PKCS11ECP_LIBRARY_NAME "librtpkcs11ecp.dylib"
#endif
HMODULE hModule = NULL_PTR; // Хэндл загруженной библиотеки PKCS#11
CK_FUNCTION_LIST_PTR pFunctionList = NULL_PTR; // Указатель на список функций PKCS#11, хранящийся в структуре CK_FUNCTION_LIST
CK_C_GetFunctionList pfGetFunctionList = NULL_PTR; // Указатель на функцию C_GetFunctionList
CK_RV rv = CKR_OK; // Вспомогательная переменная для хранения кода возврата
while (TRUE)
{
/* Загрузить библиотеку */
printf("Loading library %s", PKCS11ECP_LIBRARY_NAME);
hModule = LoadLibrary(PKCS11ECP_LIBRARY_NAME);
if (hModule == NULL_PTR)
{
printf(" -> Failed\n");
break;
}
printf(" -> OK\n");
/* Получить адрес функции запроса структуры с указателями на функции */
printf("Getting GetFunctionList function");
pfGetFunctionList = (CK_C_GetFunctionList)GetProcAddress(hModule, "C_GetFunctionList");
if (pfGetFunctionList == NULL_PTR)
{
printf(" -> Failed\n");
break;
}
printf(" -> OK\n");
/* Получить структуру с указателями на функции */
printf("Getting function list");
rv = pfGetFunctionList(&pFunctionList);
if (rv != CKR_OK)
{
printf(" -> Failed\n");
break;
}
printf(" -> OK\n");
...
break;
}
/* Выгрузить библиотеку из памяти */
if (hModule)
{
printf("Unloading library");
if (FreeLibrary(hModule) != TRUE)
printf(" -> Failed\n");
else
printf(" -> OK\n");
hModule = NULL_PTR;
} |
После загрузки библиотеки нужно ее инициализировать вызовом функции C_Initialize. Параметр NULL при вызове данной функции означает, что функции библиотеки не будут вызываться из нескольких потоков, в противном случае в параметре должен быть передан указатель на структуру типа CK_INITIALIZE_ARGS.
Для завершения работы с библиотекой ее нужно деинициализировать вызовом функции C_Finalize().
/* Инициализировать библиотеку */
printf("Initializing library");
rv = pFunctionList->C_Initialize(NULL_PTR);
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n");
...
/* Деинициализировать библиотеку */
if (pFunctionList)
{
printf("Finalizing library");
rvTemp = pFunctionList->C_Finalize(NULL_PTR);
if (rvTemp != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n");
pFunctionList = NULL_PTR;
} |
Доступ к каждому подключенному устройству осуществляется с помощью идентификатора слота, к которому оно подключено. Для получения списка всех слотов предназначена функция C_GetSlotList. Значение первого параметра указывает, должен ли список включать слоты только с подключенным токенами (CK_TRUE) или все слоты (CK_FALSE).
CK_SLOT_ID_PTR aSlots = NULL_PTR; // Указатель на массив идентификаторов слотов
CK_ULONG ulSlotCount = 0; // Количество идентификаторов слотов в массиве
while(TRUE)
{
...
/* Получить количество слотов c подключенными токенами */
printf(" Getting number of connected slots");
rv = pFunctionList->C_GetSlotList(CK_TRUE, NULL_PTR, &ulSlotCount);
if (rv != CKR_OK)
{
printf(" -> Failed\n");
break;
}
printf(" -> OK\n");
aSlots = (CK_SLOT_ID*)malloc(ulSlotCount * sizeof(CK_SLOT_ID));
memset(aSlots, 0, (ulSlotCount * sizeof(CK_SLOT_ID)));
/* Получить список слотов c подключенными токенами */
printf(" Getting list of connected slots");
rv = pFunctionList->C_GetSlotList(CK_TRUE, aSlots, &ulSlotCount);
if (rv != CKR_OK)
{
printf(" -> Failed %X\n", (int)rv);
break;
}
printf(" -> OK\n");
printf(" Slots available: 0x%8.8X\n", (int)ulSlotCount);
...
break;
}
if (aSlots)
{
free(aSlots);
aSlots = NULL_PTR;
} |
Для получения актуальной информации о состоянии конкретного слота вызывается функция C_GetSlotInfo, в которую передается идентификатор слота. Ее вызов запускает обновление информации обо всех слотах. Если токен извлечь из разъема и затем снова вставить в тот же самый разъем, то он может подключиться к любому свободному слоту, а не обязательно к тому же самому.
Для мониторинга событий извлечения и подключения токенов для всех слотов используется функция C_WaitForSlotEvent, запущенная в отдельном потоке.
При вызове C_WaitForSlotEvent с флагом CKF_DONT_BLOCK функция возвращает код CKR_NO_EVENT при отсутствии событий или код CKR_OK при его наличии (вместе с идентификатором соответствующего событию слота).
При вызове C_WaitForSlotEvent с флагом 0 выполнение функции блокируется до возникновения события и функция возвращает код CKR_OK и номер соответствующего слота.
Все поддерживаемые устройствами Рутокен атрибуты объектов представлены в разделе Объекты PKCS #11.
Рутокен PINPad имеет два специфических атрибута закрытого ключа, которые влияют на поведение устройства при осуществлении криптографических операций с использованием такого ключа: CKA_VENDOR_KEY_CONFIRM_OP и CKA_VENDOR_KEY_PIN_ENTER. Оба атрибута присваиваются закрытому ключу при генерации ключевой пары соответственно указанным в шаблоне значениям и поэтому не могут быть изменены после генерации. Помимо закрытого ключа, эти атрибуты могут быть присвоены также секретному ключу.
Если ключ был создан с флагом визуализации CKA_VENDOR_KEY_CONFIRM_OP, то данные, которые подписываются с помощью такого ключа, перед подписью будут показаны на экране устройства и для их подписи потребуется подтверждение пользователя в виде нажатия специальной кнопки на тачскрине устройства.
Если ключ был создан с флагом повышенной защиты CKA_VENDOR_KEY_PIN_ENTER, то для подписи таким ключом перед операцией потребуется ввести PIN-код на тачскрине устройства.
Устройства Рутокен поддерживают следующие типы ключей асимметричной криптографии (CK_KEY_TYPE) :
CKK_GOSTR3410 для ключей ГОСТ Р 34.10-2001,
CKK_GOSTR3410_512 для ключей ГОСТ Р 34.10-2012, CKK_RSA для ключей RSA.Ниже представлены примеры шаблонов закрытого и открытого ключа ГОСТ Р 34.10-2001 с пояснениями.
CK_OBJECT_CLASS ocPrivKey = CKO_PRIVATE_KEY;
CK_UTF8CHAR PrivKeyLabel[] = {"GOST Private Key"};
CK_BYTE KeyPairID[] = {"GOST keypair"};
CK_KEY_TYPE KeyType = CKK_GOSTR3410;
CK_BBOOL bTrue = CK_TRUE;
CK_BYTE GOST3410params[] = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01 }; // Параметры алгоритма ГОСТ Р 34.10-2001
CK_ATTRIBUTE GOST34_10_2001PrivateKey[] = {
{ CKA_CLASS, &ocPrivKey, sizeof(ocPrivKey)}, // Объект закрытого ключа
{ CKA_LABEL, &PrivKeyLabel, sizeof(PrivKeyLabel) - 1}, // Метка ключа
{ CKA_ID, &KeyPairID, sizeof(KeyPairID) - 1}, // Идентификатор ключевой пары #1 (должен совпадать у открытого и закрытого ключей)
{ CKA_KEY_TYPE, &KeyType, sizeof(KeyType)}, // Тип ключа
{ CKA_DECRYPT, &bTrue, sizeof(bTrue)}, // Ключ предназначен для расшифрования
{ CKA_TOKEN, &bTrue, sizeof(bTrue)}, // Ключ является объектом токена
{ CKA_PRIVATE, &bTrue, sizeof(bTrue)}, // Ключ доступен только после авторизации на токене
{ CKA_DERIVE, &bTrue, sizeof(bTrue)}, // Ключ поддерживает деривацию (из него могут быть получены другие ключи)
{ CKA_VENDOR_KEY_CONFIRM_OP, &bTrue, sizeof(bTrue) }, // Операция подписи требует подтверждения на PINPad (только для Рутокен PINPad)
{ CKA_VENDOR_KEY_PIN_ENTER, &bTrue, sizeof(bTrue) }, // Операция подписи требует ввода PIN-кода на PINPad (только для Рутокен PINPad)
{ CKA_GOSTR3410_PARAMS, GOST3410params, sizeof(GOST3410params)} // Параметры алгоритма
}; |
CK_OBJECT_CLASS ocPubKey = CKO_PUBLIC_KEY;
CK_UTF8CHAR PubKeyLabel[] = {"GOST Public Key"};
CK_BYTE KeyPairID[] = {"GOST keypair"};
CK_KEY_TYPE KeyType = CKK_GOSTR3410;
CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;
CK_BYTE GOST3410params[] = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01 }; // Параметры алгоритма ГОСТ Р 34.10-2001
CK_BYTE GOST3411params[] = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x01 }; // Параметры алгоритма ГОСТ Р 34.11-1994
CK_ATTRIBUTE GOST34_10_2001PublicKey[] = {
{ CKA_CLASS, &ocPubKey, sizeof(ocPubKey)}, // Объект открытого ключа
{ CKA_LABEL, &PubKeyLabel, sizeof(PubKeyLabel)-1}, // Метка ключа
{ CKA_ID, &KeyPairID, sizeof(KeyPairID)-1}, // Идентификатор ключевой пары
{ CKA_KEY_TYPE, &KeyType, sizeof(KeyType)}, // Тип ключа
{ CKA_ENCRYPT, &bTrue, sizeof(bTrue)}, // Ключ предназначен для зашифрования
{ CKA_TOKEN, &bTrue, sizeof(bTrue)}, // Ключ является объектом токена
{ CKA_PRIVATE, &bFalse, sizeof(bFalse)}, // Ключ доступен без авторизации на токене
{ CKA_DERIVE, &bTrue, sizeof(bTrue)}, // Ключ поддерживает деривацию (из него могут быть получены другие ключи)
{ CKA_GOSTR3410_PARAMS, GOST3410params, sizeof(GOST3410params)},// Параметры алгоритма
{ CKA_GOSTR3411_PARAMS, GOST3411params, sizeof(GOST3411params)} // Параметры алгоритма
}; |
Устройства Рутокен поддерживают следующие механизмы генерации ключевой пары:
CKM_GOSTR3410_KEY_PAIR_GEN для генерации ключевой пары ГОСТ Р 34.10.2001,CKM_GOSTR3410_512_KEY_PAIR_GEN для генерации ключевой пары ГОСТ Р 34.10.2012,CKM_RSA_PKCS_KEY_PAIR_GEN для генерации ключевой пары RSA./* Вычисление размера массива */
#define arraysize(a) (sizeof(a)/sizeof(a[0]))
CK_MECHANISM KeyGenMech = {CKM_GOSTR3410_KEY_PAIR_GEN, NULL_PTR, 0}; // Генерация ключа ГОСТ Р 34.10-2001
CK_OBJECT_HANDLE hPublicKey = NULL_PTR; // Хэндл открытого ключа
CK_OBJECT_HANDLE hPrivateKey = NULL_PTR; // Хэндл закрытого ключа
printf("\n Generating key pair");
rv = pFunctionList->C_GenerateKeyPair(hSession, // Хэндл открытой сессии
&KeyGenMech, // Используемый механизм генерации ключевой пары
GOST34_10_2001PublicKey, // Шаблон открытого ключа
arraysize(GOST34_10_2001PublicKey), // Размер шаблона открытого ключа
GOST34_10_2001PrivateKey, // Шаблон закрытого ключа
arraysize(GOST34_10_2001PrivateKey), // Размер шаблона закрытого ключа
&hPublicKey, // Хэндл открытого ключа
&hPrivateKey); // Хэндл закрытого ключа
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n"); |
Все поддерживаемые устройствами Рутокен атрибуты объектов представлены в разделе Объекты секретных ключей.
Рутокен PINPad имеет два специфических атрибута секретного ключа, которые влияют на поведение устройства при осуществлении криптографических операций с использованием такого ключа: CKA_VENDOR_KEY_CONFIRM_OP и CKA_VENDOR_KEY_PIN_ENTER. Оба атрибута присваиваются закрытому ключу при генерации ключевой пары соответственно указанным в шаблоне значениям и поэтому не могут быть изменены после генерации. Помимо закрытого ключа, эти атрибуты могут быть присвоены также секретному ключу.
Если ключ был создан с флагом визуализации CKA_VENDOR_KEY_CONFIRM_OP, то данные, которые шифруются с помощью такого ключа, перед подписью будут показаны на экране устройства и для их шифрования потребуется подтверждение пользователя в виде нажатия специальной кнопки на тачскрине устройства.
Если ключ был создан с флагом повышенной защиты CKA_VENDOR_KEY_PIN_ENTER, то для шифрования таким ключом перед операцией потребуется ввести PIN-код на тачскрине устройства.
Устройства Рутокен поддерживают следующие типы секретных ключей (CK_KEY_TYPE) :
CKK_GENERIC_SECRET для абстрактных ключей произвольной длины,
CK_OBJECT_CLASS ocPubKey = CKO_SECRET_KEY;
CK_UTF8CHAR SecKeyLabel[] = {"GOST Secret Key"};
CK_BYTE SecKeyID[] = {"GOST Secret Key"};
CK_KEY_TYPE KeyType = CKK_GOST28147;
CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;
CK_BYTE GOST28147params[] = { 0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x01 }; // Параметры алгоритма ГОСТ 28147-89
CK_ATTRIBUTE attrGOST28147_89SecKey[] =
{
{ CKA_CLASS, &ocSeckey, sizeof(ocSeckey)}, // Объект секретного ключа ГОСТ 28147-89
{ CKA_LABEL, &SecKeyLabel, sizeof(SecKeyLabel) - 1}, // Метка ключа
{ CKA_ID, &SecKeyID, sizeof(SecKeyID) - 1}, // Идентификатор ключа
{ CKA_KEY_TYPE, &KeyType, sizeof(KeyType)}, // Тип ключа
{ CKA_ENCRYPT, &bTrue, sizeof(bTrue)}, // Ключ предназначен для зашифрования
{ CKA_DECRYPT, &bTrue, sizeof(bTrue)}, // Ключ предназначен для расшифрования
{ CKA_TOKEN, &bTrue, sizeof(bTrue)}, // Ключ является объектом токена
{ CKA_PRIVATE, &bFalse, sizeof(bFalse)}, // Ключ доступен без авторизации на токене
{ CKA_VENDOR_KEY_CONFIRM_OP, &bTrue, sizeof(bTrue) }, // Операция шифрования/расшифрования требует подтверждения на PINPad (только для Рутокен PINPad)
{ CKA_VENDOR_KEY_PIN_ENTER, &bTrue, sizeof(bTrue) }, // Операция шифрования/расшифрования требует ввода PIN-кода на PINPad (только для Рутокен PINPad)
{ CKA_GOST28147_PARAMS, GOST28147params, sizeof(GOST28147params)} // Параметры алгоритма
}; |
Устройства Рутокен поддерживают следующие механизмы генерации секретного ключа:
CKM_GOST28147_KEY_GEN для генерации секретного ключа ГОСТ 28147-89./* Вычисление размера массива */
#define arraysize(a) (sizeof(a)/sizeof(a[0]))
CK_MECHANISM KeyGenMech = {CKM_GOST28147_KEY_GEN, NULL_PTR, 0}; // Генерация ключа ГОСТ 28147-89
CK_OBJECT_HANDLE hSecKey = NULL_PTR; // Хэндл cекретного ключа
printf("\n Generating key");
rv = pFunctionList->C_GenerateKey(hSession, // Хэндл открытой сессии
&KeyGenMech, // Используемый механизм генерации ключа
attrGOST28147_89SecKey, // Шаблон для создания секретного ключа
arraysize(attrGOST28147_89SecKey), // Размер шаблона секретного ключа
&hSecKey); // Хэндл секретного ключа
if (rv != CKR_OK)
printf(" -> Failed\n");
else
printf(" -> OK\n"); |