Deploying the platform on a private network using GOST cryptography with PKI

Если вы планируете использовать ГОСТ криптографию с PKI, следуйте описанному ниже порядку создания аккаунтов нод, настройки TLS, подписания genesis-блока и ****** .

Создание аккаунта ноды c использованием ГОСТ криптографии с PKI

Create accounts for each node of your future network.

Аккаунт ноды включает в себя адрес, ключевую пару и сертификат X.509. Адрес, ключевая пара (публичный и приватный ключи ноды) и запрос на сертификат создаются при помощи утилиты GeneratePkiKeypair, которая входит в пакет generators. Этот пакет входит в состав сертифицированной версии Платформы «Waves Enterprise» и поставляется вместе с ней.

Important

Исключена возможность генерации ключевых пар по удаленному подключению к ноде.

Note

При использовании ГОСТ криптографии генерация аккаунта ноды возможна только при наличии графического интерфейса в операционной системе и предварительно установленных компонент СКЗИ «КриптоПро CSP».

Ключ ЭП и закрытые ключи TLS ноды ?????????ссылка на стр ТЛС для PKI????????? записываются в хранилище ключей СКЗИ «КриптоПро CSP», которое размещается на жестком диске ноды. Хранилище ключей (keystore) в этом случае расположено в директории, которая по умолчанию находится в директории /var/opt/cprocsp/keys/root/{username} в UNIX-подобных системах (Linux, OSX), где username — имя пользователя, под которым запускался генератор.

Для создания ключей электронной подписи и соответствующих им ключей проверки электронной подписи используется алгоритм JCP.GOST_EL_2012_256_NAME.

Чтобы создать аккаунт узла, запустите утилиту GeneratePkiKeypair.

The utility performs the following actions:

  • отображает в командной строке адрес и публичный ключ узла;

  • записывает приватный ключ узла в контейнер в хранилище ключей;

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

  • при работе на ОС CentOS отобразится диалоговое окно, в котором необходимо задать пароль к контейнеру;

  • при работе на ОС Linux пароль запрашивается через консоль;

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

  • выгружает запрос на сертификат в указанную директорию; запрос на сертификат содержит ранее сгенерированный публичный ключ и информацию, полученную из конфигурационного файла; в дальнейшем этот запрос необходимо самостоятельно отправить в удостоверяющий центр (УЦ) для получения сертификата;

  • выводит лог, в конце которого отображается имя контейнера, в котором хранится приватный ключ, и алиас (адрес) публичного ключа.

После того как вы отправили в УЦ запрос и получили из УЦ сертификат, его необходимо вручную импортировать в контейнер с ключевой парой в хранилище ключей, как описано ниже в разделе «Импорт сертификата».

Note

Утилита GeneratePkiKeypair также используется для создания ключей для TLS. За один запуск генератор создаёт одну ключевую пару.

Authenticating Center

Для подтверждения подлинности ключей шифрования Платформа использует сертификаты, выданные удостоверяющим центром (центром сертификации, УЦ). Для работы с УЦ необходимо выполнить следующие шаги:

  1. Выберите УЦ, с которым будете работать.

  2. Скачайте корневой сертификат УЦ с сайта УЦ.

  3. Поместите корневой сертификат УЦ в хранилище сертификатов в директории ноды: /node/certificates.

  4. Помимо этого, для создания genesis-блока необходимо добавить корневой сертификат в хранилище доверенных сертификатов JVM как описано ниже в разделе «Подготовка к запуску генератора GenesisBlockGenerator».

После этого узел будет считать достоверными сертификаты, подписанные этим УЦ.

GeneratePkiKeypair

Используйте утилиту GeneratePkiKeypair для создания ключевой пары узла и подписанного этой ключевой парой запроса на сертификат (CSR – Certificate Signing Request) стандарта X.509.

Для генерации ключевой пары утилита использует средства КриптоПро (КриптоПро CSP, включая КриптоПро JCSP).

Созданная ключевая пара сохраняется в хранилище ключей (keystore): приватный ключ записывается сразу после генерации, публичный – вместе с полученным от УЦ сертификатом.

