CEF Secure Payments Backend

1. Overview

The CEF Secure Payments Backend module implements a local HTTPS CONNECT proxy used by BastionGuard to provide a hardened and sandboxed browsing environment for secure payment operations.

The module acts as an intermediary between client applications (typically browsers configured to use the local proxy) and remote HTTPS endpoints. Upon the first qualifying CONNECT request, it launches a dedicated CEF-based secure browser UI with Chromium sandboxing enabled.

This component is designed to:

  • Expose a local loopback-only proxy endpoint
  • Intercept HTTPS CONNECT requests
  • Launch the Secure Payments CEF UI on demand
  • Provide transparent bidirectional tunneling after validation
  • Maintain strict privilege and sandbox separation

2. Architecture and Responsibilities

The module is implemented as a standalone executable and combines multiple responsibilities:

  • CEF initialization with sandbox enabled
  • Minimal HTTP CONNECT parsing
  • Local TCP proxy server (Boost.Asio)
  • On-demand SecureBrowser UI launch
  • Bidirectional socket forwarding
  • Graceful shutdown handling

All network operations are limited to the local host by default and no clear-text HTTP traffic is processed.

3. Command-Line Interface

The backend supports a minimal command-line interface:

  • --listen <address> – IP address to bind the proxy server (default: 127.0.0.1)
  • --port <port> – TCP port to listen on (default: 3130)

These parameters allow flexible integration with different desktop or browser configurations.

4. HTTP CONNECT Parsing

4.1 Minimal CONNECT Line Parsing

The module implements a minimal and strict parser for HTTP CONNECT requests. Only requests in the following format are accepted:

CONNECT host:port HTTP/1.1

The parser:

  • Validates the HTTP method (CONNECT)
  • Extracts host and port
  • Rejects malformed or unsupported requests

Non-CONNECT requests result in an immediate 405 Method Not Allowed response.

4.2 Error Handling

If hostname resolution or remote connection fails, the proxy responds with:

HTTP/1.1 502 Bad Gateway

and terminates the client connection.

5. SecureBrowser UI Launch Logic

5.1 Single-Instance UI Enforcement

The Secure Payments UI is launched lazily and strictly only once per backend lifecycle.

This behavior is enforced using an atomic flag:

  • std::atomic<bool> g_ui_opened

On the first valid CONNECT request, the backend spawns a detached thread that opens the SecureBrowser UI targeting:

https://<requested-host>

Subsequent CONNECT requests do not trigger additional UI instances.

5.2 Future Domain Filtering Hook

The launch point is explicitly designed to support future logic such as:

  • Payment domain allowlists
  • URL classification
  • Secure Payments enable/disable checks

This logic can be inserted before invoking SecureBrowser::open().

6. Bidirectional TCP Tunneling

6.1 Tunnel Establishment

After successfully connecting to the remote target, the proxy replies with:

HTTP/1.1 200 Connection Established
Proxy-Agent: BastionGuard-CEF

From this point onward, the proxy operates as a transparent TCP tunnel.

6.2 Forwarding Implementation

Bidirectional forwarding is implemented using two dedicated threads:

  • Client → Remote
  • Remote → Client

Each direction continuously reads and writes fixed-size buffers until an error or EOF occurs.

Socket shutdown behavior:

  • Only the sending side of the destination socket is shut down per direction
  • Full socket closure occurs only after both forwarding threads terminate

This design avoids premature connection termination and improves compatibility with TLS streams.

7. CEF Integration

7.1 CEF Application Class

The backend defines a custom CEF application class implementing:

  • CefApp
  • CefBrowserProcessHandler

The browser process handler is returned via GetBrowserProcessHandler().

7.2 Command-Line Hardening

The following Chromium command-line switches are enforced:

  • --incognito
  • --disable-extensions
  • --no-first-run
  • --no-default-browser-check

This configuration ensures a clean, isolated, and deterministic browser environment.

7.3 Sandbox Configuration

CEF is initialized with sandbox support explicitly enabled:

settings.no_sandbox = false;

This provides process-level isolation for renderer, GPU, and utility subprocesses.

8. CEF Lifecycle Management

8.1 Subprocess Execution

Before full initialization, the backend executes:

CefExecuteProcess()

This allows Chromium subprocesses to exit cleanly when invoked in secondary roles.

8.2 Initialization and Shutdown

The main process initializes CEF using CefInitialize() and performs a clean shutdown via:

CefShutdown()

Shutdown is guaranteed even in the presence of proxy runtime errors.

9. Proxy Server Runtime

9.1 Boost.Asio Server Loop

The proxy backend uses a synchronous accept loop based on boost::asio::ip::tcp::acceptor.

Each incoming connection is handled by a detached thread invoking handle_client().

9.2 Signal Handling

Graceful termination is implemented using boost::asio::signal_set:

  • SIGINT
  • SIGTERM

Upon signal reception, the I/O context is stopped and the process exits cleanly.

10. Security Considerations

  • Loopback binding: the proxy listens on localhost only by default
  • Protocol restriction: only HTTP CONNECT is supported
  • Sandboxing: Chromium sandbox is explicitly enabled
  • Single UI instance: prevents UI flooding or abuse
  • No traffic inspection: TLS payload remains opaque
  • Thread isolation: each client connection is handled independently

11. Integration with BastionGuard Secure Payments

This backend is activated when the Secure Payments feature is enabled in BastionGuard settings.

It is designed to work in conjunction with:

  • Domain and URL allowlists (payments.json)
  • CEF SecureBrowser frontend
  • SettingsStore feature toggles

The backend itself is intentionally minimal and delegates all policy decisions to higher-level BastionGuard components.

Published on:
Last updated on: