Общая информация

В данной статье описаны следующие сценарии использования Рутокена с OpenSSL:

генерация ключевой пары в файл с помощью алгоритмов ГОСТ, ECDSA, RSA;
генерация ключевой пары на токене с помощью алгоритмов ГОСТ, ECDSA, RSA;
просмотр записанных на токен объектов;
формирование запроса PKCS #10;
выпуск самоподписанного сертификата по запросу;
зашифрование и расшифрование в формате CMS;
подпись «сырой» подписью;
проверка «сырой» подписи;
запуск SSL/TLS клиента/сервера.

Для использования ключей с токена необходимо специальным образом указывать идентификатор ключа. Подробнее этот идентификатор описан в разделе Использование ключей на Рутокене.

Начало работы

Перед тем, как приступить к выполнению описанных ниже сценариев, установите и настройте OpenSSL и rtengine:

Для генерации ключевых пар на токене также понадобится pkcs11-tool из состава OpenSC.

Использование ключей на Рутокене

rtengine позволяет использовать ключи, расположенные на токене. В зависимости от операции будет выбран открытый или закрытый ключ соответственно.

Оба ключа пары должны иметь одинаковый идентификатор объекта и/или имя объекта. Ключевая пара идентифицируется с помощью pkcs11 uri.

Этот идентификатор соответствует аргументу "pkcs11:your_pkcs11_uri" в примерах команд, которые используют ключи на токене.

Возможные компоненты идентификатора пути:

Компонент Описание

manufacturer ID производителя токена

model Модель токена

serial Серийный номер токена

token Метка токена(поле "label")

object Имя объекта(CKA_LABEL)

id

Идентификатор объекта (CKA_ID)

Если ключевая пара была сгенерирована с помощью pkcs11-tool, чтобы использовать ID объекта в URI, нужно конвертировать его в ASCII. Сделать это можно с помощью онлайн-сервиса конвертации HEX в ASCII.
Например, для ключевой пары ГОСТ с "--id 3132" в PKCS #11 URI нужно указать "pkcs11:id=12".

Пример идентификатора ключевой пары на токене:

pkcs11:manufacturer=Aktiv%20Co.;model=Rutoken%20ECP;serial=2adc8d87;object=my%20label;id=%aa%bb%cc%dd?pin-value=12345678

Если подключен только один Рутокен с единственной ключевой парой, для идентификации можно использовать только модель:

pkcs11:model=Rutoken%20ECP

Генерация ключевой пары в файл

Формат команды:

openssl genpkey -algorithm alg ‑pkeyopt opt:value [‑pkeyopt opt:value]... ‑out filename.pem

Описание параметров:

Параметр Описание

‑algorithm Алгоритм шифрования

‑pkeyopt

Настройки алгоритма (размер ключа, тип эллиптической кривой, и т.д.). Задает для параметра алгоритма opt значение value.

Может быть использован несколько раз, если у алгоритма есть несколько изменяемых параметров. Например:

openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3

‑out

Название файла, в который будет записана ключевая пара. По умолчанию создается в том же каталоге, откуда была вызвана команда.

Чтобы сохранить файл в другой каталог, укажите в параметре -out полный путь к этому каталогу, включая название файла:

-out /путь/к/файлу.pem

Генерация ключевой пары ГОСТ в файл

Пример:

openssl genpkey ‑algorithm gost2012_256 ‑pkeyopt paramset:A ‑out privatekey.pem

Значения параметров:

Параметр Возможные значения

‑algorithm

gost2001;
gost2012_256;
gost2012_512

‑pkeyopt

paramset:<value>

Поддерживаемые значения value в зависимости от алгоритма:

gost2001:
- A;
- B;
- C;
- XA;
- XB.
gost2012_256:
- A;
- B;
- C;
- id-GostR3410-2001-CryptoPro-A-ParamSet;
- id-GostR3410-2001-CryptoPro-B-ParamSet;
- id-GostR3410-2001-CryptoPro-C-ParamSet.
gost2012_512:
- A;
- B;
- C.

Параметры кривых, соответствующие значениям, описаны в Приложении 1.

Генерация ключевой пары ECDSA в файл

