В этом документе описывается использование rtengine через инструменты
командной строки OpenSSL.

НАСТРОЙКА

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

    openssl_conf = openssl_def

    [ openssl_def ]
    engines = engine_section

    [ engine_section ]
    rtengine = gost_section

    [ gost_section ]
    dynamic_path = /path/to/librtengine.so
    default_algorithms = CIPHERS, DIGEST, PKEY, RAND

dynamic_path - путь до библиотеки rtengine.
В переменную среды OPENSSL_CONF запишите путь до кофигурационного файла.
Например, для bash выполните:

    export OPENSSL_CONF=/path/to/openssl.cnf

Для windows cmd:

    set OPENSSL_CONF=C:\path\to\openssl.cnf

Для формирования псевдослучайной последовательности на токене установите
значения для MODULE_PATH и RAND_TOKEN в openssl.cnf в секции [ gost_section ]:

    [ gost_section ]
    dynamic_path = /path/to/librtengine.so
    MODULE_PATH = /path/to/librtpkcs11ecp.so
    RAND_TOKEN = pkcs11:manufacturer=Aktiv%20Co.;model=Rutoken%20ECP;serial=2adc8d87
    default_algorithms = CIPHERS, DIGEST, PKEY, RAND

MODULE_PATH - путь до библиотеки rtpkcs11ecp.
RAND_TOKEN - идентификатор токена согласно rfc7512 (pkcs11 uri https://tools.ietf.org/html/rfc7512).
Возможные компоненты идентификатора:
    manufacturer: ID производителя токена;
    model: модель токена;
    serial: серийный номер токена;
    token: метка токена (поле "label").

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

Изменение порядка строк в секции [ gost_section ] в приведенном файле
конфигурации может привести к неработоспособности библиотеки.

После успешной настройки все операции по формированию псевдослучайной
последовательности будут производится на указанном токене.
Пример выработки псевдослучайной последовательности:
    openssl rand -engine rtengine -out rand_file 20

ИСПОЛЬЗОВАНИЕ КЛЮЧЕЙ НА ТОКЕНЕ

rtengine позволяет использовать ключи, расположенные на токене.
Ключевая пара идентифицируется с помощью описанного выше pkcs11 uri.
К уже описанным компонентам идентификатора добавляются:
    object: имя объекта (CKA_LABEL)
    id: идентификатор объекта (CKA_ID)

Пример идентификатора ключевой пары на токене:
    pkcs11:manufacturer=Aktiv%20Co.;model=Rutoken%20ECP;serial=2adc8d87;object=my%20label;id=%aa%bb%cc%dd

В зависимости от операции будет выбран открытый или закрытый ключ
соответственно. Вследствие этого оба ключа пары должны иметь одинаковый
идентификатор объекта и/или имя объекта.

Примеры реального применения находятся в соответствующих пунктах.

ИСПОЛЬЗОВАНИЕ В КОМАНДНОЙ СТРОКЕ

1. Генерация закрытого ключа

  Программно:
    openssl genpkey -algorithm gost2012_256 -pkeyopt paramset:A -out seckey.pem

  Аппаратная генерация не поддерживается.

  Укажите алгоритм, используя опцию -algorithm.
  Укажите парамсет с помощью -pkeyopt.
  Поддерживаются следующие значения алгоритмов и соответствующих им парамсетов:
    gost2001: A,B,C,XA,XB
    gost2012_256: A,B,C,XA,XB
    gost2012_512: A,B

2. Создание запроса на сертификат

  Программно:
    openssl req -utf8 -new -key seckey.pem -out req.csr

  Аппаратно:
    openssl req -utf8 -new -keyform engine -key "your_pkcs11_uri" -engine rtengine -out req.csr

3. Вычисление хеш-функции

    openssl dgst -md_gost94 test_data

  Поддерживаемые опции:
    -md_gost94
    -md_gost12_256
    -md_gost12_512

4. Вычисление HMAC на основе алгоритмов вычисления хеш-функции ГОСТ

    openssl dgst -md_gost12_256 -mac hmac -macopt key:<32 bytes of key> test_data

  Возможные алгоритмы совпадают с пунктом 3.
  Для указания ключа в шестнадцатеричном формате используйте опцию hexkey вместо key.

5. Подпись

  Программно:
    openssl dgst -sign seckey.pem -out signature test_data

  Аппаратно:
    openssl dgst -keyform engine -sign "your_pkcs11_uri" -engine rtengine -out signature test_data

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

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

  Получить открытый ключ из закрытого можно следующей командой:
    openssl pkey -in seckey.pem -pubout -out pubkey.pem

  Программная проверка:
    openssl dgst -verify pubkey.pem -signature signature test_data

  Аппаратная:
    openssl dgst -keyform engine -verify "your_pkcs11_uri" -engine rtengine -signature signature test_data

7. CMS подпись

  Для создания CMS подписи необходимо иметь сертификат. В тестовых
  целях в проекте предоставлены настройки для удостоверяющего центра
  openssl, который позволяет выпускать сертификаты.
  Используя тестовый конфигурационный файл выполните из папки проекта:
    openssl ca -batch -in req.csr -out cert.cer

  Затем создайте CMS подпись.
  Программно:
    openssl cms -sign -binary -nosmimecap -in test_data -out signed_cms -outform PEM -inkey seckey.pem -signer cert.cer

  Аппаратно:
    openssl cms -sign -binary -nosmimecap -in test_data -out signed_cms -outform PEM -keyform engine -inkey "your_pkcs11_uri" -engine rtengine -signer cert.cer

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

8. Проверка CMS подписи

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

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

9. CMS зашифрование

    openssl cms -encrypt -binary -gost28147-paramset_a-cfb -in test_data -out encrypted_cms -outform PEM cert.cer

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

10. CMS расшифрование

  Программно:
    openssl cms -decrypt -binary -in encrypted_cms -inform PEM -recip cert.cer -inkey seckey.pem -out decrypted_cms_data

  Аппаратно:
    openssl cms -decrypt -binary -in encrypted_cms -inform PEM -recip cert.cer -keyform engine -inkey "your_pkcs11_uri" -engine rtengine -out decrypted_cms_data

11. Запуск SSL/TLS сервера/клиента

  Сервер, программный ключ:
    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 -keyform engine -key "server_key_pkcs11_uri" -engine rtengine -cert demoCA/cacert.pem -Verify 7 -CAfile demoCA/cacert.pem -accept 44330 -WWW -purpose any -4

  Клиент, программный ключ:
    openssl s_client -host 127.0.0.1 -port 44330 -cert cert.cer -key seckey.pem

  Клиент, аппаратный ключ:
    openssl s_client -host 127.0.0.1 -port 44330 -cert cert.cer -keyform engine -key "client_key_pkcs11_uri" -engine rtengine
