Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Данные сценарии предполагают клиент-серверное взаимодействие, написание клиентских скриптов на JavaScript и соответствующих им серверных вызовов openssl.

Общие операции

Операции с устройством

Поиск подключенных устройств

Любой клиентский сценарий начинается с поиска подключенных к компьютеру USB-устройств Рутокен. В контексте данной статьи акцент делается на устройство Рутокен ЭЦП.

...

 Рутокен Плагин определяет все подключенные к компьютеру USВ-устройства Рутокен ЭЦП, Рутокен PINPad. Поэтому следующим шагом следует определить тип устройства.

Получение информации об устройстве

Для определения типа устройства следует использовать функцию getDeviceInfo с параметром TOKENфункцию getRutokenModelName() репозитория https://github.com/AktivCo/blade-runner.github.io

Параметр функции getDeviceInfo TOKEN_INFO_DEVICE_

...

TYPE – устарел и не поддерживается.

С помощью функции getDeviceInfo можно получить:

  • модель устройства
  • метку устройства
  • серийный номер устройства
  • информацию о том, залогинен ли пользователь на устройство

Смена PIN-кода

Code Block
languagejs
titleПример смены PIN-кода на устройстве:
var options = {}

...

Code Block
languagejs
var type;

try
{   
  type = plugin.getDeviceInfochangePin(deviceId, plugin.TOKEN_INFO_DEVICE_TYPE"12345678", "12345671", options);
}
catch (error) 
{
    console.log(error);
}

switch (type) 
{
    case plugin.TOKEN_TYPE_UNKNOWN:
        message = "Неизвестное устройство";
        break;
    case plugin.TOKEN_TYPE_RUTOKEN_ECP:
        message = "Рутокен ЭЦП";
        break;
    case plugin.TOKEN_TYPE_RUTOKEN_PINPAD_2:
        message = "Рутокен PINPad";
        break;
}
 

Также с помощью функции getDeviceInfo можно получить:

  • модель устройства
  • метку устройства
  • серийный номер устройства
  • информацию о том, залогинен ли пользователь на устройство

Смена PIN-кода


Здесь первым параметром выступает старый PIN-код, а вторым новый PIN-код.

 

Работа с сертификатами

1. На токене могут храниться 3 категории сертификатов:

  • пользовательские (константа в плагине CERT_CATEGORY_USER)
    Это сертификаты, связанные с закрытым ключом пользователя. Применяются, например, для подписи CMS/PKCS#7, аутентификации пользователя в протоколе TLS.
    Если сертификат импортируется как пользовательский, то при импорте будет произведен поиск в устройстве соответствующего ему закрытого ключа. Если такой ключ будет найден, то сертификат будет «привязан» к этому ключу. Если ключ найден не будет, то вернется ошибка.
  • корневые (константа в плагине CERT_CATEGORY_CA)
    Это сертификаты издателей сертификатов, применяющиеся для проверки подписи под сертификатами. Подобная проверка подписи (построение цепочки доверия) позволяет определить, доверяет ли пользователь подписи другого пользователя. Например, в функции плагина verify есть режим проверки сертификата, на котором было подписано сообщение. При этом используется хранилище корневых сертификатов на токене, созданное импортом корневых сертификатов на токен.
  • другие (константа в плагине CERT_CATEGORY_OTHER)
    Это сертификаты, которые не связаны с закрытым ключом и не являются корневыми.


2. Для чтения сертификатов, хранящихся на устройстве, не требуется авторизация на устройство.

Code Block
languagejs
titleПример чтения пользовательских сертификатов с устройства:
 var certs = Array();

try
{   
    certs = plugin.enumerateCertificates(deviceId, plugin.CERT_CATEGORY_USER);
}
catch (error) 
{
    console.log(error);
}


3. Сертификат можно экспортировать в PEM-формате:

Code Block
languagejs
var certpem
Code Block
languagejs
titleПример смены PIN-кода на устройстве:
var options = {};

try
{   
    certpem = plugin.changePingetCertificate(deviceId, "12345678", "12345671", optionscertId);
}
catch (error) 
{
    console.log(error);
}

