# How to Configure TLS Stealth and MITM Proxy with Certificate Management in OmniRoute

> Configure TLS stealth and MITM proxy in OmniRoute. Automate root CA certificate generation and system-wide installation on Windows macOS and Linux with this guide.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Enable the `ENABLE_TLS_FINGERPRINT` feature flag, start the MITM proxy with `npm run start:mitm`, and let OmniRoute automatically generate the root CA certificate and install it system-wide on Windows, macOS, and Linux.**

Configuring TLS stealth and MITM proxy with certificate management in OmniRoute allows you to masquerade outbound traffic as native client traffic, bypassing fingerprint-based detection. This guide covers the complete setup based on the `diegosouzapw/OmniRoute` source code, from feature flags to cross-platform certificate installation.

---

## How TLS Stealth Works in OmniRoute

TLS stealth mode in OmniRoute works by intercepting TLS handshakes, terminating them with a locally-generated root CA, then re-encrypting traffic to upstream providers while rewriting handshake fields to match official client fingerprints.

The architecture consists of five core components:

| Component | Purpose | Source Location |
|-----------|---------|---------------|
| **Feature flag** | Toggles the stealth pipeline on/off | [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) |
| **MITM proxy** | Intercepts and re-encrypts TLS traffic | `src/mitm/*` |
| **Root CA generation** | Creates deterministic self-signed certificate | [`src/mitm/cert/generate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/generate.ts) |
| **System trust store installation** | Installs CA into OS-specific stores | [`src/mitm/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) |
| **JA3/JA4 fingerprint matching** | Rewrites TLS handshake fields to mimic native clients | [`src/mitm/tproxy/tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/tlsCapture.ts) |

When `ENABLE_TLS_FINGERPRINT` is active, every proxied request carries the same TLS fingerprint as the official provider client, dramatically reducing CAPTCHA triggers and IP bans.

---

## Enabling the TLS Stealth Feature Flag

Set the environment variable before starting OmniRoute:

```bash
export ENABLE_TLS_FINGERPRINT=true

```

Or add to your `.env` file:

```bash
ENABLE_TLS_FINGERPRINT=true

```

The flag is consumed by `proxyFetchEnabled()` in [`src/open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/utils/proxyFetch.ts):

```typescript
export const proxyFetchEnabled = () => process.env.ENABLE_TLS_FINGERPRINT === "true";

```

If the flag is **false** or unset, the proxy operates in normal (non-stealth) mode without fingerprint rewriting.

---

## Starting the MITM Proxy

Launch the proxy using either method:

```bash

# NPM script

npm run start:mitm

# Direct CLI execution

node ./bin/omniroute.mjs --mitm

```

On startup, the proxy automatically:

1. **Generates the root CA** (`omniroute-mitm.crt`) at `dataDir/mitm/` if missing
2. **Detects the host OS** and selects the appropriate installation routine

No manual certificate creation is required.

---

## Certificate Management Architecture

OmniRoute handles the complete certificate lifecycle: generation, installation verification, and NSS database updates for browsers.

### Generating the Root CA

The [`generate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/generate.ts) module creates a deterministic, self-signed X.509 certificate:

- Public key: `dataDir/mitm/omniroute-mitm.crt`
- Private key: stored alongside with appropriate permissions

The certificate is reused across restarts to maintain consistent trust relationships.

### Installing to System Trust Stores

The `installCert()` function in [`src/mitm/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) checks installation status before attempting changes:

```typescript
export async function checkCertInstalled(certPath: string): Promise<boolean> {
  if (IS_WIN) return checkCertInstalledWindows(certPath);
  if (IS_MAC) return checkCertInstalledMac(certPath);
  return checkCertInstalledLinux(certPath);
}

```

#### macOS Installation

Uses the `security` command to query and modify the System Keychain:

```bash
security find-certificate -a -Z /Library/Keychains/System.keychain

```

Fingerprint normalization ensures reliable comparison:

```typescript
export function macCertOutputHasFingerprint(
  securityOutput: string, 
  fingerprint: string
): boolean {
  const normalize = (value: string) => value.replace(/:/g, "").toUpperCase();
  return normalize(securityOutput).includes(normalize(fingerprint));
}

```

#### Linux Installation

Detects the distribution and selects the correct certificate management tool:

| Distribution | Tool | Certificate Directory |
|-------------|------|----------------------|
| Debian/Ubuntu | `update-ca-certificates` | `/usr/local/share/ca-certificates/` |
| Arch | `update-ca-trust` | `/etc/ca-certificates/trust-source/anchors/` |
| Fedora/RHEL | `update-ca-trust extract` | `/etc/pki/ca-trust/source/anchors/` |
| openSUSE | `update-ca-certificates` | `/etc/ssl/certs/` |

The configuration is resolved dynamically:

```typescript
function getLinuxCertConfig(): LinuxCertConfig {
  for (const config of LINUX_CERT_PATHS) {
    if (fs.existsSync(config.dir)) return config;
  }
  return LINUX_CERT_PATHS[0]; // fallback
}

```

#### Windows Installation

Uses `certutil` with the certificate thumbprint:

```typescript
export function certutilThumbprint(certPath: string): string {
  return getCertFingerprint(certPath).replace(/:/g, "");
}

```

The command `certutil -store Root <thumbprint>` verifies existing installation.

### Updating NSS Databases (Firefox/Chrome)

Browser-specific certificate stores are updated via `updateNssDatabases()`:

```typescript
const script = `
  set -u
  if ! command -v certutil &> /dev/null; then exit 0; fi
  DIRS="$HOME/.pki/nssdb $HOME/snap/chromium/current/.pki/nssdb"
  # Firefox profiles, Snap-Firefox, etc.

  for db in $DIRS; do
    if [ -d "$db" ]; then
      if [ "$ACTION" = "add" ]; then
        certutil -d sql:"$db" -A -t "C,," -n "$CERT_NAME" -i "$CERT_PATH" 2>/dev/null || \
        certutil -d "$db" -A -t "C,," -n "$CERT_NAME" -i "$CERT_PATH" 2>/dev/null || true
      fi
    fi
  done
`;

```

Environment variables `CERT_NAME`, `CERT_PATH`, and `ACTION` are passed safely without shell interpolation (lines 46-50 in [`install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/install.ts)), preventing injection attacks.

---

## Complete Configuration Example

```bash

# Step 1: Enable TLS stealth mode

export ENABLE_TLS_FINGERPRINT=true

# Step 2: Start the MITM proxy (auto-generates and installs CA)

npm run start:mitm

# Step 3: Verify certificate installation programmatically

node - <<'EOS'
import { checkCertInstalled } from './src/mitm/cert/install.js';
const path = './data/mitm/omniroute-mitm.crt';
console.log('CA installed?', await checkCertInstalled(path));
EOS

```

**Expected output:**

- Console message: `✅ Certificate already installed` (or installation progress)
- Certificate visible in: macOS Keychain Access, Windows Certificate Manager, or Linux trust store
- All OmniRoute traffic presents matching JA3/JA4 fingerprints to upstream providers

---

## Key Source Files Reference

| File | Function |
|------|----------|
| [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) | Declares `ENABLE_TLS_FINGERPRINT` at line 110 |
| [`src/open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/utils/proxyFetch.ts) | Reads stealth flag at line 22 |
| [`src/mitm/cert/generate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/generate.ts) | Root CA certificate generation |
| [`src/mitm/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) | Cross-platform trust store installation (lines 42-50 for NSS script) |
| [`src/mitm/tproxy/setup.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/setup.ts) | Transparent proxy initialization |
| [`docs/security/STEALTH_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/STEALTH_GUIDE.md) | Extended documentation and troubleshooting |

---

## Summary

- **Enable stealth**: Set `ENABLE_TLS_FINGERPRINT=true` as environment variable
- **Start proxy**: Use `npm run start:mitm` for automatic CA generation and installation
- **Certificate auto-management**: OmniRoute handles generation, system trust store installation, and NSS database updates for all major platforms
- **Fingerprint matching**: TLS handshake fields are rewritten to match official clients via [`tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tlsCapture.ts)
- **Zero manual steps**: The CA is deterministic and persists across restarts

---

## Frequently Asked Questions

### How do I verify the MITM certificate is properly installed?

Run `checkCertInstalled()` from [`src/mitm/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) with the path to your generated certificate. On macOS, you can also use `security find-certificate -c "omniroute-mitm"` in Terminal. On Linux, check `ls /etc/ssl/certs/ | grep omniroute`. Windows users can run `certutil -store Root` and search for the thumbprint.

### Does enabling TLS stealth affect connection performance?

The MITM proxy introduces minimal overhead—typically under 5ms per request. The TLS termination and re-encryption happen locally, and JA3/JA4 fingerprint rewriting occurs during the initial handshake only. According to the OmniRoute source code, no persistent connection pooling modifications are required.

### What happens if the certificate expires?

The root CA generated by [`src/mitm/cert/generate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/generate.ts) uses a long validity period (typically 10 years). If you need to rotate certificates, delete `dataDir/mitm/omniroute-mitm.crt` and restart the proxy. The installation routines in [`install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/install.ts) will automatically replace the old certificate in all trust stores.

### Can I use TLS stealth without installing the system-wide certificate?

No. The MITM proxy must terminate TLS connections locally, which requires clients to trust the generated CA. Without system-wide installation, all HTTPS requests through OmniRoute will fail certificate validation. The automated installers in [`src/mitm/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) handle this securely across Windows, macOS, and Linux without manual intervention.