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.
Install
Deploy TLSMCP as a sidecar binary or container alongside your service. One command, minimal config.
| sh
✓ TLSMCP installed
Version: 1.4.2
Location: /usr/local/bin/tlsmcp
Configure
Point TLSMCP at your services, set TLS policy, and define certificate lifetimes. Config is version-controlled.
services:
- name: api
listen: :8443
backend: localhost:3000
mtls: required
Enforce
TLSMCP starts, validates client certs at the TLS handshake, and forwards authenticated requests to your app.
✓ 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.
with cert
with cert
with cert
localhost:3000
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.
TCP Connect
Client initiates a TCP connection to TLSMCP's listening port (e.g., :8443). TLSMCP accepts the connection.
TLS Handshake (ClientHello)
Client sends a TLS 1.3 ClientHello. TLSMCP responds with ServerHello, using TLSMCP's server certificate (issued by Cyphers Hub).
Client Certificate Presentation
Client presents its certificate in the CertificateVerify message. TLSMCP immediately retrieves the client cert (from its local cache or Cyphers Hub).
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.
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.
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.
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.
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).
$ 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.
$ 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.
$ 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.
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.
-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.
- 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.
[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.
--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.
--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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Part of the [cyphers] ecosystem
HTTPS Node
Automated HTTPS for every node. Zero-config TLS termination and certificate management.
TLSMCP current
mTLS proxy and full certificate lifecycle automation for both client and server certificates.
TLS for Claude
Verified machine identity for AI agents and MCP connections. Built on TLSMCP.