Пример:

openssl genpkey ‑algorithm EC ‑pkeyopt ec_paramgen_curve:secp256r1 ‑out privatekey.pem

Значения параметров:

Параметр Возможные значения

‑algorithm

EC

‑pkeyopt

ec_param_enc:<encoding> — определение параметров кривой. Может принимать значение named_curve (используется существующая кривая) или explicit (параметры кривой задаются вручную; не рекомендуется с точки зрения безопасности и совместимости).
Значение encoding по умолчанию: named_curve.
ec_param_curve:<curve> — название эллиптической кривой.
Чтобы посмотреть список эллиптических кривых, поддерживаемых установленной версией OpenSSL, выполните команду:
openssl ecparam ‑list_curves

Генерация ключевой пары RSA в файл

Пример:

openssl genpkey ‑algorithm RSA -pkeyopt rsa_keygen_bits:2048 ‑out rsakey.pem

Значения параметров:

Параметр Возможные значения

‑algorithm

RSA

‑pkeyopt

rsa_keygen_bits:<numbits> — длина ключа в битах.
Значение numbits по умолчанию: 2048
rsa_keygen_primes:<numprimes> — количество простых чисел в генерируемом ключе.
Значение numprimes по умолчанию: 2
rsa_keygen_pubexp:<value> — значение открытой экспоненты. Может быть представлено в десятичной или шестнадцатеричном системе (для этого перед значением нужно поставить 0x).
Значение value по умолчанию: 65537

Генерация ключевой пары на Рутокене

Через OpenSSL генерация ключевых пар на Рутокене пока не поддерживается. Используйте для этого pkcs11-tool из состава OpenSC.

Генерация ключевой пары ГОСТ

Формат команды:

pkcs11-tool ‑‑module mod ‑‑login ‑‑pin pin ‑‑keypairgen ‑‑key‑type specification ‑‑id id ‑‑usage‑derive

Описание параметров:

Параметр Описание

‑‑module Модуль или библиотека PKCS #11, которая будет использована для генерации ключевой пары

‑‑login, ‑l Параметр используется, чтобы потребовать аутентификацию на токене перед выполнением операции.
Параметр ‑‑login не обязателен, если используется параметр ‑‑pin

‑‑pin, ‑‑p PIN‑код, который будет использован для подтверждения генерации ключевой пары.
Использование параметра ‑‑pin автоматически включает параметр ‑‑login

‑‑keypairgen, ‑k Тип операции (генерация новой ключевой пары)

‑‑key‑type

Тип и параметры алгоритма шифрования (размер ключа, параметры эллиптической кривой, и т.д.).

‑‑id, ‑d

Идентификатор объекта (CKA_ID) в виде двузначных номеров символов в hex из таблицы ASCII.

Чтобы использовать этот ID через OpenSSL, нужно использовать символы, соответствующие этим кодам.
Например, для ключевой пары ГОСТ с ID "‑‑id 3132" в PKCS #11 URI нужно указать "pkcs11:id=12".
Конвертировать ID в формат, подходящий для работы с OpenSSL, можно с помощью онлайн-сервиса конвертации HEX в ASCII.

‑‑usage‑derive

Параметр указывает на то, что на сгенерированном ключе можно вырабатывать общий симметричный ключ, который может использоваться, например, для расшифрования CMS-сообщений.

Если шифрование сообщений на генерируемой ключевой паре не планируется, этот параметр можно не использовать.

ГОСТ-2001

Пример:

pkcs11-tool ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑‑login ‑‑pin 12345678 ‑‑keypairgen ‑‑key‑type GOSTR3410:A ‑‑id 3132 ‑‑usage‑derive

Значения параметров:

Параметр Возможные значения

‑‑module

Для Windows:

/путь/к/файлу/rtPKCS11ECP.dll

Для Linux:

/путь/к/файлу/librtpkcs11ecp.so

‑‑key‑type

GOSTR3410-2001:A;
GOSTR3410-2001:B;
GOSTR3410-2001:C.

Более подробно значения описаны в Приложении 1.

ГОСТ-2012

Собирайте ветку pkcs11-tool с поддержкой ГОСТ-2012 или используйте релиз OpenSC 0.20.0 или новее.

