Интеграция .NET-приложения с внешним API по ГОСТ TLS через CryptoPro

Всем привет. Представлюсь — меня зовут Евгений Думчев и я Team Lead .NET разработки в DDPlanet.

В какой-то момент в моей практике появилась задача по интеграции с внешним API. Для взаимодействия требовалось применять предоставленный публичный доверенный сертификат сервера .cer и клиентский .pfx сертификат. Особенность в том, что .pfx сертификат был выпущен через CryptoPro CSP — а это вносит свои тонкости в процесс интеграции.

В этой статье я расскажу, как интегрировать .NET-приложение с внешним API, требующему двусторонней TLS-аутентификации по национальным криптографическим стандартам (ГОСТ) с использованием сертификатов, выпущенных через CryptoPro CSP.

Содержание

1. Безопасность и сферы применения двустороннего TLS с CryptoPro

2. Особенности взаимодействия с API, использующим сертификат CryptoPro

3. Решение для .NET приложений в Windows

4. Решение для .NET приложений в Linux

5. Решение с помощью NGINX

6. Как безопасно хранить сертификаты и пароли к ним

7. Заключение

Безопасность и сферы применения двустороннего TLS с CryptoPro

При работе с государственными или банковскими API в РФ часто предъявляются требования к применению национальных криптографических стандартов. В таких случаях сертификаты формируются через CryptoPro CSP и содержат ГОСТ-алгоритмы, которые отличают эти сертификаты от обычных X.509 сертификатов, применяемых в международной практике.

Более того, для повышения уровня безопасности при взаимодействии по API может применяться двусторонняя TLS-аутентификация (mTLS), которая обеспечивает повышенный уровень доверия между клиентом и сервером. Это означает, что:

1. Сервер предоставляет свой сертификат — клиент проверяет, доверять ли серверу.

2. Клиент предъявляет свой сертификат (client certificate) — сервер проверяет его подлинность.

Работает это по следующему принципу:

• При вызове внешнего API, клиент (в нашем случае .NET Web API приложение) выполняет запрос соединения с сервером.

• В процессе TLS-рукопожатия сервер отсылает клиенту свой публичный сертификат.

• Клиент проверяет валидность публичного сертификата, сравнивая его с заранее известным и доверенным сертификатом сервера (например, .cer файлом) или по цепочке доверия к корневому УЦ. Если сертификат соответствует ожидаемому, то можно доверять этому серверу.

• Так как на стороне сервера включена двусторонняя аутентификация — он отправляет запрос о необходимости предоставления клиентского сертификата.

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

• Сервер проверяет подпись и цепочку доверия, а также сверяет, выдан ли сертификат от доверенного УЦ.

• Если все проверки пройдены успешно — устанавливается защищенное соединение — API становится доступным и клиенту можно выполнять обработку запросов.

Сертификат .pfx (Personal Information Exchange) применяется из соображений безопасности. Это стандартизированный двоичный формат контейнера сертификатов PKCS #12 (Public-Key Cryptography Standards). Он представляет собой единый файл, который включает в себя закрытый ключ  (private key), открытый ключ / сертификат (public key) и цепочку доверия (промежуточные и корневые сертификаты). К особенностям можно отнести то, что содержимое .pfx-файла шифруется и защищается паролем.

Дополнительно .pfx-файл может быть экспортирован с включенной опцией «расширенной защиты», что позволяет повысить уровень безопасности хранения закрытого ключа внутри контейнера. Это достигается посредством применения более стойкого шифрования и добавления ограничения на экспорт — даже после импорта сертификата его нельзя будет снова выгрузить с приватным ключом.

Получаем следующую схему взаимодействия:

С таким уровнем безопасности с применением CryptoPro чаще всего можно столкнуться при взаимодействии с отечественным ПО в следующих сферах:

• Системы электронного документооборота (ЭДО).

• Порталы государственных услуг.

• Банковские и финансовые API.

• Торговые площадки, работающие с ЭЦП (электронной подписью).

• Юридически значимые интеграции — в которых важно соблюдение требований к квалифицированной электронной подписи (КЭП).