...

Получится примерно такая строка:

Code Block
-----BEGIN CERTIFICATE-----
MIIBmjCCAUegAwIBAgIBATAKBgYqhQMCAgMFADBUMQswCQYDVQQGEwJSVTEPMA0G
A1UEBxMGTW9zY293MSIwIAYDVQQKFBlPT08gIkdhcmFudC1QYXJrLVRlbGVjb20i
MRAwDgYDVQQDEwdUZXN0IENBMB4XDTE0MTIyMjE2NTEyNVoXDTE1MTIyMjE2NTEy
NVowEDEOMAwGA1UEAxMFZmZmZmYwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAQYHKoUD
AgIeAQNDAARADKA/O1Zw50PzMpcNkWnW39mAJcTehAhkQ2Vg7bHkIwIdf7zPe2Px
HyAr6lH+stqdACK6sFYmkZ58cBjzL0WBwaNEMEIwJQYDVR0lBB4wHAYIKwYBBQUH
AwIGCCsGAQUFBwMEBgYpAQEBAQIwCwYDVR0PBAQDAgKkMAwGA1UdEwEB/wQCMAAw
CgYGKoUDAgIDBQADQQD5TY55KbwADGKJRK+bwCGZw24sdIyayIX5dn9hrKkNrZsW
detWY3KJFylSulykS/dfJ871IT+8dXPU5A7WqG4+
-----END CERTIFICATE-----

4. Сертификат можно распарсить вызовом функции parseCertificate и получить из него DN Subject, DN Issuer, расширения, значение открытого ключа, подпись, серийный номер, срок действия и т.п.

5. Сертификат можно записать на устройство.

Code Block
languagejs
titleПример записи сертификата на устройство как пользовательского:
 var certpem = "-----BEGIN CERTIFICATE-----
MIIBmjCCAUegAwIBAgIBATAKBgYqhQMCAgMFADBUMQswCQYDVQQGEwJSVTEPMA0G
A1UEBxMGTW9zY293MSIwIAYDVQQKFBlPT08gIkdhcmFudC1QYXJrLVRlbGVjb20i
MRAwDgYDVQQDEwdUZXN0IENBMB4XDTE0MTIyMjE2NTEyNVoXDTE1MTIyMjE2NTEy
NVowEDEOMAwGA1UEAxMFZmZmZmYwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAQYHKoUD
AgIeAQNDAARADKA/O1Zw50PzMpcNkWnW39mAJcTehAhkQ2Vg7bHkIwIdf7zPe2Px
HyAr6lH+stqdACK6sFYmkZ58cBjzL0WBwaNEMEIwJQYDVR0lBB4wHAYIKwYBBQUH
AwIGCCsGAQUFBwMEBgYpAQEBAQIwCwYDVR0PBAQDAgKkMAwGA1UdEwEB/wQCMAAw
CgYGKoUDAgIDBQADQQD5TY55KbwADGKJRK+bwCGZw24sdIyayIX5dn9hrKkNrZsW
detWY3KJFylSulykS/dfJ871IT+8dXPU5A7WqG4+
-----END CERTIFICATE-----"

 

Работа с сертификатами

1. На токене могут храниться 3 категории сертификатов:

  • пользовательские (константа в плагине CERT_CATEGORY_USER)
    Это сертификаты, связанные с закрытым ключом пользователя. Применяются, например, для подписи CMS/PKCS#7, аутентификации пользователя в протоколе TLS.
    Если сертификат импортируется как пользовательский, то при импорте будет произведен поиск в устройстве соответствующего ему закрытого ключа. Если такой ключ будет найден, то сертификат будет «привязан» к этому ключу. Если ключ найден не будет, то вернется ошибка.
  • корневые (константа в плагине CERT_CATEGORY_CA)
    Это сертификаты издателей сертификатов, применяющиеся для проверки подписи под сертификатами. Подобная проверка подписи (построение цепочки доверия) позволяет определить, доверяет ли пользователь подписи другого пользователя. Например, в функции плагина verify есть режим проверки сертификата, на котором было подписано сообщение. При этом используется хранилище корневых сертификатов на токене, созданное импортом корневых сертификатов на токен.
  • другие (константа в плагине CERT_CATEGORY_OTHER)
    Это сертификаты, которые не связаны с закрытым ключом и не являются корневыми.

