Adam the automator

Подготовка конфигурационных файлов

Необходимо создать конфигурационный файл для OpenSSL. Создадим файл , скопируем в него следующее содержимое root-config.txt.
Раздел является обязательным. Здесь мы говорим OpenSSL использовать параметры из раздела :

Раздел содержит ряд значений по умолчанию:

Policy_strict будет применяться для всех подписей корневого центра сертификации, и корневой центр сертификации будет использоваться только для создания промежуточных центров сертификации.

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

Параметры из секции применяются когда создаются сертификаты или запросы на подписывание сертификатов.

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

Следующие несколько секций являются расширениями, которые могут применять при подписывании сертификатов. Например, при указании аргумента командной строки -extensions v3_ca будут применены расширения из секции . Эти расширения будут применяться при создании корневого сертификата.

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

Расширение будет применяться при подписывании клиентских сертификатов, таких, которые используются для аутентификации удаленных пользователей.

Расширение будет применяться при подписывании серверных сертификатов, таких, которые используются для веб-серверов.

Расширение будет автоматически применяться при создании списков отзыва сертификатов (CRL — certificate revocation lists).

Расширение будет применяться при подписывании сертификата OCSP (Online Certificate Status Protocol, онлайн протокол статуса сертификатов).

Troubleshooting & Debugging

Now that you can create & convert CSR’s, certificates, and key pairs, it’s time to learn how to troubleshoot and debug them. OpenSSL comes with commands that make it a breeze to troubleshoot problems.

OpenSSL also allows you to check certificates for file integrity and test for possible data corruption. Using an MD5 checksum, you can use the following code examples to test certificates, keys and CSR’s:

Once you have the original hash, you can then compare that original hash with a current hash to verify the certificate hasn’t been modified or corrupted.

Here’s a sample of what that code looks like when run in PowerShell:

Sample troubleshooting command output with OpenSSL in PowerShell

Installing OpenSSL

If your application , you need to have the necessary library files in your file system before deploying your application.

Platform	Download Required	File Names	Static/Dynamic Linking
	Yes	libeay32.dll and ssleay32.dll	Dynamic
	No	libcrypto.dylib, libssl.dylib	Dynamic
	Yes	libcrypto.a and libssl.a	Static
	No	libcrypto.dylib, libssl.dylib	Dynamic
	No		Dynamic

Review the requirements below depending on the platform that you are using:

32-bit and 64-bit Windows

To install OpenSSL in a 32-bit or 64-bit Windows, you need to copy the libeay32.dll and ssleay32.dll dynamic library files to your file system, you can download them from one of these locations:

• Option 1 — Download the OpenSSL installer files and install them.
• Option 2 — Download the OpenSSL compressed library files and copy the libeay32.dll and ssleay32.dll files to your system path.

If you go for Option 2 and decide to copy libeay32.dll and ssleay32.dll files to your system path, ensure you copy them to the right location:

• 32-bit Windows: You must copy the libeay32.dll and ssleay32.dll 32-bit files to your Windows system folder (System32 folder).
• 64-bit Windows: You must copy the libeay32.dll and ssleay32.dll 64-bit files to your Windows system folder for 64-bit files (System32) and the libeay32.dll and ssleay32.dll 32-bit files to your Windows 32-bit files folder (SysWOW64 folder).

So when working with a 64-bit Windows, remember:

• System32 folder is for 64-bit files only.
• SysWOW64 folder is for 32-bit files only.

32-bit and 64-bit iOS Device

To install OpenSSL in a 32-bit or 64-bit iOS device, you must copy the libcrypto.a and libssl.a SSL library files to your system. Download the .zip iOS OpenSSL, extract it and find the .a files in the directory. You must copy the libcrypto.a and libssl.a SSL library files to these directories:

iOS Simulator, macOS and Android

No additional steps are required in iOS Simulator and macOS since the required files are already in your file system.

For Android versions up to 6, you need to include the OpenSSL Libraries since Android moved away from OpenSSL to BoringSSL.

Note: RAD Studio Sydney only supports up to Android 6 versions.

Tip: Android no longer uses OpenSSL since version 6, ensure to bundle all your non-NDK libraries with your APK.

Update PowerShell Profile Environment Variables

To make things go smoothly, you should modify your PowerShell profile on Windows 10. Setting up some environment variables allows you to easily switch between different versions of OpenSSL that you may have installed.

I suggest adding two environment variables to your PowerShell profile called and . You will update the environment variable to ensure you can run the openssl binary in any location while on the command line.

Below you’ll see a way to create a PowerShell profile if you don’t already have one. This command appends the OpenSSL binary path to your and assign the configuration file path to .

To use the environment variables, reload your profile typing or just close and reopen PowerShell.

Now you can easily invoke the openssl binary wherever you are in PowerShell as shown below.

Verifying OpenSSL version in PowerShell

Сертификат доменного имени

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

1. Создайте файл расширения x509 v3:

cat > v3.ext <<-EOFauthorityKeyIdentifier=keyid,issuerbasicConstraints=CA:FALSEkeyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEnciphermentsubjectAltName = @alt_names # Локальные хостингиDNS.1 = localhostDNS.2 = 127.0.0.1DNS.3 = ::1 # Перечислите доменные именаDNS.4 = local.devDNS.5 = my-app.devDNS.6 = local.some-app.devEOF

Следуя этому шаблону, можно добавить сколько угодно доменных имен.

Примечание: пожалуйста, обновите DNS.4, DNS.5 и DNS.6 или удалите их, если у вас не настроены никакие локальные доменные имена.

2. Создайте закрытый ключ и запрос на подпись сертификата:

openssl req -new -nodes -newkey rsa:4096 \  -keyout localhost.key -out localhost.csr \  -subj "/C=US/ST=State/L=City/O=Some-Organization-Name/CN=localhost"

Опционально: страну, штат, город и организацию можно изменять.

3. Создайте самоподписанный сертификат:

openssl x509 -req -sha512 -days 365 \-extfile v3.ext \-CA ca.crt -CAkey ca.key -CAcreateserial \-in localhost.csr \-out localhost.crt

Использование сертификата

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

Вот несколько примеров:

Use OpenSSL on a Windows machine

By default, OpenSSL for Windows is installed in the following directory:

• if you have installed Win64 OpenSSL v1.X.X: C:\Program Files\OpenSSL-Win64\
• if you have installed Win32 OpenSSL v1.X.X: C:\Program Files (x86)\OpenSSL-Win32\

To launch OpenSSL, open a command prompt with administrator rights.

b)Generate the private key (.key) and the CSR (Certificate Signing Request)

As part of obtaining (or renewing or reissue) a certificate, you will have to generate a private key and
the associated CSR. To do this we advise you to use our online wizard
to execute the OpenSSL command with the adequate parameters.

Open a command prompt with Administrators rights (right click — Run as …). Go to the «bin» subdirectory
from the OpenSSL installation folder.

openssl req -new -newkey rsa:2048 -nodes -out www.mywebsite.com.csr -keyout www.mywebsite.com.key -subj "/C=FR/ST=Calvados/L=CAEN/O=Mon organisation/CN=www.mywebsite.com"

Save and keep safe the file containing the private key (.key, and copy / paste only the contents of the file .csr
file in the order form.

Центры сертификации: как они используются

Задача центра сертификации — подтверждать подлинность ключей шифрования с помощью сертификатов электронной подписи. Логику работы ЦС, как правило, можно описать тезисом «никто не доверяет друг другу, но все доверяют ЦС».

Допустим, условная сущность Аlice имеет сертификат, подписанный ЦС Comp, а сущность Bob пытается проверить подлинность этого сертификата. Проверка будет успешной, если Bob и Alice доверяют одному и тому же ЦС. Для решения такой проблемы в ОС Alice и ОС Bob установлено множество сертификатов различных ЦС.

Установив сертификат ЦС в систему, можно доверять тем сертификатам, которые он подписал. Если сертификат (в частности для HTTPS) выдан, но не подписан каким-нибудь доверенным ЦС, то его называют самоподписанным и он считается недоверенным — если, конечно, не заставить систему доверять такому сертификату.

Здесь могут возникать разные ошибки. Протестировать реакцию браузера на нарушения в работе SSL можно на сайте badssl.com.

Рассмотрим, как браузер реагирует на разные сертификаты. У Firefox, например, для идентификации есть такой набор сертификатов ЦС:

Вот пример с HTTPS. Есть ресурс www.geekbrains.ru, соединение с которым браузер считает доверенным:

Если открыть подробности, то можно увидеть почему:

Браузер считает подключение доверенным потому, что сертификат HTTPS подписан ЦС Comodo CA. Эта организация своим сертификатом подтверждает, что сертификату, выданному для сайта GeekBrains, можно доверять. Получается примерно такая схема:

• браузер доверяет организации Comodo CA;
• браузер открывает сайт GeekBrains и видит там сертификат HTTPS, подписанный Comodo CA;
• браузер считает, что если организация, которой он доверяет, уверена в сайте GeekBrains (они же подтвердили их сертификат), то такое соединение для конечного пользователя можно считать доверенным.

Если коротко, то для успешной проверки доверия (в рамках HTTPS) с использованием центра сертификации необходимо, чтобы:

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

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

Если открыть дополнительные сведения (что я всегда советую делать), то можно подробнее узнать о проблеме. Здесь видно, что на сайте установлен самоподписанный сертификат, то есть не подписанный каким-либо другим сертификатам. Его подлинность нельзя проверить, и соединение считается недоверенным.

Другой пример — сайт wrong.host.badssl.com. Сертификат выдан для другого хоста, о чём и уведомляет браузер:

А вот пример для сайта, у которого истёк срок действия сертификата:

Autoconf[edit]

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either OPENSSL_init_ssl or SSL_library_init from libssl. To craft a feature test for OpenSSL that recognizes both OPENSSL_init_ssl and SSL_library_init, you can use the following.

if test "$with_openssl" = yes ; then
  dnl Order matters!
  if test "$PORTNAME" != "win32"; then
     AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], )])
     FOUND_SSL_LIB="no"
     AC_CHECK_LIB(ssl, OPENSSL_init_ssl, )
     AC_CHECK_LIB(ssl, SSL_library_init, )
     AS_IF(, )])
  else
     AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], )])
     FOUND_SSL_LIB="no"
     AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, )
     AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, )
     AS_IF(, )])
  fi
fi

Отзыв сертификата

Утилита OpenSSL ocsp может выступать в качестве ответчика OCSP, но она предназначена только для тестирования. Для производственной среды OCSP ответчики тоже существуют, но они выходят за рамки данной статьи.

Создадим серверный сертификат для тестирования.

Запустим ответчик OCSP на локальной машине. Вместо того, чтобы хранить статус отзыва в отдельном CRL файле ответчик OCSP напрямую читает файл index.txt. Ответ подписывается криптографической парой OCSP (используя опции –rkey и –rsigner).

В другом терминале пошлем запрос к OCSP ответчику. Опция указывает сертификат для запроса.

Начало вывода показывает следующее:

• был ли получен положительный ответ (OCSP Response Status)
• идентичность ответчика (Responder Id)
• статус отзыва сертификата (Cert Status)

Отзыв сертификата.

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

Converting Certificates with OpenSSL

There are occasions where an application does not use a particular certificate format. You can run into this issue with an application called HAproxy, for example that requires a PEM certificate when you may have a DER-formatted certificate (.crt .cer .der).

To demonstrate converting a certificate, let’s convert the self-signed certificate created earlier in a DER format (certificate.crt) to PEM. Use the code in the following code snippet to do so.

This command below uses the sub-command with the parameter of which should match the format of the file followed by the format.

You can also reverse the order if you’d like to the DER format from PEM too as shown below.

And last but not least, you can convert PKCS#12 to PEM and PEM to PKCS#12. This is a file type that contain private keys and certificates. To convert to PEM format, use the sub-command.

You can convert a PEM certificate and private key to PKCS#12 format as well using with a few additional options. Below you are exporting a PKCS#12 formatted certificate using your private key by using as the input source. Using the option value allows you to validate .

Разворачиваем собственный ЦС

Чтобы лучше понять все процессы, лежащие в основе PKI, рассмотрим на практике развёртывание небольшого ЦС на виртуальной машине под управлением Ubuntu 18 (без выхода в глобальную сеть). Мы не будем жёстко придерживаться правил и стандартов выдачи сертификатов — просто разберём работу с ними.

С учетом того, что. все эксперименты мы проводим в виртуальной среде (без выхода в глобальную сеть), мы можем использовать любое доменное имя — например www.simple.org. Однако надо помнить, что в глобальной сети такое имя вполне может быть зарегистрировано за каким-нибудь сайтом.

Допустим, нам надо настроить веб-сервер так, чтобы соединение к нему шло по протоколу HTTPS и сервер заодно проверял клиента по сертификату. Пользователь у нас один, веб-сервер на Apache 2. Схема нашего центра сертификации будет такой:

Начальные настройки

Сперва заполним файл /root/.rnd, который используется как источник начальных случайных значений в генераторе псевдослучайных чисел OpenSSL. Суть использования этого файла описана на сайте OpenSSL. Нам надо заполнить свой файл случайными данными, как вариант — скопировав из /dev/urandom 32768 байт в файл .rnd таким образом: 

Далее создадим сертификат для CA:

root@shpc:/opt/simple_CA# openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

Опции для сертификата берутся из файла /etc/ssl/openssl.cnf. Сам файл довольно большой, мы не будем приводить здесь его содержимое. В реальности стоит создать свой конфигурационный файл с необходимыми опциями и блоками — и использовать его для генерации сертификатов.

На выходе получим два файла: ключ и сертификат. 

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

root@shpc:/opt/simple_CA# openssl x509 -text -noout -in ca.cer

Далее на основе полученного сертификата (напомним, что это сертификат корневого CA) можно сгенерировать сертификат для сервера. Вначале генерируем закрытый ключ для сервера:

root@shpc:/opt/simple_CA# openssl genrsa -out server.key 4096

Теперь используем этот ключ для генерации запроса на выдачу сертификата (CSR):

root@shpc:/opt/simple_CA# openssl req -new -key server.key -out server.req -sha256

Отметим, что данные, которые вы вводите в поля, должны совпадать со значениями в тех полях, что указывались при создании сертификата корневого сервера. Теперь возьмём корневой сертификат CA и запрос — и сгенерируем на их основе сертификат для сервера:

root@shpc:/opt/simple_CA# openssl x509 -req -in server.req -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 1460 -outform PEM -out server.cer -sha256 

Должно получиться 5 файлов.

Файл server.req можно удалить — а при необходимости создать заново. Теперь надо перенастроить веб-сервер для работы с сертификатами.

Поддержка ГОСТ-сертификатов в nginx

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

1. Легко поднимать свой веб-сервер с ГОСТ-сертификатом по HTTPS (TLS).
2. Легко проксировать все запросы на хост с ГОСТ-сертификатом

Легко – это означает докер-образ. Его нужно создать. Для этого нужно в Dockerfile собрать nginx с кастомным OpenSSL и GOST-engine. Открыв документацию сборки nginx, я увидел одну опцию о ssl — , которая просто булева. Но nginx популярный продукт, инструкций по сборке с openssl много, поэтому я нашел еще опцию . Как показала практика, nginx хочет, чтобы здесь были исходники openssl, а сборкой скрипты nginx займутся сами. Это не совсем то, что я хотел бы (я хотел использовать multi-stage build). Я ознакомился с help-выводом сборщика nginx, но ничего, что мне там помогло бы, я не нашел.

Пришлось дублировать инструкции выкачивания исходников OpenSSL, распаковки, сборки GOST-engine, включения GOST-engine в конфиги. Всё это начало собираться, но поддержки ГОСТ-алгоритмов в nginx все ещё не было. Это я проверял указанием в конфиге . Выполнение говорило, что не знает этого алгоритма.

Как оказалось, openssl, собранный nginx, не поддерживал динамические движки, т.е. выводил . Здесь пришлось внимательно почитать документацию сборки OpenSSL, чтобы выяснить, что проставило . Причина нашлась в openssl, которые вызывал nginx, а именно . Если это указано, то нет никаких флагов, чтобы включить поддержку загрузки движков. Пришлось править инструкцию сборки:

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

Рядом с основным Dockerfile в репозитории я положил демонстрационный Dockerfile, который при сборке создает себе ГОСТ-сертификаты и использует их, обрабатывая соединения на https://gost.example.com. Придется поработать с DNS или docker network, чтобы из одного контейнера попробовать подключится к этому демонстрационному, но все это я описал в документации.
Демонстрационный хост использует ключи по , другие варианты это , . А вместо — .
Образ с nginx + GOST запушен в Docker Hub: https://hub.docker.com/r/rnix/nginx-gost/

Configuring OpenSSL

By default, OpenSSL on Windows 10 does not come with a configuration file. This is intentional because there are a lot of configuration options that you can customize. For the purposes of this guide, you are going to use a sample configuration that you can customize later to best suit your security requirements.

Open up PowerShell and run the below command. This command downloads a sample configuration file from MIT and saves it as openssl.cnf in the current working directory.

You can now open up the openssl.cnf file and you should see something that looks like below.