Особенности взаимодействия с API, использующим сертификат CryptoPro

При взаимодействии со сторонней API по REST в нашем случае должен использоваться .pfx сертификат, созданный через CryptoPro. Это означает, что алгоритмы и структуры сертификата могут содержать специфичные для ГОСТ и CryptoPro криптографические идентификаторы OID, например, 1.2.840.113549.1.12.1.80, которые не поддерживаются большинством стандартных библиотек (например, OpenSSL, curl). Что требует использования именно CryptoPro или его оберток для корректной работы.

У сторонней API предусмотрена Swagger-документация, но она так просто не доступна в браузере.

Во-первых, для доступа к API из браузера необходимо установить CryptoPro CSP. Этот инструмент позволяет установить на устройство клиентский сертификат .pfx.

Во-вторых, даже после установки сертификата Swagger-документация внешнего API становится доступна только в браузерах Chromium-Gost и Яндекс Браузер. Эти браузеры поддерживают отечественные криптографические алгоритмы ГОСТ, используемые в сертификатах, выпущенных через CryptoPro. И на этих браузерах должен быть установлен КриптоПро ЭЦП Browser Plugin.

Наконец, при открытии url /swagger в подходящем браузере появляется модальное окно CryptoPro CSP для выбора нужного сертификата, применяемого для доступа к ресурсу. И после выбора нужного сертификата — победа, Swagger-документация становится доступна и позволяет успешно отправлять REST запросы на сервер.

Но как же выполнять взаимодействие с API по REST из приложения на .NET? Ведь в случае классической реализации выполнения запросов через HttpClient получаем в ответе HTTP статус код 400 (Bad Request) с ошибкой:

<html> <head><title>400 No required SSL certificate was sent</title></head> <body> <center><h1>400 Bad Request</h1></center> <center>No required SSL certificate was sent</center> <hr><center>nginx</center> </body> </html>

Основным решением является подключение к запросам клиентского сертификата .pfx CryptoPro и публичного доверенного сертификата сервера .cer для организации двусторонней TLS-аутентификации.

Рассмотрим следующие варианты решения:

• для .NET приложения, запускаемом на Windows;

• для .NET приложения, запускаемом на Linux;

• с помощью NGINX.

Решение для .NET приложений в Windows

Самый простой способ подцепить сертификаты (клиентский .pfx и доверенный сертификат сервера .cer) из приложения на .NET под Windows заключается в том, чтобы добавить их в виде файлов в структуру проекта.

После чего эти файлы можно подгрузить по пути к ним и применить в REST запросах к целевой API.  Для этого необходимо сконфигурировать типизированный HttpClient и добавить к обработке HTTP запросов логику применения сертификатов в HttpClientHandler.