Пример:

pkcs11-tool ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑‑login ‑‑pin 12345678 ‑‑keypairgen ‑‑key‑type GOSTR3410‑2012‑256:B ‑‑id 3132 ‑‑usage‑derive

Значения параметров:

Параметр Возможные значения

‑‑module

Для Windows:

/путь/к/файлу/rtPKCS11ECP.dll

Для Linux:

/путь/к/файлу/librtpkcs11ecp.so

‑‑key‑type

Для алгоритма GOSTR3410-2012-256:

GOSTR3410-2012-256:B;
GOSTR3410-2012-256:C;
GOSTR3410-2012-256:D.

Для алгоритма GOSTR3410-2012-512:

GOSTR3410-2012-512:A;
GOSTR3410-2012-512:B;
GOSTR3410-2012-512:C.

Более подробно значения описаны в Приложении 1.

Генерация ключевой пары ECDSA

Пример:

pkcs11-tool ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑‑login ‑‑pin 12345678 ‑‑keypairgen ‑‑key‑type EC:secp256r1 ‑‑id 3132 ‑‑usage‑derive

Значения параметров:

Параметр Возможные значения

‑‑module

Для Windows:

/путь/к/файлу/rtpkcs11ecp.dll

Для Linux:

/путь/к/файлу/librtpkcs11ecp.so

‑‑key‑type

Для Рутокен ЭЦП 3.0 3110 и 3220:

EC:secp256r1;
EC:secp256k1.

Для Рутокен ЭЦП 3.0 3120:

EC:secp256r1;
EC:secp256k1;
EC:secp384r1;
EC:secp521r1.

Генерация ключевой пары RSA

Пример:

pkcs11-tool ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑‑login ‑‑pin 12345678 ‑‑keypairgen ‑‑key‑type RSA:2048 ‑‑id 3132

Значения параметров:

Параметр Возможные значения

‑‑module

Для Windows:

/путь/к/файлу/rtpkcs11ecp.dll

Для Linux:

/путь/к/librtpkcs11ecp.so

‑‑key‑type

Использовать 1024-битные ключи RSA небезоспано.
Рекомендуем использовать как минимум 2048-битные ключи.

Для Рутокен ЭЦП 2.0:

RSA:1024;
RSA:2048.

Для Рутокен ЭЦП 3.0:

RSA:1024;
RSA:2048;
RSA:4096.

Просмотр объектов на токене

Посмотреть записанные на токен объекты можно с помощью команды:

pkcs11-tool ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑Ol

Формирование запроса PKCS#10

Сформировать запрос можно:

с помощью ключа в файле:
openssl req ‑utf8 ‑new ‑key privatekey.pem ‑out req.csr
с помощью ключа на Рутокене:
openssl req ‑utf8 ‑new ‑keyform engine ‑key "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑out req.csr

В процессе работы команда попросит ввести PIN-код. После этого потребуется указать данные для сертификата.

Набор вводимой информации при формировании запроса определяется конфигурационным файлом openssl.cnf. По умолчанию нужно заполнить следующие поля:

Поле	Описание
`C`	CountryName Страна
`ST`	StateOrProvinceName Регион или область
`L`	Locality Населенный пункт (город, село, поселок и т.д.)
`O`	Organization Название организации
`OU`	OrganizationalUnit Название отдела в организации
`CN`	CommonName Имя владельца сертификата
`emailAddress`	Почтовый адрес владельца сертификата

Выпуск самоподписанного сертификата по запросу

Самоподписанный сертификат можно выпустить:

с помощью ключа в файле:
openssl req ‑utf8 ‑x509 ‑key /путь/к/файлу/privatekey.pem ‑out cert.cer

с помощью ключа на Рутокене:

openssl req ‑utf8 ‑x509 ‑keyform engine ‑key "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑out cert.cer ‑subj "/C=<страна>/ST=<регион>/L=<населенный_пункт>/O=<организация>/OU=<отдел>/CN=<ФИО>/emailAddress=<email>"

Подробнее параметры сертификата описаны в предыдущем разделе.

Работа с подписью в формате CMS

Создание подписи