The GeneratePkiKeypair utility uses the configuration file it receives for input to fill in the fields in the generated certificate request.

Note

Утилита GeneratePkiKeypair также используется для создания ключей для TLS. За один запуск генератор создаёт одну ключевую пару.

GeneratePkiKeypair configuration file

До запуска генератора необходимо подготовить конфигурационный файл в формате HOCON pki-keypair-generator.conf с данными для запроса на сертификат. Ниже приведён пример этого файла:

pki-key-pair-generator {
    crypto-type = gost
    chain-id = T
    key-pair-algorithm = "GOST_EL_2012_256" # or GOST_DH_2012_256
    keystore-password = "avada-kedavra"
    out-dir = "/Users/dummy/cert_requests" # optional: execution dir if not set
    cert-request-content {
        CN = "Node-0"
        O = "Waves Enterprise"
        OU = "IT Business"
        C = "RU"
        S = "Moscow"
        L = "Moscow"
        extensions {
            key-usage = ["digitalSignature"]
            extended-key-usage = ["clientAuth"] # or ["serverAuth"]
            subject-alternative-name = "DNS:welocal.dev,DNS:localhost,IP:51.210.211.61,IP:127.0.0.1"
        }
    }
}

Fill in the fields of the configuration file:

  • crypto-type — cryptography type; only the gost value is supported;

  • chain-id — идентифицирующий байт сети; допустимо передать только один символ без кавычек либо в двойных кавычках: латинскую букву (строчную или прописную), либо цифру; значение должно совпадать с параметром blockchain.custom.address-scheme-character из конфигурационного файла узла;

  • key-pair-algorithm — алгоритм генерации ключевой пары; допустимые значения:

    • GOST_EL_2012_256 — для ключей ЭП (ключей узла); в этом случае в поле extensions.key-usage должно быть указано значение digitalSignature;

    • GOST_DH_2012_256 — для ключевых пар, которые участвуют в процессе шифрования данных (ключи для TLS); в этом случае в поле extensions.key-usage должно быть указано значение keyEncipherment или dataEncipherment;

  • keystore-password — пароль хранилища ключей (keystore); этот же пароль потребуется в дальнейшем:

    • он должен быть указан в конфигурационном файле узла в разделе wallet в параметре password;

    • при использовании PKI этот же пароль используется при подписании genesis-, когда в консоли выводится запрос ввода пароля хранилища ключей (сообщение «enter keystore password»);

  • out-dir — the path to save the certificate request; optional field; if no value is specified, the request is saved to the directory from which the generator was started;

  • cert-request-content — fields with information for creating a certificate request:

    • CN — common name;

    • O — organization;

    • OU — organizational unit;

    • C — country;

    • S — state or province;

    • L — locality name;

    • extensions

      • key-usage — допускаются следующие значения, указывающие на назначение ключа:

        • digitalSignature — укажите это значение для ключей ЭП (ключей узла); в этом случае используется алгоритм шифрования GOST_EL_2012_256,

        • keyEncipherment — укажите это значение при генерации ключей для TLS; в этом случае используется алгоритм шифрования GOST_DH_2012_256,

        • dataEncipherment — укажите это значение при генерации ключей для TLS; в этом случае используется алгоритм шифрования GOST_DH_2012_256.

      • extended-key-usage — массив дополнительных значений типа enum, указывающих на назначение ключа; опциональное поле; допустимые значения:

        • ServerAuth,

        • ClientAuth,

        • CodeSigning,

        • EmailProtection,

        • TimeStamping,

        • OCSPSigning.

      Кроме этих значений допустимы значения в формате строки из чисел, разделённых точками, например: “1.2.3.4”.

      • subject-alternative-name — alternate subject name, mainly used for TLS for hostname matching; optional field.

Running the GeneratePkiKeypair

Скопируйте в директорию узла файл generators.jar. После этого утилиту GeneratePkiKeypair можно запустить из командной строки. В качестве аргумента утилите необходимо передать один параметр: путь до файла с конфигурацией:

java -cp "generators-1.9.0-M1-38-d823c7f.jar:gostCrypto-5.0.42119-A/*" com.wavesenterprise.generator.pki.PkiKeyPairGenerator pki-keypair-generator.conf