Sample OpenSSL configuration file

The downloaded configuration will work as-is for now. Do not use the defaults in a production environment!

Special notes for Universal Windows Platform builds, aka VC-*-UWP

• UWP targets only support building the static and dynamic libraries.

• You should define the platform type to «uwp» and the target arch via
  «vcvarsall.bat» before you compile. For example, if you want to build
  «arm64» builds, you should run «vcvarsall.bat x86_arm64 uwp».

Native builds using Embarcadero C++Builder

1. Install Perl.

2. Open the RAD Studio Command Prompt.

3. Go to the root of the OpenSSL source directory and run:
   perl Configure BC-32 —prefix=%CD%

4. make -N

5. make -N test

6. Build your program against this OpenSSL:

   • Set your include search path to the «include» subdirectory of OpenSSL.
   • Set your library search path to the OpenSSL source directory.

Note that this is very experimental. Support for 64-bit and other Configure
options is still pending.

Native builds using MinGW

MinGW offers an alternative way to build native OpenSSL, by cross compilation.

• Usually the build is done on Windows in a GNU-like environment called MSYS2.

  MSYS2 provides GNU tools, a Unix-like command prompt,
  and a UNIX compatibility layer for applications.
  However, in this context it is only used for building OpenSSL.
  The resulting OpenSSL does not rely on MSYS2 to run and is fully native.

  Requirement details

  • Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2

  • make, installed using «pacman -S make» into the MSYS2 environment

  • MinGW compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc.
    These compilers must be on your MSYS2 $PATH.
    A common error is to not have these on your $PATH.
    The MSYS2 version of gcc will not work correctly here.

  In the MSYS2 shell do the configuration depending on the target architecture:

  or
  ./Configure mingw64 …
  or
  ./Configure …

  for the default architecture.

  Apart from that, follow the Unix / Linux instructions in INSTALL.md.

• It is also possible to build mingw on Linux or Cygwin.

  In this case configure with the corresponding —cross-compile-prefix= option.
  For example

  or
  ./Configure mingw64 —cross-compile-prefix=x86_64-w64-mingw32- …

  This requires that you’ve installed the necessary add-on packages for
  mingw cross compilation.

Linking native applications

This section applies to all native builds.

If you link with static OpenSSL libraries then you’re expected to
additionally link your application with WS2_32.LIB, GDI32.LIB,
ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
non-interactive service applications might feel concerned about
linking with GDI32.LIB and USER32.LIB, as they are justly associated
with interactive desktop, which is not available to service
processes. The toolkit is designed to detect in which context it’s
currently executed, GUI, console app or service, and act accordingly,
namely whether or not to actually make GUI calls. Additionally those
who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
actually keep them off service process should consider implementing
and exporting from .exe image in question own _OPENSSL_isservice not
relying on USER32.DLL. E.g., on Windows Vista and later you could:

If you link with OpenSSL .DLLs, then you’re expected to include into
your application code a small «shim» snippet, which provides
the glue between the OpenSSL BIO layer and your compiler run-time.
See also the OPENSSL_Applink manual page.

Hosted builds using Cygwin

Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
Windows subsystem and provides a Bash shell and GNU tools environment.
Consequently, a build of OpenSSL with Cygwin is virtually identical to the
Unix procedure.

To build OpenSSL using Cygwin, you need to:

• Install Cygwin Perl, at least version 5.10.0
  and ensure it is in the $PATH

• Run the Cygwin Bash shell

Apart from that, follow the Unix / Linux instructions in INSTALL.md.

NOTE: «make test» and normal file operations may fail in directories
mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
stripping of carriage returns. To avoid this ensure that a binary
mount is used, e.g. mount -b c:\somewhere /home.

Заключение

Мной изучена проблема работы с ГОСТ-алгоритмами в системах Linux, предоставлено решение в виде docker-образов, все это сопровождено документацией и примерами. Решение оформлено в виде репозитория на GitHub.

Стоит сказать о безопасности использования такого решения. Главное, не стоит доверять образам на Docker Hub, даже если там написано . Я все равно могу собрать образ с любыми правками всех используемых библиотек и систем и запушить его в свой Docker Hub под любым тегом. Поэтому рекомендую форкать репозиторий на гитхабе, пулить его себе и уже самостоятельно собирать, проверив инструкции в Dockerfile на наличие того, что используются только официальные ресурсы без подозрительных модификацией по ходу сборки.

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