По умолчанию команда openssl cms ‑sign создает открепленную подпись (подпись, которая сохраняется в отдельный файл), а сертификат подписанта включается в состав CMS-пакета. Изменить это поведение можно с помощью двух опциональных параметров:

‑nodetach включает подписываемые данные в состав CMS-пакета и создает присоединенную подпись:
‑nocerts исключает сертификат подписанта из состава CMS-пакета.

Для создания CMS-подписи необходимо иметь сертификат. В тестовых целях в Рутокен SDK предоставлены настройки удостоверяющего центра OpenSSL, который позволяет выпускать сертификаты.

Для того, чтобы создать CMS-подпись с помощью предоставленного УЦ:

Скачайте Рутокен SDK и распакуйте архив.
Из распакованного архива скопируйте папку /sdk/openssl/samples/tool/demoCA и конфигурационный файл openssl.cnf в папку с OpenSSL.
Выполните команду:
openssl ca ‑batch ‑in req.csr ‑out cert.cer
Создайте CMS-подпись:
- с помощью ключа в файле:
  openssl cms ‑sign ‑binary ‑nosmimecap ‑in data_to_sign ‑out signed_cms ‑outform PEM ‑inkey privatekey.pem ‑signer cert.cer
- с помощью ключа на Рутокене:
  openssl cms ‑sign ‑binary ‑nosmimecap ‑in data_to_sign ‑out signed_cms ‑outform PEM ‑keyform engine ‑inkey "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑signer cert.cer

Проверка подписи

Чтобы проверить подпись, выполните команду:

openssl cms ‑verify ‑binary ‑in signed_cms ‑inform PEM ‑out verified_data ‑CAfile demoCA/cacert.pem ‑content data_to_sign

Файл, указанный в ‑CAfile, является доверенным сертификатом удостоверяющего центра и используется для проверки сертификата подписанта.

В опцию ‑content передается файл с подписанными данными, если он не был включен в состав CMS пакета.

Если сертификат подписанта не был включен в CMS пакет (отсоединенная подпись), он указывается в опции ‑certfile.

Шифрование в формате CMS

Зашифрование

При расшифровании сообщения вырабатывается общий симметричный ключ. Этот же ключ используется при расшифровке. Рутокен позволяет генерировать такой общий ключ только на неизвлекаемых закрытых ключах с опцией derive в поле key usage. Для того, чтобы указать эту опцию, при генерации ключа используйте флаг ‑‑usage‑derive. Например:

pkcs11‑tool.exe ‑‑module /путь/к/библиотеке/rtPKCS11ECP ‑‑login ‑‑pin 12345678 ‑‑keypairgen ‑‑key‑type GOSTR3410‑2012‑256:B ‑‑id 3132 ‑‑usage‑derive

Формат команды:

openssl cms ‑encrypt ‑binary ‑<cipher> ‑in data_to_encrypt ‑out encrypted_cms ‑outform DER|PEM|SMIME respondent.cer

Описание параметров:

Параметр	Описание
`‑encrypt`	Тип операции (зашифрование)
`‑binary`	По умолчанию, входное сообщение конвертируется в канонический формат, который использует CR и LF в качестве знака перевода строки (в соответствии со по спецификацией S/MIME). Параметр `‑binary` отключает эту конвертацию.
`‑<cipher>`	Алгоритм шифрования. Возможные значения зависят от типа ключа. Для ключей ГОСТ и rtengine версии 0.7: `gost28147‑paramset_a‑cfb` — алгоритм, который работает в режиме гаммирования с обратной связью с набором параметров А. Для ключей ГОСТ и rtengine версии 0.7 и выше: `gost28147-cfb` — алгоритм, который работает в режиме гаммирования с обратной связью с набором параметров Z. Для RSA и ECDSA ключей: `aes128` — AES-128; `aes192` — AES-192; `aes256` — AES-256; `des` — DES; `des3` — Triple DES (3DES)
`‑in`	Входное сообщение, которое нужно зашифровать
`‑out`	Название файла, в который будет сохранено зашифрованное сообщение
`‑outform`	Формат CMS-структуры. Значение по умолчанию: SMIME
`respondent.cer`	Cертификат адресата, для которого шифруется сообщение

