mTLS GOST Gateway (CryptoPro CSP + cpnginx)

Docker image for proxying HTTP/SOAP traffic to external systems through GOST TLS with mutual TLS client authentication.

The gateway is configured by profiles in conf/profiles.yaml. At startup it renders a cpnginx.conf, imports trusted CA chains from trust/, optionally runs preflight checks, and starts a background certificate expiry watcher.

What is Included

• Multi-profile routing from conf/profiles.yaml.
• Runtime cpnginx config rendering.
• Trust-chain import into CryptoPro machine and cpnginx user stores.
• Optional preflight checks for every configured route.
• Daily certificate expiry logging for client and trusted certificates.
• Helper scripts for fetching and checking upstream certificate chains.

Example Integration Profiles

The public conf/profiles.yaml contains two ready-to-adapt example profiles:

• vtb - example profile for VTB Business / H2H SOAP integration.
• rfmo - example profile for RFMO / Russian financial monitoring service integration.

Both profiles intentionally use placeholder client certificate thumbprints. Set real thumbprints only in your local or deployment-specific configuration.

Repository Layout

• Dockerfile - image build for CryptoPro CSP, CryptoPro TLS and cpnginx.
• conf/profiles.yaml - public profile template with placeholder client cert thumbprints.
• scripts/entrypoint.sh - runtime orchestration.
• scripts/render-cpnginx-config.sh - cpnginx config generator.
• scripts/import-trust.sh - trust CA import into CryptoPro stores.
• scripts/preflight-check.sh - profile route and TLS smoke checks.
• scripts/cert-expiry-watch.sh - certificate expiry watcher.
• scripts/fetch-cert-chains.sh - upstream chain fetch helper.
• scripts/check-trust-certs.sh - local trust directory validation.
• trust/<profile>/roots|intermediates - public trusted CA chains per profile.
• cpnginx-keys/cpnginx/ - local-only key container mount/copy location.
• csp/ - local-only CryptoPro license files.

Sensitive Data Policy

Do not commit real client certificates, private key containers, .pfx files, PINs, production license keys, personal certificate owner names, or real client certificate thumbprints.

This repository keeps only public templates/placeholders for:

• csp/README.md
• cpnginx-keys/cpnginx/README.md
• conf/profiles.yaml client certificate thumbprints

Real key containers should stay local under cpnginx-keys/cpnginx/<container>.000/ or be mounted into the image/container by your deployment system.

Configure a Profile

Edit conf/profiles.yaml:

gateway:
  listen_port: 3010

profiles:
  - profile: example
    incoming:
      path_prefix: /example/
      wsdl_path_regex: null
    upstream:
      scheme: https
      host: api.example.org
      port: 443
      soap_path: /service
      wsdl_passthrough: false
    mtls:
      client_cert_thumbprint: "0xYOUR_CLIENT_CERT_THUMBPRINT"
      trusted_ca_alias: Root
      ssl_verify: true
      ssl_verify_depth: 4
      sni_host: api.example.org
      host_header: api.example.org

For each profile, put CA files into:

trust/<profile>/roots/
trust/<profile>/intermediates/

Supported trust file extensions are .pem, .cer, .crt, and .der.

Build

Place the CryptoPro Linux distribution at:

distr/linux-amd64_deb.tgz

Put local license values into:

csp/csp_license.txt
csp/tls_license.txt

Then build:

docker build -t mtls-gost-gateway:local .

If license files are missing or still contain placeholders, the build skips license installation. The resulting image is useful for structure checks, but a real CryptoPro runtime needs valid licenses.

Run

docker run --rm -p 3010:3010 \
  -e RUN_IMPORT_TRUST=1 \
  -e ENABLE_PREFLIGHT=1 \
  -e ENABLE_CERT_WATCHER=1 \
  mtls-gost-gateway:local

Common environment variables:

• PROFILES_FILE=/etc/mtls/profiles.yaml
• TRUST_DIR=/etc/mtls/trust
• RUN_IMPORT_TRUST=1
• ENABLE_PREFLIGHT=0
• ENABLE_CERT_WATCHER=1
• REQUEST_TIMEOUT_SEC=30
• REQUEST_TIMEOUT_RETRY_SEC=30
• PREFLIGHT_HTTP_METHOD=GET
• CERT_WATCH_LOG_MAX_MONTHS=6

Client Certificates

The profile value mtls.client_cert_thumbprint must match a certificate in CryptoPro uMy or mMy, and the certificate must have a private key link.

Inside a running container:

/opt/cprocsp/bin/amd64/certmgr -list -store uMy -all

Look for PrivateKey Link: Yes.

Updating Trust Chains

The helper can fetch upstream certificate chains into a staging directory:

OUTPUT_BASE=./trust-fetched bash scripts/fetch-cert-chains.sh

Review the generated certificates, copy only the required root and intermediate certificates into trust/<profile>/roots and trust/<profile>/intermediates, then validate:

bash scripts/check-trust-certs.sh

Preflight Behavior

Preflight calls each configured gateway route and treats 502, 404, and timeouts as failures. Other expected HTTP responses, such as 401, 403, 405, or 500, can still indicate that TLS and routing succeeded and the upstream application rejected the probe payload.