← Back to TLSMCP Overview

How TLSMCP Works
From Install to Enforced mTLS in Minutes

A technical walkthrough of TLSMCP's architecture, certificate lifecycle, and deployment models. See exactly how TLSMCP deploys as a sidecar proxy, manages certificate issuance and rotation, and enforces mutual TLS on every connection.

Three Steps to Enforced mTLS

TLSMCP is designed for minimal friction. Deploy the binary, point it at your services, and watch mTLS enforcement activate.

1

Install

Deploy TLSMCP as a sidecar binary or container alongside your service. One command, minimal config.

$ curl -s https://install.cyphers.ai \
    | sh
✓ TLSMCP installed
  Version: 1.4.2
  Location: /usr/local/bin/tlsmcp
2

Configure

Point TLSMCP at your services, set TLS policy, and define certificate lifetimes. Config is version-controlled.

# tlsmcp-config.yaml
services:
  - name: api
    listen: :8443
    backend: localhost:3000
    mtls: required
3

Enforce

TLSMCP starts, validates client certs at the TLS handshake, and forwards authenticated requests to your app.

$ tlsmcp run --config tlsmcp-config.yaml
✓ TLSMCP proxy active
  Listening: :8443 (mTLS required)
  Backend: localhost:3000
  Policy: Certs from Cyphers Hub

Sidecar Proxy Architecture

TLSMCP deploys alongside your service, transparently handling TLS termination and certificate validation. Your application never touches TLS.

Client A
with cert
Service B
with cert
Worker
with cert
mTLS handshake · TLS 1.3
TLSMCP Sidecar
TLS terminated · Certificate validated · Identity verified
Your App
localhost:3000
Plain HTTP (trusted)
Cyphers Hub — Policy · Certs · Audit

Why Sidecar?

  • Zero application changes: Your app remains ignorant of TLS. No SDKs, no refactoring, no dependency hell.
  • Transparent enforcement: Every incoming connection is validated before it reaches your code. If the cert is invalid, the connection is rejected at the TLS layer.
  • Service isolation: Each service gets its own TLSMCP instance, independent of others. Easy to enable/disable per service.
  • Observable: All TLS handshakes, certificate validation results, and connection metadata are logged and visible in Cyphers Hub.

Single Connection Lifecycle

Watch what happens, step by step, when a client connects to a TLSMCP-protected service.

1

TCP Connect

Client initiates a TCP connection to TLSMCP's listening port (e.g., :8443). TLSMCP accepts the connection.

2

TLS Handshake (ClientHello)

Client sends a TLS 1.3 ClientHello. TLSMCP responds with ServerHello, using TLSMCP's server certificate (issued by Cyphers Hub).

3

Client Certificate Presentation

Client presents its certificate in the CertificateVerify message. TLSMCP immediately retrieves the client cert (from its local cache or Cyphers Hub).

4

Certificate Validation

TLSMCP verifies: issuer (signed by Cyphers Hub CA), not revoked, not expired, CN matches expected service. If validation fails, the handshake is aborted and the connection is closed.

5

Handshake Complete

Both sides derive session keys. TLS channel is encrypted. TLSMCP logs the successful mTLS handshake with client identity, timestamp, and cert details to Cyphers Hub.

6

Request Forwarding

Application data (HTTP requests) flow over the encrypted TLS channel. TLSMCP decrypts, validates that the connection is still valid, and forwards to localhost:app-port.

7

Response Return

Your app sends a response back to TLSMCP. TLSMCP encrypts it with the TLS session key and sends it back to the client.

8

Connection Close / Renewal

Either side can close the TLS connection. If client cert is approaching expiry, TLSMCP suggests renewal via Cyphers Hub. Subsequent connections use fresh certificates.

Certificate Management Deep Dive

How TLSMCP handles certificate issuance, storage, rotation, and revocation across your fleet.

Issuance & Storage

When TLSMCP starts, it contacts Cyphers Hub and requests:

  • Server certificate: For TLS termination. Valid for 1 year, auto-renewed 30 days before expiry.
  • Revocation list: Current revoked client cert serials, cached locally. Updated every 5 minutes or on-demand.
  • Trust root: Cyphers Hub's CA certificate, pinned in TLSMCP config.

Certificates are stored in secure local storage (encrypted at rest if using encrypted volumes).

# Initialize TLSMCP
$ tlsmcp init --hub-url \
    https://hub.cyphers.ai \
    --service-id api-prod-01
✓ Initialized
  Server cert: downloaded
  Trust root: pinned
  Revocation: cached (5min TTL)

# Check local certs
$ tlsmcp cert info
  Server cert:
    Expires: 2026-12-21
    Renews: 2026-11-21

Rotation & Auto-Renewal

TLSMCP monitors certificate expiry in the background. When a certificate reaches its renewal threshold (30 days for server certs, configurable for client certs), TLSMCP:

  • 1. Requests a fresh certificate from Cyphers Hub with the same CN and properties.
  • 2. Overlaps validity windows — the old cert remains valid for 3-5 days after the new one is active.
  • 3. Switches gracefully — new TLS connections use the new cert; old connections continue on the old cert.
  • 4. Verifies replacement — ensures the new cert is valid before retiring the old one.

Result: zero-downtime rotation. Clients never see "certificate not found" or mid-connection revocation.

# Monitor renewals
$ tlsmcp renew --watch

14:30:01 INFO: Checking cert
            old_cert (exp: 14d)
14:30:02 INFO: Requesting renewal
14:30:03 INFO: New cert issued
            new_cert (exp: 365d)
14:30:04 INFO: Validation OK
14:30:05 INFO: Active for new
            conns
14:30:06 INFO: Overlap: 5d
            (old still valid)

Revocation & Instant Termination

Revocation is not a CRL download or OCSP check. Cyphers Hub pushes revocation events directly to TLSMCP instances:

  • 1. Admin revokes cert in Hub (or via API/CLI)
  • 2. Hub sends webhook to all proxy instances with the revoked serial number.
  • 3. TLSMCP receives webhook (< 500ms typical)
  • 4. Updates local revocation list in-memory.
  • 5. Terminates active connections using the revoked cert (if any).
  • 6. Rejects new connections attempting to use revoked cert.

Propagation time: < 1 second across a fleet. No CRL lag, no OCSP latency, no caching delays.

# At Cyphers Hub:
$ cyphers revoke --cert \
    worker-07.staging \
    --reason \
    key_compromise
✓ Revoked

# At TLSMCP instance:
14:35:22 WARN: Revocation received
            worker-07
14:35:22 WARN: Killing 2 active
            conns
14:35:22 WARN: Future conns:
            REJECTED

TLSMCP Config Reference

Full example of a TLSMCP configuration file, covering service definitions, TLS policies, and certificate settings.

# tlsmcp-config.yaml — TLSMCP Sidecar Configuration

version: 1
service_id: api-prod-01
hub_url: https://hub.cyphers.ai
auth_token: tlsmcp_xxxxxxxxxxxx

# TLS listener on port 8443
listen: :8443
tls:
  protocol: tls13
  client_auth: required
  cipher_suites:
    - TLS_AES_256_GCM_SHA384
    - TLS_CHACHA20_POLY1305_SHA256
  server_cert_renewal_days: 30

# Backend service (your app)
backend:
  address: localhost:3000
  protocol: http
  health_check: true
  health_path: /health

# Certificate policies (per service)
certificate_policies:
  client:
    allowed_duration:
      min: 1h
      max: 12m
    auto_renew: true
    renewal_before_expiry: 5m
    required_cn_pattern: ^.*\.prod$

logging:
  level: info
  audit_enabled: true
  hub_sync: true
  metrics_port: 9090

Key Configuration Notes

  • client_auth: required — TLSMCP refuses connections without a valid client certificate.
  • tls13 — Only TLS 1.3. No fallback to older, weaker protocols.
  • server_cert_renewal_days: 30 — TLSMCP will request a renewal 30 days before the server cert expires.
  • health_check — TLSMCP verifies the backend service is healthy before accepting connections.
  • required_cn_pattern — Restrict which client certificate CNs are allowed (optional, but recommended).
  • audit_enabled: true — Every connection handshake is logged and sent to Cyphers Hub.

TLSMCP Deployment Models

Choose the deployment pattern that fits your architecture and scale.