...

Code Block
languagejs
titleПример чтения пользовательских сертификатов с устройства:
 var certs = Array();

try
{   
    certs = plugin.enumerateCertificatesimportCertificate(deviceId, certpem, plugin.CERT_CATEGORY_USER);
}
catch (error) 
{
    console.log(error);
}

6. Вызовом функции deleteCertificate можно удалить сертификат с токена.

Работа с ключевыми парами ГОСТ


1. Для получения декрипторов ключевых пар, хранящихся на устройстве, требуется ввод PIN-кода. Следует понимать, что само значение закрытого ключ получено быть не может, так как ключ является неизвлекаемым.
3. Сертификат можно экспортировать в PEM-формате:

Code Block
languagejs
var certpemkeys = Array();

try
{   
     certpemplugin.login(deviceId, "12345678");
    keys = plugin.getCertificateenumerateKeys(deviceId, certIdnull);
}
catch (error) 
{
    console.log(error);
}

Получится примерно такая строка:

Code Block
-----BEGIN CERTIFICATE-----
MIIBmjCCAUegAwIBAgIBATAKBgYqhQMCAgMFADBUMQswCQYDVQQGEwJSVTEPMA0G
A1UEBxMGTW9zY293MSIwIAYDVQQKFBlPT08gIkdhcmFudC1QYXJrLVRlbGVjb20i
MRAwDgYDVQQDEwdUZXN0IENBMB4XDTE0MTIyMjE2NTEyNVoXDTE1MTIyMjE2NTEy
NVowEDEOMAwGA1UEAxMFZmZmZmYwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAQYHKoUD
AgIeAQNDAARADKA/O1Zw50PzMpcNkWnW39mAJcTehAhkQ2Vg7bHkIwIdf7zPe2Px
HyAr6lH+stqdACK6sFYmkZ58cBjzL0WBwaNEMEIwJQYDVR0lBB4wHAYIKwYBBQUH
AwIGCCsGAQUFBwMEBgYpAQEBAQIwCwYDVR0PBAQDAgKkMAwGA1UdEwEB/wQCMAAw
CgYGKoUDAgIDBQADQQD5TY55KbwADGKJRK+bwCGZw24sdIyayIX5dn9hrKkNrZsW
detWY3KJFylSulykS/dfJ871IT+8dXPU5A7WqG4+
-----END CERTIFICATE-----

...

Code Block
languagejs
titleПример записи сертификата на устройство как пользовательского:
 var certpem = "-----BEGIN CERTIFICATE-----
MIIBmjCCAUegAwIBAgIBATAKBgYqhQMCAgMFADBUMQswCQYDVQQGEwJSVTEPMA0G
A1UEBxMGTW9zY293MSIwIAYDVQQKFBlPT08gIkdhcmFudC1QYXJrLVRlbGVjb20i
MRAwDgYDVQQDEwdUZXN0IENBMB4XDTE0MTIyMjE2NTEyNVoXDTE1MTIyMjE2NTEy
NVowEDEOMAwGA1UEAxMFZmZmZmYwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAQYHKoUD
AgIeAQNDAARADKA/O1Zw50PzMpcNkWnW39mAJcTehAhkQ2Vg7bHkIwIdf7zPe2Px
HyAr6lH+stqdACK6sFYmkZ58cBjzL0WBwaNEMEIwJQYDVR0lBB4wHAYIKwYBBQUH
AwIGCCsGAQUFBwMEBgYpAQEBAQIwCwYDVR0PBAQDAgKkMAwGA1UdEwEB/wQCMAAw
CgYGKoUDAgIDBQADQQD5TY55KbwADGKJRK+bwCGZw24sdIyayIX5dn9hrKkNrZsW
detWY3KJFylSulykS/dfJ871IT+8dXPU5A7WqG4+
-----END CERTIFICATE-----";