В процессе работы генератор запрашивает пароль ключевой пары; пример сообщения: “Enter key entry ‘3MrfnwhPPmvJp5B4hiwUwqtSJBJGs9DuxWe’ new password:”. Введите и подтвердите пароль. Этот же пароль потребуется в дальнейшем:

  • при использовании PKI – при подписании genesis-блока, когда в консоли выводится запрос ввода пароля ключевой пары (сообщение «enter keypair password»);

  • в файле env в поле WE_NODE_OWNER_PASSWORD ноды необходимо указать этот же пароль:

    WE_NODE_OWNER_PASSWORD=console # пароль из enter keypair password
WE_NODE_OWNER_PASSWORD_EMPTY=false

В процессе работы утилита выводит сообщения об успешности создания ключевой пары и запроса на сертификат, например:

2022-03-28 11:37:56,369 INFO [ioapp-compute-0] c.w.g.p.PkiKeyPairGenerator$ - Key pair successfully saved
2022-03-28 11:37:56,370 INFO [ioapp-compute-0] c.w.g.p.PkiKeyPairGenerator$ - Generating certificate request
2022-03-28 11:37:56,375 INFO [ioapp-compute-0] c.w.g.p.PkiKeyPairGenerator$ - Certificate request generated
2022-03-28 11:37:56,380 INFO [ioapp-compute-0] c.w.g.p.PkiKeyPairGenerator$ - Certificate request successfully exported to
 '/Users/username/Documents/VSCodeProjects/waves-enterprise/generator/jars/requests/3NAjk7wnh6VfE6esY9s94FGE1Z5QFDvPB3S.req'
2022-03-28 11:37:56,383 INFO [ioapp-compute-0] c.w.g.p.PkiKeyPairGenerator$ - Generated keypair:
Public key: 5GZrzce48Jv48Lq8Hn8PTqFDA1Yg2wWkAww1VXSonATfSub4mwo3YPymvqjkKYszxj4f794GqySz4deAZayroNnA
Alias (address for chain-id 'T'): 3NAjk7wnh6VfE6esY9s94FGE1Z5QFDvPB3S

GeneratePkiKeypair result

В результате работы генератор GeneratePkiKeypair

  • выводит в командной строке

  • The node blockchain address (alias),

  • публичный ключ узла в кодировке Base58,

  • имя контейнера (в конце лога генератора); оно потребуется для дальнейшей настройки.

  • записывает приватный ключ узла в контейнер в хранилище ключей; адрес хранилища ключей задаётся в конфигурационном файле узла в разделе wallet в параметре file;

  • выгружает запрос на сертификат (CSR) в указанную в конфигурационном файле pki-keypair-generator.conf директорию; запрос на сертификат содержит ранее сгенерированный публичный ключ и информацию, полученную из конфигурационного файла.

Obtaining and importing a certificate

Далее необходимо получить в удостоверяющем центре (УЦ) сертификат и импортировать его в контейнер с соответствующей парой ключей. Для этого выполните следующие шаги:

  1. Конвертируйте запрос на сертификат, полученный в результате работы генератора, в формат base64. Ниже приведён пример команды конвертации:

base64 ./jars/requests/3N5YTeLzpH18qrGRTVdL11DPkRPnM32aNVH.req

  1. Отправьте запрос в формате base64 в УЦ и скачайте из УЦ сертификат.

  2. Конвертируйте этот сертификат в формат base64.

  3. Импортируйте сертификат в контейнер с соответствующей парой ключей в хранилище ключей. Для GOST_EL_2012_256 используйте команду -keytype signature, для GOST_DH_2012_256 – команду -keytype exchange. Ниже приведён пример команды импорта:

/opt/cprocsp/bin/csptest -keyset -container 3MuuyL9pCsGeQNBnX14NuzRwGxSK3uzQW86 -keytype signature -impcert 3MuuyL9pCsGeQNBnX14NuzRwGxSK3uzQW86.cer