Sidecar (Per-Service)

One TLSMCP instance per service. Each service gets its own listening port and certificate policy.

  • Best for: Microservices, Kubernetes, containers.
  • Scaling: Easy — add TLSMCP container alongside each service pod.
  • Management: Independent per service — no shared state.
  • Example: Kubernetes pod with app container + TLSMCP sidecar container.

Gateway (Edge Proxy)

One TLSMCP instance protects multiple services. Clients connect to the gateway; it routes to backends.

  • Best for: Traditional infrastructure, VMs, multiple services on one host.
  • Scaling: Centralized — one gateway handles all mTLS.
  • Management: Single config file for all services.
  • Example: TLSMCP on port 8443 fronts API, DB, cache services on localhost:3000, 5432, 6379.

Hybrid

Sidecar for critical services, gateway for others. Mix and match based on security/performance needs.

  • Best for: Large deployments with varying requirements.
  • Scaling: Flexible — sidecars for high-traffic, gateway for low-traffic.
  • Management: Per-service policies, unified certificate authority.
  • Example: API servers → sidecars; internal utilities → gateway.

TLSMCP Integrations & Deployment Environments

TLSMCP integrates with the tools and platforms you already use.

Docker / Containers

Deploy TLSMCP as a sidecar container or in a multi-container pod. Share volumes for certificates. Environment variables for config.

docker run -p 8443:8443 \
  -v config:/etc/tlsmcp \
  -e HUB_URL=https://hub.cyphers.ai \
  -e SERVICE_ID=api-01 \
  cyphers/tlsmcp:latest

Kubernetes

Deploy as a sidecar container in Pods. Use ConfigMaps for config, Secrets for auth tokens. TLSMCP auto-discovers Cyphers Hub via Service DNS.

containers:
  - name: api
    image: myapp:latest
  - name: tlsmcp
    image: cyphers/tlsmcp:latest

Systemd / VMs

Run TLSMCP as a systemd service. Config in /etc/tlsmcp/, certificates in /var/lib/tlsmcp/. Auto-restart on failure.

# /etc/systemd/system/tlsmcp.service
[Service]
Type=simple
ExecStart=/usr/local/bin/tlsmcp run
Restart=always

CI/CD Pipelines

Issue short-lived client certs (1-4 hours) for build runners, deployment agents. Certs auto-revoke after job completion. Each job gets its own identity.

cyphers issue-ci-cert \
  --job $CI_JOB_ID \
  --ttl 2h \
  --output ./client.pem

Database Clients

Protect database connections (PostgreSQL, MySQL, MongoDB) with mTLS. Each service gets its own certificate. No shared passwords.

psql -h localhost:8443 \
  --cert client.pem \
  --key client-key.pem

Multi-Cloud / Hybrid

Deploy TLSMCP on AWS, GCP, Azure, on-prem. All instances connect to the same Cyphers Hub. Unified certificate policy across clouds.

# One Hub, many clouds
Cyphers Hub (centralized)
  ├─ AWS (5 TLSMCP instances)
  ├─ GCP (3 TLSMCP instances)
  └─ On-prem (2 TLSMCP instances)

Monitoring & Observability

Visibility into every mTLS connection, certificate event, and policy decision.

Prometheus Metrics

TLSMCP exposes Prometheus metrics on :9090/metrics:

  • tlsmcp_connections_total — Total TLS connections (labeled success/failed/revoked).
  • tlsmcp_handshake_duration_ms — TLS handshake latency histogram.
  • tlsmcp_cert_expiry_days — Days until cert expiry (gauge).
  • tlsmcp_revocation_events_total — Number of revocations processed.
  • tlsmcp_hub_sync_latency_ms — Latency to sync with Cyphers Hub.

Plug into Grafana, Datadog, or any Prometheus-compatible monitoring system.

Cyphers Hub Dashboard

Real-time visibility in Cyphers Hub:

  • Connection audit log — Every handshake with client CN, timestamp, status.
  • Certificate inventory — All active certs per service, expiry times, renewal status.
  • Fleet health — All TLSMCP instances, their status, uptime, sync latency.
  • Policy timeline — Changes to TLS policies, new services, revocations (audit trail).
  • Webhook logs — Delivery status of revocation webhooks to each proxy.