try
{   
    plugin.importCertificate(deviceId, certpem, plugin.CERT_CATEGORY_USER);
}
catch (error) 
{
    console.log(error);
}

6. Вызовом функции deleteCertificate можно удалить сертификат с токена.

Работа с ключевыми парами ГОСТ Р 34.10-2001

...

error);
}


2. Для генерации ключевой пары требуется ввод PIN-кода. При генерации ключа можно задать параметры ключевой пары. Если опция не задана, будут выбраны параметры А для любого из алгоритмов ГОСТ.

  • ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит: 
    • "A"
    • "B"
    • "C"
    • "XA"
    • "XB"
  • ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит
    • "A"
    • "B"


Code Block
languagejs
titleПример генерации ключевой пары ГОСТ Р 34.10-2012:
var options = {};
var keyId;

try 
{
    keyId = plugin.generateKeyPair(deviceId, undefined, marker, options);
}
catch (error) 
{
    console.log(error);
}

3. С помощью функции deleteKeyPair ключевая пара может быть удалена с токена.

Конфигурирование openssl


См. инструкцию Интеграция ГОСТ 2012 с Рутокен ЭЦП и OpenSSL 1.1.0 или новее, раздел Установка и настройка OpenSSL

...

Code Block
languagejs
var keys = Array();

try
{   
    plugin.login(deviceId, "12345678");
    keys = plugin.enumerateKeys(deviceId, null);
}
catch (error) 
{
    console.log(error);
}

...

  • A: id-GostR3410-2001-CryptoPro-A-ParamSet
  • B: id-GostR3410-2001-CryptoPro-B-ParamSet
  • C: id-GostR3410-2001-CryptoPro-C-ParamSet
  • XA: id-GostR3410-2001-CryptoPro-XchA-ParamSet
  • XB: id-GostR3410-2001-CryptoPro-XchB-ParamSet
Code Block
languagejs
titleПример генерации ключевой пары ГОСТ Р 34.10-2001:
var options = {};
var keyId;

try 
{
    keyId = plugin.generateKeyPair(deviceId, "A",  null, options);
}
catch (error) 
{
    console.log(error);
}

3. С помощью функции deleteKeyPair ключевая пара может быть удалена с токена.

Конфигурирование openssl

...

Code Block
[openssl_def]
engines = engine_section

[engine_section]
gost = gost_section

[gost_section]
engine_id = gost
default_algorithms = ALL

Если конфигурационный файл openssl не расположен в стандартном месте, то путь к нему можно задать через переменную окружения OPENSSL_CONF. 

 Другим вариантом подгрузки engine gost является ее передача в параметрах командной строки утилиты openssl.
Если engine gost не расположена в стандартном месте, то через переменную окружения OPENSSL_ENGINES можно задать путь к директории, в которой openssl будет ее искать.
Для получения информации о том, успешен ли был вызов утилиты openssl или нет, с возможностью уточнения ошибки, требуется парсить stdout и stderror. В конце статьи приведена ссылка на PHP-скрипт, который использует данную утилиту.


Теперь перейдем к реализации законченных пользовательских сценариев.

Регистрация на портале

Сертификат выдается при регистрации в системе

  • Получаем список подключенных к компьютеру устройств Рутокен ЭЦПЭЦП 2.0
  • Генерируем ключевую пару по ГОСТ Р 34.10-2001 2012 на выбранном Рутокен ЭЦПЭЦП 2.0
  • Cоздаем запрос PKCS#10 на сертификат для сгенерированной ключевой пары
  • Отправляем запрос на сервер
  • На сервере создаем сертификат, привязываем к аккаунту (сам сертификат или его дескриптор). Следует отметить, что дескрипторы сертификатов, полученные при вызове функции enumerateCertificates, являются уникальными и неизменными
  • Отправляем сертификат на клиент
  • На клиенте визуализируем полученный сертификат
  • Импортируем полученный сертификат в Рутокен ЭЦПЭЦП 2.0


