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

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

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

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

...

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

...

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

...

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

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

...

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

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

...

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

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

...

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

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

...

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

Пример:

...

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

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

...

• gost2001;
• gost2012_256;
• gost2012_512

...

• gost2001: A, B, C, XA, XB;
• gost2012_256: A, B, C, XA, XB;
• gost2012_512: A, B

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

Пример: 

...

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

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

...

EC

...

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

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

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

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

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

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

Перед тем, как приступить к работе, настройте OpenSSL и rtengine:

• Установка и настройка OpenSSL для работы с rtengine 1.4.0 и новее;
• Установка и настройка OpenSSL для работы с rtengine 0.7.x.

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

Anchor
on-token on-token

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

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

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

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

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

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

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

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

...

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

Пример:

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

...

RSA

...

• rsa_keygen_bits:<numbits> — .
  Значение numbits по умолчанию: 2048

• rsa_keygen_primes:<numprimes> — .
  Значение numprimes по умолчанию: 2

• rsa_keygen_pubexp:<value> — .
  Значение value по умолчанию: 65537

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

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

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

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

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

...

Откуда берётся ID? Или он задаётся пользователем самостоятельно? Зачем нужна часть про «использовать этот id через OpenSSL», если тут мы используем pkcs11-tool?

Идентификатор объекта (CKA_ID) в виде двузначных номеров символов в hex из таблицы ASCII.
Чтобы использовать этот id через OpenSSL надо использовать символы, соответствующие этим кодам. Например: для ‘--id 3132’ в OpenSSL надо указывать "pkcs11:id=12".  
Есть удобный онлайн-сервис конвертации строки в ASCII-коды

...

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

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

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

Пример:

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

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

Пример: 

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

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

Пример:

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

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

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

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

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

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

ГОСТ-2001

Пример:

ГОСТ-2001

Пример:

...

pkcs11-tool --module rtPKCS11ECP.dll --login --pin 12345678 --keypairgen --key-type GOSTR3410:A --id 3132 --usage-derive

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

...

• GOSTR3410:A;

• GOSTR3410:B;
• GOSTR3410:C

...

ГОСТ-2012

Пример:

...

pkcs11-tool --module rtPKCS11ECP.dll --login --pin 12345678 --keypairgen --key-type GOSTR3410-2012-256:B --id 3132 --usage-derive 

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

...

Для алгоритма 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.

...

Для удобства, можно воспользоваться онлайн-сервисом конвертации ACSII-кодов в строку.

Почему выше (и ниже) конвертация строки в коды, а тут кодов в строку? 

или

используйте веб-сервис "Центр регистрации Рутокен"

Для чего?

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

Пример:

...

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

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

Пример:

pkcs11-tool --module /путь/к/librtpkcs11ecp.so --login --pin 12345678 --keypairgen --key-type RSA:2048 --id 3132 

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

...

Для Windows:

...

/путь/к/

Для Linux:

...

/путь/к/librtpkcs11ecp.so

...

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

• RSA:1024 (небезопасно);
• RSA:2048.

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

• RSA:1024 (небезопасно);
• RSA:2048;
• RSA:4096.

...

ГОСТ-2012

Пример:

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

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

Пример:

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

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

Пример:

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

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

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

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

Формирование запроса 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. По умолчанию нужно заполнить следующие поля:

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

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

• с помощью ключа в файле:
  

  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

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

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

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

1. Скачайте Рутокен SDK и распакуйте архив.
2. Из распакованного архива скопируйте папку /sdk/openssl/samples/tool/demoCA и конфигурационный файл openssl.cnf в папку с OpenSSL.
3. Выполните команду:
   

   openssl ca -batch -in req.csr -out cert.cer

4. Создайте 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

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

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

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

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

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

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

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

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

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

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

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

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

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

...

pkcs11-tool --module rtPKCS11ECP.dll -Ol

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

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

• с помощью ключа в файле:
  

  openssl

req -utf8 -new -key

• cms -decrypt -binary -in encrypted_cms -inform PEM -recip respondent.cer -inkey privatekey.pem

• -out

req.csr