Health Endpoints

TLSMCP exposes health and readiness checks:

  • GET /health — Returns 200 if TLSMCP is running and Hub is reachable. Used by K8s liveness probes.
  • GET /ready — Returns 200 if TLSMCP is ready to accept connections. Used by K8s readiness probes.
  • GET /info — Returns service ID, version, uptime, cert expiry times (JSON).

How It Works Questions, Answered

What is the performance overhead of TLSMCP?

TLS handshake adds 5-15ms per new connection (typical for TLS 1.3). Per-request latency is negligible — TLSMCP decrypts and forwards in < 1ms. With connection pooling, the handshake cost is amortized. For reference, a 1000 req/s service with 10-minute connection lifetime sees the handshake cost on only ~1.7 requests, or < 0.02% overhead.

What cipher suites does TLSMCP support?

TLSMCP supports TLS 1.3 only. Default cipher suites are TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256. Both offer 256-bit symmetric encryption and modern AEAD construction. No legacy ciphers (3DES, RC4, MD5) are supported or negotiated. You can restrict ciphers further in config if needed for compliance.

Can I reload configuration without restarting TLSMCP?

Yes. TLSMCP watches the config file for changes and hot-reloads. Send SIGHUP to the process or use tlsmcp reload --config /path/to/config.yaml. Changes to TLS policies, service definitions, and certificate settings take effect in < 500ms without dropping active connections.

How does TLSMCP handle multi-region deployments?

All TLSMCP instances connect to a single Cyphers Hub (which can be deployed for high availability in your primary region or a dedicated control plane). Certificate issuance and revocation are managed centrally. Each TLSMCP instance caches the revocation list locally, so revocation propagates in < 1 second across regions. Certificate CNs can include region/zone info for geospatial identity if needed.

What happens if Cyphers Hub becomes unreachable?

TLSMCP continues operating with cached data. Existing connections stay alive. New connections are allowed if the client certificate is already cached and not revoked. TLSMCP will attempt to re-sync with the Hub every 30 seconds. Once Hub is reachable, it downloads the latest revocation list and policy updates. Typical downtime: minutes without impact to traffic.

Can TLSMCP validate client certs from my existing CA?

Yes. TLSMCP can trust multiple CAs. You can configure it to accept client certs signed by Cyphers Hub, your internal CA, or both. Set trusted_roots in the config to point to CA certificates. TLSMCP validates the full chain and checks against revocation lists for each CA independently.

How are client certificate private keys stored?

Private keys are generated by the service requesting the certificate (e.g., your app, a CI job) and never sent to Cyphers Hub. The Hub issues only the certificate (public key + metadata). You store the private key securely on the client side — in a secret manager (HashiCorp Vault, AWS Secrets Manager), environment variables, or mounted volumes. TLSMCP only reads and uses the certificates and keys you provide; it doesn't manage the private key lifecycle.

What happens during a certificate rotation with active connections?

TLSMCP maintains an overlap window (default 5 days). Old and new certificates are both valid during this window. Existing connections using the old certificate continue uninterrupted. New TLS connections use the new certificate. Once the old cert's overlap window closes, it becomes invalid (and any remaining old connections are terminated gracefully). Zero-downtime rotation is guaranteed.

Can I use TLSMCP with gRPC, WebSockets, or custom protocols?

Yes. TLSMCP operates at the TLS layer, below the application protocol. It works with HTTP/1.1, HTTP/2 (h2), gRPC, WebSockets, raw TCP, or any protocol that runs over TLS. The backend receives plaintext data regardless of protocol. Just point TLSMCP at your service's backend address and port, and it handles the rest.

What compliance standards does TLSMCP support?

TLSMCP uses TLS 1.3 with modern ciphers, which meets PCI-DSS, HIPAA, SOC 2, and ISO 27001 requirements. Audit logging (enabled by default) tracks every certificate issuance, validation decision, and revocation. You can export audit logs for compliance reporting. Short-lived certificates and auto-rotation support zero-trust and modern security frameworks.

Try It Yourself
Start With One Service

Deploy TLSMCP and issue your first client certificate. See mTLS working in your environment — free.