public static IServiceCollection ConfigureApiHttpClient(this IServiceCollection services) {     services.AddSingleton(serviceProvider =>     {         var options = serviceProvider.GetRequiredService<IOptions<ApiOptions>>().Value;         var env = serviceProvider.GetRequiredService<IWebHostEnvironment>();          // Формируем абсолютные пути к сертификатам         var publicCertPath = Path.Combine(env.ContentRootPath, "Certificates", options.CerCertificateName);         var privateCertPath = Path.Combine(env.ContentRootPath, "Certificates", options.PfxCertificateName);          return new ApiCertificates         {             //Загружаем серверный публичный сертификат (.cer)             PublicCert = new X509Certificate2(publicCertPath),             //Загружаем клиентский сертификат с приватным ключом (.pfx)             PrivateCert = new X509Certificate2(privateCertPath, options.PfxCertificatePassword)         };     });      services.AddHttpClient<IApiHttpClient, ApiHttpClient>()         .ConfigurePrimaryHttpMessageHandler((serviceProvider) =>         {             var apiCertificates = serviceProvider.GetRequiredService<ApiCertificates>();              var handler = new HttpClientHandler();              handler.ClientCertificateOptions = ClientCertificateOption.Manual;             //клиент будет отправлять свой сертификат при TLS-рукопожатии             handler.ClientCertificates.Add(apiCertificates.PrivateCert);              // Опционально: настройка проверки серверного сертификата             handler.ServerCertificateCustomValidationCallback = (_, cert, _, sslPolicyErrors) =>             {                 // Проверяем, совпадает ли сертификат с ожидаемым                 if (cert?.Thumbprint?.Equals(apiCertificates.PublicCert.Thumbprint, StringComparison.OrdinalIgnoreCase) == true)                     return true;                  // Если сертификат не совпадает, можно по желанию разрешить стандартную проверку TLS                 return sslPolicyErrors == SslPolicyErrors.None;             };              return handler;         });      return services; }

После запуска приложения и выполнения целевого запроса вызывается криптопровайдер CryptoPro CSP и появляется всплывающее окно запроса пароля. Такое поведение проявляется при использовании сертификатов с пометкой «требовать защищенную сессию». В этом случае CryptoPro всегда запрашивает ввод пароля или подтверждение доступа, даже если вы уже указали пароль при загрузке X509Certificate2.

После указания учетных данных запросы успешно доходят до целевого API.

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

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

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

Тогда получим следующий код:

private static X509Certificate2? FindCertInStore(string thumbprint, StoreName storeName, StoreLocation storeLocation) {     using var store = new X509Store(storeName, storeLocation);     store.Open(OpenFlags.ReadOnly);      return store.Certificates         .Find(X509FindType.FindByThumbprint, thumbprint, validOnly: false)         .FirstOrDefault(); }  public static IServiceCollection ConfigureApiHttpClient(this IServiceCollection services) {     services.AddSingleton(serviceProvider =>     {         var options = serviceProvider.GetRequiredService<IOptions<ApiOptions>>().Value;          return new ApiCertificates         {             //Загружаем серверный публичный сертификат (.cer)             PublicCert = FindCertInStore(options.CerCertificateThumbprint, StoreName.My, StoreLocation.CurrentUser)!,             //Загружаем клиентский сертификат с приватным ключом (.pfx)             PrivateCert = FindCertInStore(options.PfxCertificateThumbprint, StoreName.My, StoreLocation.CurrentUser)!         };     });      services.AddHttpClient<IApiHttpClient, ApiHttpClient>()         .ConfigurePrimaryHttpMessageHandler((serviceProvider) =>         {             var apiCertificates = serviceProvider.GetRequiredService<ApiCertificates>();              var handler = new HttpClientHandler();              handler.ClientCertificateOptions = ClientCertificateOption.Manual;             //клиент будет отправлять свой сертификат при TLS-рукопожатии             handler.ClientCertificates.Add(apiCertificates.PrivateCert);              // Опционально: настройка проверки серверного сертификата             handler.ServerCertificateCustomValidationCallback = (_, cert, _, sslPolicyErrors) =>             {                 // Проверяем, совпадает ли сертификат с ожидаемым                 if (cert?.Thumbprint?.Equals(apiCertificates.PublicCert.Thumbprint, StringComparison.OrdinalIgnoreCase) == true)                     return true;                  // Если сертификат не совпадает, можно по желанию разрешить стандартную проверку TLS                 return sslPolicyErrors == SslPolicyErrors.None;             };              return handler;         });      return services; }

В данном случае сертификат CryptoPro успешно достается из хранилища сертификатов Windows и применяется в запросах на сервер без всплывающего окна и запроса пароля. Это работает за счет того, что криптопровайдер CryptoPro интегрируется в инфраструктуру Windows как один из поддерживаемых провайдеров. Соответственно, сертификаты, установленные через CryptoPro, регистрируются в стандартных хранилищах Windows — например, в StoreName.My и StoreLocation.CurrentUser или LocalMachine и доступны через X509Store.

Решение для .NET приложений в Linux

Для запуска приложения в Linux соберем и запустим docker образ.

# этап сборки проекта FROM mcr.microsoft.com/dotnet/sdk:8.0 AS publish WORKDIR /src COPY . .  WORKDIR "/src/Cert.Client.Api"  RUN dotnet restore "Cert.Client.Api.csproj" --verbosity Minimal --use-current-runtime  RUN dotnet publish "Cert.Client.Api.csproj" --no-restore -c Release -o /app/publish /p:UseAppHost=false   # этап подготовки финального образа FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final  RUN sed -i '/\[openssl_init\]/a ssl_conf = ssl_sect' /etc/ssl/openssl.cnf RUN printf "\n[ssl_sect]\nsystem_default = system_default_sect\n" >> /etc/ssl/openssl.cnf RUN printf "\n[system_default_sect]\nMinProtocol = TLSv1.2\nCipherString = DEFAULT@SECLEVEL=0" >> /etc/ssl/openssl.cnf  USER $APP_UID WORKDIR /app EXPOSE 8080 EXPOSE 8081  ENV ASPNETCORE_ENVIRONMENT=Development  WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "Cert.Client.Api.dll"]

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

System.Security.Cryptography.CryptographicException: The certificate data cannot be read with the provided password, the password may be incorrect.   ---> System.Security.Cryptography.CryptographicException: The EncryptedPrivateKeyInfo structure was decoded but was not successfully interpreted, the password may be incorrect.   ---> System.Security.Cryptography.CryptographicException: The algorithm identified by '1.2.840.113549.1.12.1.80' is unknown, not valid for the requested usage, or was not handled.   at System.Security.Cryptography.X509Certificates.OpenSslX509CertificateReader.FromFile(String fileName, SafePasswordHandle password, X509KeyStorageFlags keyStorageFlags)

Ошибка возникает из-за того, что OpenSSL не может корректно прочитать сертификат, поскольку в нем используется алгоритм шифрования от CryptoPro, который не поддерживается в стандартной сборке OpenSSL. То есть в Linux такой сертификат не типизировать в X509Certificate2, как это работало для Windows «из коробки».

Установить сертификат на Linux с помощью команд OpenSSL не получится — формат PFX сертификатов не поддерживается в операционной системе Linux. Однако есть возможность конвертировать его в формат PEM с помощью OpenSSL:

# Конвертация .pfx в .pem openssl pkcs12 -in private-cert.pfx -out private-cert.pem -nodes

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

# Извлечь ключ openssl pkcs12 -in private-cert.pfx -nocerts -nodes -out private.key  # Извлечь сертификат openssl pkcs12 -in private-cert.pfx -clcerts -nokeys -out certificate.crt  # Извлечь CA-цепочку openssl pkcs12 -in private-cert.pfx -cacerts -nokeys -out ca-chain.crt

Все это не сработает для .pfx сертификата CryptoPro по причине неизвестного алгоритма шифрования.

Error outputting keys and certificates C8650000:error:03000079:digital envelope routines:EVP_PBE_CipherInit_ex:unknown pbe algorithm:crypto\evp\evp_pbe.c:116:TYPE=1.2.840.113549.1.12.1.80

Одним из вариантов решения является установка модифицированной версии OpenSSL, например, gost-engine. Но я бы не рекомендовал подобный вариант, так как сторонние реализации не гарантируют поддержку и безопасность, а также могут не поддерживать актуальные сертификаты или ключи.

Правильным вариантом решения является использование сертифицированного CryptoPro CSP для Linux. И установить его в docker-образ. Скачать необходимый дистрибутив можно по ссылке. В нашем случае используется образ mcr.microsoft.com/dotnet/aspnet:8.0, который базируется на debian образе, поэтому нужно установить дистрибутив linux-amd64_deb.tgz.

CryptoPro CSP является набором инструментов по работе с криптографией, предназначенных для реализации российских алгоритмов ГОСТ, создания и проверки электронной подписи, шифрования, управления сертификатами и контейнерами закрытых ключей. Часть полезных инструментов, содержащихся в сборке linux-amd64_deb.tgz:

• csptest — инструмент для тестирования функций CSP: проверка алгоритмов, ключей, сертификатов, подписей и шифрования.

• certmgt — утилита управления сертификатами: установка, удаление, экспорт и просмотр сертификатов из хранилищ CSP.

• cprodiag — диагностический инструмент для сбора информации о конфигурации CryptoPro CSP, лицензии, хранилищах и возможных ошибках.

• cpverify — проверка целостности и корректности установки CryptoPro CSP: сверка контрольных сумм и доступности компонентов.

• cryptcp — утилита для подписания, шифрования и проверки данных.

• cpconfig — утилита настройки компонентов CryptoPro CSP: используется для активации и просмотра лицензий, управления параметрами криптопровайдера и системными настройками.

• cpnginx — модифицированная версия NGINX с поддержкой ГОСТ TLS через интерфейс SSPI, встроенная в CryptoPro CSP.

Внесем изменения в Dockerfile — добавим команды по установке CryptoPro CSP. Для соблюдения правил использования необходимо указать лицензионный ключ. И с помощью инструментария CryptoPro CSP нужно установить сертификаты .pfx и .cer. Скорректированный Dockerfile:

# этап сборки проекта FROM mcr.microsoft.com/dotnet/sdk:8.0 AS publish WORKDIR /src COPY . .  WORKDIR "/src/Cert.Client.Api"  RUN dotnet restore "Cert.Client.Api.csproj" --verbosity Minimal --use-current-runtime  RUN dotnet publish "Cert.Client.Api.csproj" --no-restore -c Release -o /app/publish /p:UseAppHost=false   # этап подготовки финального образа FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final  # установка CryptoPro WORKDIR /cryptopro ADD Cert.Client.Api/CryptoPro/linux-amd64_deb.tgz . RUN ./linux-amd64_deb/install.sh  # добавление лицензионного ключа CryptoPro ARG CRYPTO_PRO_LICENSE RUN /opt/cprocsp/sbin/amd64/cpconfig -license -set ${CRYPTO_PRO_LICENSE}  # копирование сертификатов CryptoPro ADD Cert.Client.Api/Certificates ./certificates  # установка доверенного сертификата сервера .cer в CryptoPro RUN /opt/cprocsp/bin/amd64/certmgr -install -file ./certificates/public-cert.cer -silent  # установка клиентского сертификата .pfx в CryptoPro ARG PRIVATE_CERT_PASS RUN /opt/cprocsp/bin/amd64/certmgr -install -pfx -file ./certificates/private-cert.pfx -pin ${PRIVATE_CERT_PASS} -silent  # установка сертификатов из контейнеров в CryptoPro RUN /opt/cprocsp/bin/amd64/csptest -absorb -certs -autoprov  WORKDIR /app RUN rm -R /cryptopro   RUN sed -i '/\[openssl_init\]/a ssl_conf = ssl_sect' /etc/ssl/openssl.cnf RUN printf "\n[ssl_sect]\nsystem_default = system_default_sect\n" >> /etc/ssl/openssl.cnf RUN printf "\n[system_default_sect]\nMinProtocol = TLSv1.2\nCipherString = DEFAULT@SECLEVEL=0" >> /etc/ssl/openssl.cnf  USER $APP_UID WORKDIR /app EXPOSE 8080 EXPOSE 8081  ENV ASPNETCORE_ENVIRONMENT=Development  WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "Cert.Client.Api.dll"]

После выполнения команды установки сертификата .pfx его содержимое импортируется в систему CryptoPro и преобразуется — разбивается на отдельные компоненты, сохраненные в формате с расширением .key:

В основном хранилище ключей keys появляется наш преобразованный .pfx контейнер в формате cert.000 с шестью файлами:

• primary.key, primary2.key — основные ключи.

• name.key — содержит имя или идентификатор контейнера.

• masks.key, masks2.key — используется для маскировки/шифрования ключей.

• header.key — содержит метаинформацию (заголовок, версию и т. п.).

Поскольку в Linux .pfx сертификат CryptoPro не типизировать в X509Certificate2, то ни вариант с загрузкой сертификата напрямую из структуры проекта, ни вариант с получением из хранилища сертификатов X509Store не сработает — нам не удастся найти целевой .pfx сертификат и, соответственно, не получится выполнить TLS-рукопожатие. Получим следующую ошибку:

InvokeGetRequest Error. System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception.   ---> System.IO.IOException: Received an unexpected EOF or 0 bytes from the transport stream.   at System.Net.Security.SslStream.ReceiveHandshakeFrameAsync[TIOAdapter](CancellationToken cancellationToken)   at System.Net.Security.SslStream.ForceAuthenticationAsync[TIOAdapter](Boolean receiveFirst, Byte[] reAuthenticationData, CancellationToken cancellationToken)   at System.Net.Http.ConnectHelper.EstablishSslConnectionAsync(SslClientAuthenticationOptions sslOptions, HttpRequestMessage request, Boolean async, Stream stream, CancellationToken cancellationToken)

В Linux предусмотрена возможность получения сертификатов из специализированного хранилища сертификатов CryptoPro. Для этого необходимо воспользоваться официальным кроссплатформенным решением CryptoPro .NET, доступным по ссылке.

Решение включает в себя четыре NuGet-пакета, которые необходимо подключить к проекту. Это можно сделать одним из следующих способов:

• Локальное подключение пакетов.

• Загрузка пакетов в онлайн-репозиторий, например Nexus, Azure DevOps и другие.

В .csproj нужно добавить все эти пакеты:

<PackageReference Include="CryptoPro.Net.Security" Version="2025.4.17" /> <PackageReference Include="CryptoPro.Security.Cryptography" Version="2025.4.17" /> <PackageReference Include="CryptoPro.Security.Cryptography.Pkcs" Version="2025.4.17" /> <PackageReference Include="CryptoPro.Security.Cryptography.Xml" Version="2025.4.17" />

Теперь с помощью библиотек CryptoPro можно получить сертификаты с типом CpX509Certificate2 из хранилища сертификатов CpX509Store. Получим следующий код:

private static CpX509Certificate2? FindCertInCryptoProStore(string thumbprint, StoreName storeName, StoreLocation storeLocation) {     using var store = new CpX509Store(StoreName.My, StoreLocation.CurrentUser);      store.Open(OpenFlags.ReadOnly);      return store.Certificates         .Find(X509FindType.FindByThumbprint, thumbprint, false)         .FirstOrDefault(); }  public static IServiceCollection ConfigureApiHttpClient(this IServiceCollection services) {     services.AddSingleton(serviceProvider =>     {         var options = serviceProvider.GetRequiredService<IOptions<ApiOptions>>().Value;          return new ApiCertificates         {             //Загружаем серверный публичный сертификат (.cer)             PublicCert = FindCertInCryptoProStore(options.CerCertificateThumbprint, StoreName.My, StoreLocation.CurrentUser)!,             //Загружаем клиентский сертификат с приватным ключом (.pfx)             PrivateCert = FindCertInCryptoProStore(options.PfxCertificateThumbprint, StoreName.My, StoreLocation.CurrentUser)!         };     });      services.AddHttpClient<IApiHttpClient, ApiHttpClient>()         .ConfigurePrimaryHttpMessageHandler((serviceProvider) =>         {             var apiCertificates = serviceProvider.GetRequiredService<ApiCertificates>();              return new CpHttpHandler             {                 SslOptions = new()                 {                     ClientCertificates = [apiCertificates.PrivateCert],                     RemoteCertificateValidationCallback = (_, cert, _, sslPolicyErrors) =>                      {                         // Проверяем, совпадает ли сертификат с ожидаемым                         if (cert?.Thumbprint?.Equals(apiCertificates.PublicCert.Thumbprint, StringComparison.OrdinalIgnoreCase) == true)                             return true;                          // Если сертификат не совпадает, можно по желанию разрешить стандартную проверку TLS                         return sslPolicyErrors == SslPolicyErrors.None;                     }                 }             };         });      return services; }

В данном случае сертификат CryptoPro успешно достается из хранилища сертификатов CryptoPro и применяется в запросах на сервер. Вдобавок это решение работает и для Windows тоже.

Решение с помощью NGINX

Вместо интеграции ГОСТ TLS напрямую в .NET-приложение, можно вынести TLS-обвязку на уровень NGINX. Это снимает с .NET приложения (или приложения на любом другом языке программирования) необходимость подключения CryptoPro-сертификатов и реализации TLS взаимодействия, что упрощает код, повышает кроссплатформенность и масштабируемость решения.

Чтобы это работало с сертификатом CryptoPro необходимо воспользоваться cpnginx — специальной версией NGINX от CryptoPro с поддержкой ГОСТ TLS. Это решение содержится в linux-дистрибутивах, доступных на официальной странице загрузки CryptoPro CSP.

Получаем следующую схему взаимодействия с внешним API:

Таким образом:

• .NET-приложение посылает обычные HTTP-запросы на cpnginx;

• cpnginx выступает в роли клиента TLS, обрабатывая криптографию через CryptoPro CSP;

• cpnginx проксирует запрос на сервер и возвращает ответ приложению.

Для настройки CryptoPro Nginx необходимо создать внешний конфигурационный файл api-tls.conf. Этот конфиг необходимо поместить в директорию /etc/opt/cprocsp/cpnginx/conf.d/api-tls.conf. Все *.conf-файлы из этой директории автоматически подключаются к основному конфигурационному файлу cpnginx.

server {     listen 8080;  # cpnginx слушает обычный HTTP-порт 8080          #listen 443 sspi; # если нужен https     #sspi_certificate 0x7C00013D42201F55870674C594000100013D421; # Сертификат сервера NGINX (если https)          server_name localhost; # Имя сервера     sspi_protocols TLSv1.2; # Используемый TLS-протокол      location / {         proxy_pass https://external-api.ru; # API на который проксировать запрос         proxy_http_version 1.1; # Используем HTTP/1.1 при проксировании          proxy_sspi on; # Включаем использование SSPI - ГОСТ TLS при подключении         proxy_ssl_verify on; # Включаем проверку подлинности TLS-сертификата сервера API         proxy_ssl_server_name on; # Включаем передачу SNI (Server Name Indication) при TLS          proxy_ssl_certificate 0x0552A7B13510B2E8AE4C322F78CAB170BC; # Серийный номер клиентского сертификата .pfx         proxy_ssl_trusted_certificate Root; # Указываем хранилище, откуда cpnginx возьмет корневой (доверенный) сертификат для валидации сервера         proxy_ssl_verify_local_crl_only on; # Проверка на отзыв сертификата производится только по локальному CRL     } }

Для запуска cpnginx приложения в Linux соберем и запустим docker образ:

# Используем базовый образ Debian FROM debian:bullseye  # Обновляем систему и устанавливаем необходимые пакеты RUN apt-get update && apt-get install -y \     wget curl unzip gnupg lsb-release sudo \     libcap2-bin ca-certificates systemd libssl1.1 \     && apt-get clean && rm -rf /var/lib/apt/lists/*  # Создаем пользователя cpnginx RUN useradd -r -m -d /var/opt/cprocsp/cpnginx -s /bin/bash cpnginx  # Копируем дистрибутив CryptoPro в контейнер COPY ./crypto-pro/linux-amd64_deb.tgz /tmp/linux-amd64_deb.tgz  # Распаковка и установка дистрибутива CryptoPro с cpnginx WORKDIR /tmp RUN tar -xvzf linux-amd64_deb.tgz && \     cd linux-amd64_deb && \     ./install.sh cprocsp-nginx && \     rm -rf /tmp/linux-amd64_deb*  # Копируем сертификаты в контейнер COPY ./certs/private-cert.pfx /certs/private-cert.pfx COPY ./certs/public-cert.cer /certs/public-cert.cer  # добавление лицензионного ключа CryptoPro ARG CRYPTO_PRO_LICENSE RUN /opt/cprocsp/sbin/amd64/cpconfig -license -set ${CRYPTO_PRO_LICENSE}  #Установка тестового .cer (только открытая часть) в CryptoPro RUN echo o | sudo -u cpnginx /opt/cprocsp/bin/amd64/certmgr -install -store uRoot -file /certs/public-cert.cer  ARG PRIVATE_CERT_PASS #Установка production .pfx (экспортированный ключ с закрытой и открытой частью) в CryptoPro RUN sudo -u cpnginx /opt/cprocsp/bin/amd64/certmgr -install -pfx -file /certs/private-cert.pfx -pin ${PRIVATE_CERT_PASS} -silent  #Установка сертификатов из контейнеров в CryptoPro RUN sudo -u cpnginx /opt/cprocsp/bin/amd64/csptest -absorb -certs -autoprov  # Копируем конфигурацию cpnginx COPY ./config/sspi.conf /etc/opt/cprocsp/cpnginx/conf.d/api-tls.conf  # Устанавливаем права доступа к ключам RUN chown -R cpnginx:cpnginx /var/opt/cprocsp/keys/cpnginx && \     chmod -R go= /var/opt/cprocsp/keys/cpnginx  # Открываем порты EXPOSE 8080  # Запускаем cpnginx в режиме "foreground" CMD ["/opt/cprocsp/sbin/amd64/cpnginx", "-g", "daemon off;"]

NGINX успешно запускается и принимает входящие HTTP-запросы на http://localhost:8080 (настраивается) и проксирует их на внешний API с использованием CryptoPro TLS. Все запросы и ошибки логируются в /var/log/cpnginx/access.log и /var/log/cpnginx/error.log.

В приложении .NET конфигурация HttpClient упрощается. Остается только указать адрес nginx — куда посылать запросы:

private static IServiceCollection ConfigureApiHttpClient(this IServiceCollection services) {     services.AddHttpClient<IApiHttpClient, ApiHttpClient>(httpClient =>      {         httpClient.BaseAddress = new Uri("http://localhost:8080"); //адрес Nginx     });      return services; }

Получаем решение, которое обладает следующими преимуществами:

• Упрощение .NET-приложения — нет необходимости подключать и настраивать ГОСТ TLS в приложении. ‑TLS реализован на nginx.

• Независимость от языка программирования приложения.

• Изоляция криптографии — CryptoPro CSP используется только внутри контейнера cpnginx.

• Легкое масштабирование — cpnginx можно масштабировать независимо от самого приложения.

Как безопасно хранить сертификаты и пароли к ним

При работе с чувствительными данными, особенно такими как.pfx сертификаты с приватным ключом, крайне важно соблюдать правила безопасного хранения. На этапе разработки многие допускают ошибку — хранят сертификаты и пароли в открытом виде прямо в проекте, включая их в git‑репозиторий или конфигурационные файлы. Это недопустимо даже в условиях ограниченного доступа к репозиторию.

Правильным подходом является хранение сертификатов и секретов вне исходного кода. Кроме того, сертификаты не должны включаться в Docker‑образ напрямую. Вместо этого они монтируются во время запуска контейнера через Docker volume или persistent volume в Kubernetes. Пароли к ним считываются в runtime, не попадая в историю образа.

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

• Переменные окружения, определенные в CI/CD или на хост‑машине при запуске.

• Secrets‑хранилища: например, Azure Key Vault, AWS Secrets Manager, HashiCorp Vault.

• Docker Secrets / Kubernetes Secrets — для защищенной передачи секретов в контейнеры.

Такой подход позволяет обеспечить высокий уровень безопасности на всех этапах жизненного цикла приложения — от сборки до развертывания в production среде.

Заключение

Интеграция с API, использующим сертификаты CryptoPro и ГОСТ TLS, может показаться непростой задачей, особенно в кроссплатформенных проектах. В статье рассмотрено три рабочих варианта: реализацию для.NET‑приложений на Windows и на Linux, а также подход с использованием cpnginx — модифицированного NGINX с поддержкой ГОСТ TLS.

Наиболее универсальным и масштабируемым решением становится cpnginx. Он полностью изолирует криптографическую обвязку от логики приложения, устраняет зависимость от ОС, упрощает сопровождение и снижает риски, связанные с безопасностью. С его помощью.NET‑приложение может работать с API как с обычным HTTP‑сервисом, а все криптографические операции выполняются внутри защищённого контейнера.

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