TLS 1.3 & mTLS

CoreSDK uses rustls for all TLS. There is no OpenSSL dependency and no TLS 1.2 fallback. Every connection between the wrapper SDK and the Sidecar daemon is TLS 1.3 with mutual authentication (mTLS).

No application code is required to enable mTLS. The SDK and Sidecar negotiate and maintain the mTLS channel automatically at startup. Localhost does not imply trust — a local Sidecar is held to the same certificate verification requirements as a remote one.

TLS 1.3 only

Negotiating an earlier protocol version is not possible — rustls rejects the handshake. This removes a class of downgrade attacks and eliminates cipher suites with known weaknesses.

Supported cipher suites (in preference order):

The cipher suite is negotiated by the TLS handshake. Preference order is fixed by the security policy above and cannot be overridden in application config.

mTLS: SDK-to-Sidecar

The Sidecar presents a server certificate. The SDK presents a client certificate. Both sides verify the other's certificate before any application data is exchanged.

SDK process                          Sidecar daemon
    |                                      |
    |--- ClientHello (TLS 1.3) ----------->|
    |<-- ServerHello + ServerCertificate --|
    |<-- CertificateRequest ---------------|
    |--- ClientCertificate --------------->|
    |--- Finished ------------------------>|
    |<-- Finished -------------------------|
    |                                      |
    |=== Mutually authenticated channel ===|

HMAC keys used for cache verification are distributed over this channel. They are never written to config files, environment variables, or any storage outside the mTLS session.

Client certificate lifecycle

Client certificates use ECDSA P-256 and have a 24-hour TTL. The SDK rotates them automatically without restarting the connection or the process.

Hot-swap is implemented via rustls::ResolvesClientCert. The resolver holds a reference to the current certificate behind an ArcSwap. A background task generates a new certificate and key pair, presents it to the Sidecar for countersigning, and atomically swaps the ArcSwap pointer. In-flight requests complete under the old certificate; new requests use the new one.

The default renewal threshold is 75% of the TTL (18 hours). Renewal never requires a process restart.

Application configuration

mTLS is on by default. The only optional environment variable is the CA certificate path — used when your deployment provides certificates from an internal PKI rather than the auto-generated development CA.

Python

from coresdk import CoreSDKClient, SDKConfig

# Development — auto-generates ephemeral certificates, no CA cert needed
_sdk = CoreSDKClient(SDKConfig(
    sidecar_addr="127.0.0.1:50051",
    tenant_id="acme",
    service_name="orders-api",
    fail_mode="open",
))

# Production — point to your internal CA cert via env var
# CORESDK_SIDECAR_CA_CERT=/etc/coresdk/ca.pem
# Then use SDKConfig.from_env() to pick it up automatically:
_sdk = CoreSDKClient(SDKConfig.from_env())

Rust

use coresdk_engine::{Engine, EngineConfig};

// Reads CORESDK_SIDECAR_ADDR, CORESDK_SIDECAR_CA_CERT, etc. from env
let engine = Engine::from_env()?;

Certificate issuance: development vs production

In development, the SDK generates a self-signed CA and issues its own client certificates automatically — no PKI setup required.

In production, set CORESDK_SIDECAR_CA_CERT to a CA certificate issued by your internal PKI (e.g., SPIFFE/SPIRE). The SDK validates the Sidecar's server certificate against this CA on every connection.

The SDK enforces that development self-signed mode is not active when CORESDK_ENV=production.

Compliance references

Next steps

• PII & Secrets Masking — HMAC keys distributed over the mTLS channel are used to verify cached policy decisions
• Resilience Primitives — how the SDK behaves when the mTLS channel to the Sidecar is unavailable
• Deployment — certificate provisioning in Kubernetes and Docker environments