Table of Contents
Введение
Предназначение устройств Рутокен
...
Code Block | ||||
---|---|---|---|---|
| ||||
/* Имя библиотеки 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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
/* Инициализировать библиотеку */
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функция C_WaitForSlotEvent
, запущенная в отдельном потоке.
...
Code Block | ||||
---|---|---|---|---|
| ||||
Определение типа устройств
Открытие и закрытие сессии
Генерация ключевой пары
Атрибуты ключевых объектов
...
Если ключ был создан с флагом повышенной защиты 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 с пояснениями.
Code Block |
---|
...
Code Block | ||||
---|---|---|---|---|
| ||||
CK_OBJECT_CLASS ocPrivKey = CKO_PRIVATE_KEY; CK_UTF8CHAR PrivKeyLabel[] = {"GOST Private Key"}; CK_BYTE KeyPairID[] = {"GOST keypair"}; CK_KEY_TYPE KeyType = CKK_GOSTR3410; // или CKK_GOSTR3410_512 для ключа длиной 512 бит 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)} // Параметры алгоритма }; |
Code Block | ||||
---|---|---|---|---|
| ||||
CK_OBJECT_CLASS ocPubKey = CKO_PUBLIC_KEY;
CK_UTF8CHAR PubKeyLabel[] = {"GOST Public Key"};
CK_BYTE KeyPairID[] = {"GOST keypair"};
CK_KEY_TYPE KeyType = CKK_GOSTR3410; // или CKK_GOSTR3410_512 для ключа длиной 512 бит
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.
Пример генерации ключевой пары
Code Block | ||||
---|---|---|---|---|
| ||||
/* Вычисление размера массива */
#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
Рутокен 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 для абстрактных ключей произвольной длины,
- CKK_GOST28147 для ключей ГОСТ 28147-89.
Примеры шаблона секретного ключа
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Пример генерации секретного ключа
Code Block | ||||
---|---|---|---|---|
| ||||
/* Вычисление размера массива */
#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"); |
...