Последовательность вызовов в клиентском скрипте будет следующей:

...

Code Block
languagebash
openssl genpkey -engine gost -algorithm GOST2001gost2012_256 -pkeyopt paramset:A -out ca.key

...

Code Block
languagebash
openssl req -engine gostutf8 -x509 -new -key ca.key -out ca.crt 

После ввода необходимой информации об издателе в файле ca.crt будет создан сертификат УЦ.

Полученный от клиента запрос сохраняем в файл user.csr и выдаем на его основе сертификат (без модификации данных из запроса):

Code Block
languagebash
openssl ca -engine gost -keyfile ca.key -cert ca.crt -in user.csr -out user.crt -outform PEM -batch

После этого в файле user.crt создается сертификат пользователя в PEM формате. Его следует отправить на клиент.
 

Дальнейшая последовательность вызовов на клиенте:

 

 

Сертификат уже имеется на токене, выдан внешним УЦ

Ключевая пара при этом должна быть создана в формате, совместимом с библиотекой rtPKCS11ECP для Рутокен ЭЦП 2.0.

  • Получаем список подключенных к компьютеру устройств Рутокен ЭЦПЭЦП 2.0
  • Получаем список всех имеющихся пользовательских сертификатов на выбранном Рутокен ЭЦПЭЦП 2.0
  • Визуализируем каждый сертификат
  • Пользователь выбирает нужный сертификат
  • Сервер формирует начальную последовательность случайных данных (строку salt) и отправляет ее на клиент
  • Вызываем на клиенте authenticate. При передаче salt в функцию плагина authenticate данная последовательность дополняется дополнительными случайными данными размером в 32 символа, и происходит подпись итоговой последовательности на выбранном пользователем сертификате в формате CMS attached
  • Подпись отправляется на сервер
  • На сервере происходит проверка CMS attached подписи с использованием корневого сертификата
  • Из CMS attached сообщения извлекается итоговая случайная последовательность, “отсоединяется” salt и происходит сравнение
  • Если сравнение успешно, то регистрируем пользователя по сертификату, который содержится в CMS attached сообщении

...

Code Block
languagebash
titleПроверка подписи на сервере:
openssl cms -engine gost -verify -in sign.cms -inform PEM -CAfile ca.crt -out data.file -certsout user.cr

...

Code Block
languagebash
titleПоказать DN субъекта (subject):
openssl x509 -in cert.pem -noout -subject


 

 

Code Block
languagebash
titleПоказать DN издателя (issuer):
openssl x509 -in cert.pem -noout -issuer

...


 

Code Block
languagebash
titleПоказать почтовый адрес субъекта:
openssl x509 -in cert.pem -noout -email

...

Code Block
languagebash
titleПоказать время окончания действия сертификата:
openssl x509 -in cert.pem -noout -enddate

Строгая аутентификация на портале

Общая схема аутентификации, используемая в Рутокен Плагин, выглядит следующим образом: 

  • сервер формирует начальную последовательность случайных данных (строку salt) и отправляет ее на клиент
  • при передаче salt в функцию плагина authenticate данная последовательность дополняется случайными данными размером в 32 символа, и происходит подпись итоговой последовательности на выбранном пользователем сертификате в формате CMS attached
  • подпись отправляется на сервер
  • на сервере происходит проверка подписи
  • из CMS attached сообщения извлекается итоговая случайная последовательность, “отсоединяется” salt и происходит сравнение
  • в случае успешной проверки пользователь аутентифицируется на основе сертификата, извлеченного из сообщения CMS


Реализация данной схемы ничем принципиально не отличается от «Регистрация, сертификат уже имеется, выдан внешним УЦ».