In this example:

  • 3MuuyL9pCsGeQNBnX14NuzRwGxSK3uzQW86 – имя контейнера, которое указано в конце лога генератора,

  • 3MuuyL9pCsGeQNBnX14NuzRwGxSK3uzQW86.cer – полученный из УЦ файл сертификата.

  1. Помимо этого, необходимо добавить сертификат в секцию node.blockchain.custom.genesis.pki конфигурационного файла узла для создания genesis-блока как описано ниже в разделе «Подготовка к запуску генератора GenesisBlockGenerator».

Настройка платформы для работы в частной сети при использовании ГОСТ криптографии с PKI

Для конфигурации платформы для работы в частной сети при использовании ГОСТ криптографии с PKI необходимо выполнить те же шаги общей и тонкой настройки, что и при использовании Waves криптографии или ГОСТ криптографии без PKI.

Obtaining a private network license and associated files

To deploy the platform on a private network, you need to get the kind of license that suits your purposes: trial, commercial or non-commercial.

Note

The opensource version of the Waves Enterprise blockchain platform does not require a license.

The license to run a node is tied to the node owner’s key. The license contains the address of the node for which the license is issued.

To discuss the details of your license, contact Waves Enterprise Sales at sales@wavesenterprise.com.

After that, you will be sent the license file. Place the file into the folder whose path is specified in the license-file parameter of the node configuration file.

Before deployment, familiarize yourself with the blockchain platform system requirements.

Genesis block signing and starting the network

After configuring your network’s nodes, you must create a genesis block, the first private blockchain block which contains the transactions that determine a node’s initial balance and permissions.

A genesis block is signed by the GenesisBlockGenerator utility included in the generators package. It uses the node.conf node configuration file that you set up as an argument:

java -jar generators-x.x.x.jar GenesisBlockGenerator node.conf

As a result, the utility fills the genesis-public-key-base-58 and signature fields located in the genesis block of the blockchain section in the node configuration file with the generated values of the public key and signature of the genesis block.

Example:

genesis-public-key-base-58: "4ozcAj...penxrm"
signature: "5QNVGF...7Bj4Pc"

Note

When using GOST PKI cryptography, it is necessary that the CryptoPro components be installed before signing the genesis block. Also, before starting the GenesisBlockGenerator you should prepare the node configuration file:

  • set the node.crypto.type parameter to gost;

  • set the node.crypto.pki.mode parameter to one of the following values: on or test;

  • add the public key that will be used to sign the genesis block to the network-participants section and give it the permissioner role there; the public key that will be used to sign the genesis block is also created by the GeneratePkiKeypair generator. The key must be located in the key store on the PC from which the generator is launched.

  • add the identifiers of the root trusted certificates to the configuration file; SHA-1 of certificate fingerprints are used as identifiers; list the network members certificates in DER format encoded to text using Base64; to do this, set the following parameters in the node.blockchain.custom.genesis.pki section:

    • trusted-root-fingerprints – an array of Base64 strings listing SHA-1 of trusted root certificates fingerprints which should be in the JVM trust-store,

    • certificates – an array of Base64 strings containing DER (binary) encoded certificate bodies.

It is also necessary to configure the GenesisBlockGenerator startup environment:

  • add the root certificates, which will be used as trusted certificates for blockchain validation, to the JVM trust-store. For this purpose you can use for instance the keystore utility built into the JVM. Here is an example of the utility call:

keytool -import -trustcacerts -alias %CERT_ALIAS% -noprompt -storepass 'changeit' -keystore %PATH_TO_YOUR_JRE%/lib/security/cacerts -file cert-to-add.cer

Then run the GenesisBlockGenerator on the command line, specifying the path to the node configuration file you want to sign, and the alias (address) of the key that will be used to sign the genesis block. For example:

java -cp "generators-x.x.x.jar::./java-csp-5.0.R2/*" com.wavesenterprise.generator.GeneratorLauncher GenesisBlockGenerator ./node_alone.conf 3N1uZiamcpuTnRASi7L17vM8xhbC292UNgU

After signing the genesis block, the platform is fully configured and ready to run the network. You can launch it according to the instructions received from Waves Enterprise specialists.

See also