Расшифрование на стороне адресата

Расшифровать данные можно:

с помощью ключа в файле:
openssl cms ‑decrypt ‑binary ‑in encrypted_cms ‑inform PEM ‑recip respondent.cer ‑inkey privatekey.pem ‑out decrypted_cms_data
с помощью ключа на Рутокене:
openssl cms ‑decrypt ‑binary ‑in encrypted_cms ‑inform PEM ‑recip respondent.cer ‑keyform engine ‑inkey "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑out decrypted_cms_data

Работа с «сырыми» подписями

Подпись данных

Подписать данные «сырой» подписью можно:

с помощью ключа в файле:
openssl dgst ‑sign privatekey.pem ‑out file_to_sign.sig file_to_sign.txt
с помощью ключа на Рутокене:
openssl dgst ‑keyform engine ‑sign "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑out file_to_sign.sig file_to_sign.txt
Алгоритм хеша будет зависеть от алгоритма ключа.

Проверка «сырой» подписи

Получите открытый ключ из закрытого:
openssl pkey -in privatekey.pem ‑pubout ‑out publickey.pem
Проверьте подпись:
- с помощью ключа в файле:
  openssl dgst ‑verify publickey.pem ‑signature signed_file.sig signed_file.txt
- с помощью ключа на Рутокене:
  openssl dgst ‑keyform engine ‑verify "pkcs11:your_pkcs11_uri" ‑engine rtengine ‑signature signed_file.sig signed_file.txt

Запуск SSL/TLS сервера

Формат команды:

openssl s_server ‑key filename|uri [‑keyform format] [‑engine id] ‑cert infile ‑Verify int ‑CAfile file ‑accept val ‑WWW ‑purpose purpose ‑4

Описание параметров:

Параметр	Описание
‑key	Название файла или URI закрытого ключа. Если параметр не задан, будет использован файл сертификата
‑keyform	Формат файла закрытого ключа. Значение по умолчанию: PEM
‑engine	Модуль для работы с криптографическими алгоритмами. Задается, если задан параметр `‑keyform engine`
‑cert	Путь к сертификату
‑Verify	Глубина проверки цепочки сертификатов
‑CAfile	Путь к доверенному сертификату
‑accept	TCP-порт, который будет прослушиваться в ожидании запросов. Значение по умолчанию: 4433
‑WWW	Эмуляция простого веб-сервера
‑purpose	Назначение сертификата. Возможные значения: `slclient`; `sslserver`; `nssslserver`; `mimesign;` `mimeencrypt`; `crlsign`; `ocsphelper`; `timestampsign`; `codesign`; `any.`
‑4	Использовать только IPv4

Примеры команд:

Ключ в файле
`openssl s_server ‑key demoCA/private/cakey.pem ‑cert demoCA/cacert.pem ‑Verify 7 ‑CAfile demoCA/cacert.pem ‑accept 44330 ‑WWW ‑purpose any ‑4`

Ключ на токене
`openssl s_server ‑key "pkcs11:server_key_pkcs11_uri" ‑keyform engine ‑engine rtengine ‑cert demoCA/cacert.pem ‑Verify 7 ‑CAfile demoCA/cacert.pem ‑accept 44330 ‑WWW ‑purpose any ‑4`

Запуск SSL/TLS клиента

Формат команды:

openssl s_client -key filename|uri [‑keyform format] [‑engine id] ‑cert filename ‑host hostname ‑port port

Описание параметров:

Параметр	Описание
‑key	Название файла или URI закрытого ключа. Если параметр не задан, будет использован файл сертификата
‑keyform	Формат файла закрытого ключа. Значение по умолчанию: PEM
‑engine	Модуль для работы с криптографическими алгоритмами. Задается, если задан параметр `‑keyform engine`
‑cert	Путь к сертификату
‑host	Адрес сервера, с которым нужно установить соединение
‑port	Порт сервера, с которым нужно установить соединение

Примеры команд:

Ключ в файле
`openssl s_client ‑key privatekey.pem ‑cert cert.cer ‑host 127.0.0.1 ‑port 44330`