Электронная подпись данных и/или файлов в формате CMS

  • формируется текстовое сообщение (строка), формирование сообщения может происходить как на сервере, так и на клиенте
  • если требуется подписать документ произвольного формата (например, PDF), то требуется перекодировать его в формат base64
  • строка, содержащая данные для подписи, передается в функцию sign
  • если строка представляет собой закодированные в base64 данные, то параметр функции isBase64 должен быть установлен в true, при этом перед подписью произойдет декодирование данных из base64
  • если требуется использовать аппаратное вычисление хэш-функции ГОСТ Р 34.11-94 (сертифицированная реализация, скорость 60-70 Кб/c), то в options нужно установить опцию useHardwareHash в true. Если данная опция установлена в false, то будет использована быстрая программная реализация хэш-функции ГОСТ Р 34.11-942012
  • если требуется сформировать “отсоединенную” (detached) подпись CMS, то нужно установить опцию detached в true, иначе будет сформирована “присоединенная” (attached) подпись
  • для того, чтобы включить/не включить пользовательский сертификат в подписанное CMS-сообщение существует опция addUserCertificate
  • Установка опции addSignTime в true приведет к тому, что в подписанное CMS-сообщение будет добавлено системное время в качестве подписанного атрибута

Проверка подписи на сервере описана выше.

Шифрование/расшифрование данных и/или файлов в формате CMS

Шифрование данных на клиенте для сервера

Для того, чтобы обеспечить конфиденциальность обмена данными между клиентом и сервером в плагине предусмотрено шифрование/расшифрование данных. Данные шифруются в формате CMS. Для того, чтобы зашифровать данные в формате CMS, требуется сертификат открытого ключа «адресата». При этом расшифровать такое сообщение сможет только владелец закрытого ключа. При шифровании данных для сервера рекомендуется хранить сертификат сервера на Рутокен ЭЦП 2.0. Этот сертификат может быть записан на устройство при регистрации пользователя на портале. Для этого следует использовать функцию importCertificate, при этом в качестве параметра category следует передать CERT_CATEGORY_OTHER. Для использования в функции cmsEncrypt нужно получить тело сертификата по его дескриптору с помощью функции getCertificate. При этом дескриптор является уникальным и неизменным и может быть сохранен в учетной записи пользователя на сервере при импорте сертификата сервера. Для того, чтобы использовалось аппаратное шифрование по ГОСТ 28147-89, требуется установить опцию useHardwareEncryption в true. В противном случае будет использована быстрая программная реализация ГОСТ 28147-89. 

Последовательность вызовов приведена на картинке:

...

Code Block
languagebash
titleРасшифрование данных на сервере
openssl smimecms -engine gostdecrypt -decryptbinary -in message.cms -inform PEM -recip recipientrespondent.crtcer -inkey recipient.key -out drecipient.crt

recipient.crt — сертификат того, для кого зашифровано сообщение, recipient.key — ключ того, для кого зашифровано сообщение.

Расшифрование данных, полученных с сервера, на клиенте

Для расшифрования данных, полученных с сервера, предназначена функция cmsDecrypt. Так как сервер шифрует для клиента, используя его сертификат, то в качестве keyId должен быть передан дескриптор закрытого ключа клиента, соответствующий открытому ключу в сертификате. Этот дескриптор является уникальным и неизменным и потому может быть сохранен в учетной записи пользователя на сервере. Кроме того, дескриптор ключа пользователя может быть получен явным образом, путем вызова функциифункции getKeyByCertificate.

Code Block
languagebash
titleШифрование данных на сервере для клиента:
openssl smimecms -encrypt -engine gostbinary -gost89 -binary -outform PEMgost28147-paramset_a-cfb -in data.file -out message.enc -outform PEM user.crt 


Code Block
languagejs
titleРасшифрование данных на клиенте:
var data;
var options = {};
try
{
    data = plugin.cmsDecrypt(deviceId, keyId, cms, options);
}
catch (error) 
{
    console.log(error);
}

Полезные ссылки


Данные ссылки могут быть полезны разработчикам инфосистем с поддержкой ЭЦП ЭП на базе Рутокен Плагин и openssl:

Демосистема Рутокен Плагин
WEB-сервис генерации ключей, формирования запросов, управления сертификатами, формирования шаблонов запросов на сертификаты 
Документация по использованию утилиты openssl с российскими крипталгоритмами
Пример скрипта на PHP, использующего утилиту openssl