• decrypted_cms_data

• с помощью ключа на Рутокене:
  
openssl req -utf8 -new -keyform engine -key

• openssl cms -decrypt -binary -in encrypted_cms -inform PEM -recip respondent.cer -keyform engine -inkey "pkcs11:your_pkcs11_uri"

• -engine

• rtengine

• -out

req.csr

Tip
Формат параметра -key описан в разделе "Использование ключей на Рутокене"

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

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

• State or Province []: Moscow

• Locality []:  RU

• Organization Name []: Aktiv Company

• Organizational Unit Name []: development

• Common Name []: tester

• Email []: tester@rutoken.ru

Есть ли у этих полей обязательные значения или можно вместо Moscow/RU/Aktiv Company указать условно SomeCity/AU/SomeCompany)? Стоит здесь рассказать про CA и флаг match в конфиге? https://docs.openssl.org/1.0.2/man1/ca/#policy-format

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

• 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

  Алгоритм хеша будет зависеть от алгоритма ключа.

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

1. Получите открытый ключ из закрытого:
   

   openssl pkey -in privatekey.pem -pubout -out publickey.pem

2. Проверьте подпись

...

1. :
   • с помощью ключа в файле:
     

     openssl

...

1. • dgst -verify publickey.pem -signature signed_file.sig signed_file.txt

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

     openssl

...

1. • dgst -keyform engine -

...

1. • verify "pkcs11:your_pkcs11_uri" -engine rtengine -

...

Параметры сертификата:

...

C

...

CountryName

Страна

...

StateOrProvinceName

Регион или область

...

Locality

Населенный пункт (город, село, поселок и т.д.)

...

Organization

Название организации

...

OrganizationalUnit

Название отдела в организации

...

CommonName

Имя владельца сертификата

...

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

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

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

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

...

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

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

...

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

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

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

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

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

...

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

...

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

...

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

...

По умолчанию, входное сообщение конвертируется в канонический формат, который использует CR и LF в качестве знака перевода строки (в соответствии со по спецификацией S/MIME). Параметр -binary отключает эту конвертацию. 

...

Алгоритм шифрования. Возможные значения зависят от типа ключа.

Для ключей ГОСТ и rtengine версии 0.7:

• gost28147-paramset_a-cfb — алгоритм, который работает в режиме гаммирования с обратной связью с набором параметров А.

Для ключей ГОСТ и rtengine версии новее 0.7 («0.7 и новее» включительно или не включая 0.7?):

...

1. • signature signed_file.sig signed_file.txt

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

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

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

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

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

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

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

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

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

Anchor
gost gost

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

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

...

Для RSA и ECDSA ключей:

• aes128 — AES-128;
• aes192 — AES-192;
• aes256 — AES-256;
• des — DES;
• des3 — Triple DES (3DES)

...

Формат CMS-структуры.

Значение по умолчанию: SMIME

...

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

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

...

openssl cms -decrypt -binary -in encrypted_cms -inform PEM -recip respondent.cer -inkey privatekey.pem -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 сервера

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

...

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

...

Название файла или URI закрытого ключа.

Если параметр не задан, будет использован файл сертификата

...

Формат файла закрытого ключа.

Значение по умолчанию: PEM

...

Модуль для работы с криптографическими алгоритмами. 

Задается, если задан параметр -keyform engine

...

TCP-порт, который будет прослушиваться в ожидании запросов.

Значение по умолчанию: 4433

...

Назначение сертификата.

Возможные значения:

• slclient;
• sslserver;
• nssslserver;
• mimesign;
• mimeencrypt;
• crlsign;
• ocsphelper;
• timestampsign;
• codesign;
• any.

...

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

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 клиента

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

...

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

...

Название файла или URI закрытого ключа.

Если параметр не задан, будет использован файл сертификата

...

Формат файла закрытого ключа.

Значение по умолчанию: PEM

...

Модуль для работы с криптографическими алгоритмами. 

Задается, если задан параметр -keyform engine

...

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

openssl s_client -key privatekey.pem -cert cert.cer -host 127.0.0.1 -port 44330

...

...