Ключ на токене
`openssl s_client ‑key "pkcs11:client_key_pkcs11_uri" ‑keyform engine ‑engine rtengine ‑cert cert.cer ‑host 127.0.0.1 ‑port 44330`

Приложение 1. Парамсеты ГОСТ в OpenSSL и pkcs11‑tool

Таблица значений ‑pkeyopt для OpenSSL

ГОСТ 34.10-2001
Алгоритм	OID парамсета	Допустимое значение аргумента
`gost2001`	1.2.643.2.2.35.1	`A;` `id-GostR3410-2001-CryptoPro-A-ParamSet`
	1.2.643.2.2.35.2	`B;` `id-GostR3410-2001-CryptoPro-B-ParamSet`
	1.2.643.2.2.35.3	`C;` `id-GostR3410-2001-CryptoPro-C-ParamSet`
	1.2.643.2.2.36.0	`XA;` `id-GostR3410-2001-CryptoPro-XchA-ParamSet`
	1.2.643.2.2.36.1	`XB;` `id-GostR3410-2001-CryptoPro-XchB-ParamSet`
ГОСТ 34.10-2012-256
Алгоритм	OID парамсета	Допустимое значение аргумента
`gost2012_256`	1.2.643.7.1.2.1.1.1	`A;` `id-tc26-gost-3410-2012-256-paramSetA`
	1.2.643.7.1.2.1.1.2	`B;` `id-tc26-gost-3410-2012-256-paramSetB`
	1.2.643.7.1.2.1.1.3	`C;` `id-tc26-gost-3410-2012-256-paramSetC`
	1.2.643.7.1.2.1.1.4	`D;` `id-tc26-gost-3410-2012-256-paramSetD`
	1.2.643.2.2.35.1	`id-GostR3410-2001-CryptoPro-A-ParamSet`
	1.2.643.2.2.35.2	`id-GostR3410-2001-CryptoPro-B-ParamSet`
	1.2.643.2.2.35.3	`id-GostR3410-2001-CryptoPro-C-ParamSet`
	1.2.643.2.2.36.0	`id-GostR3410-2001-CryptoPro-XchA-ParamSet`
	1.2.643.2.2.36.1	`id-GostR3410-2001-CryptoPro-XchB-ParamSet`
ГОСТ 34.10-2012-512
Алгоритм	OID парамсета	Допустимое значение аргумента
`gost2012_512`	1.2.643.7.1.2.1.2.1	`A;` `id-tc26-gost-3410-2012-512-paramSetA`
	1.2.643.7.1.2.1.2.2	`B;` `id-tc26-gost-3410-2012-512-paramSetB`
	1.2.643.7.1.2.1.2.3	`C;` `id-tc26-gost-3410-2012-512-paramSetC`

Таблица значений --key-type для pkcs11-tool

ГОСТ 34.10-2001
Алгоритм	OID парамсета	Допустимое значение аргумента	Название парамсета
`GOSTR3410-2001`	1.2.643.2.2.35.1	A	id-GostR3410-2001-CryptoPro-A-ParamSet
	1.2.643.2.2.35.2	B	id-GostR3410-2001-CryptoPro-B-ParamSet
	1.2.643.2.2.35.3	C	id-GostR3410-2001-CryptoPro-C-ParamSet
ГОСТ 34.10-2012-256
Алгоритм	OID парамсета	Допустимое значение аргумента	Название парамсета
`GOSTR3410-2012-256`	1.2.643.7.1.2.1.1.2	B	id-tc26-gost-3410-12-256-paramSetB
	1.2.643.7.1.2.1.1.3	C	id-tc26-gost-3410-12-256-paramSetC
	1.2.643.7.1.2.1.1.4	D	id-tc26-gost-3410-12-256-paramSetD
ГОСТ 34.10-2012-512
Алгоритм	OID парамсета	Допустимое значение аргумента	Название парамсета
`GOSTR3410-2012-512`	1.2.643.7.1.2.1.2.1	A	id-tc26-gost-3410-12-512-paramSetA
`GOSTR3410-2012-512`	1.2.643.7.1.2.1.2.2	B	id-tc26-gost-3410-12-512-paramSetB