mTLS Configuration

SCHEMABOUND supports mutual TLS authentication via the schemabound-certgen binary and runtime PEM loading. This section covers setup, usage, and configuration for production and development deployments.

certgen Binary

The schemabound-certgen CLI generates a certificate authority (CA), server certificates, and client certificates required for mTLS. It is the supported tool for generating all certificate material used by SCHEMABOUND services.

Installation

Build from source:

cargo build --release -p schemabound-certgen
cp target/release/schemabound-certgen /usr/local/bin/

Or use a release binary from the project releases page.

Generating Certificates

Generate a full mTLS certificate chain:

schemabound-certgen generate \
  --output-dir ./certs \
  --ca-name "SCHEMABOUND CA" \
  --server-cn "myservice.local" \
  --client-cn "admin-client"

This produces:

Customizing Certificates

Use --help for full option listing. Common options:

schemabound-certgen generate --help

• --output-dir — Directory to write certificates (default: ./certs)
• --ca-name — CN for the root CA (default: "SCHEMABOUND CA")
• --server-cn — Common name for server certificate (default: "localhost")
• --client-cn — Common name for client certificate (default: "client")
• --days — Certificate validity in days (default: 365)

Runtime Configuration

Services load certificates at startup via a trait-based configuration module that supports multiple transport strategies — file paths, inline PEM strings, or secrets manager integration. The runtime validates PEM format and rejects malformed material with a clear error message.

Config Module Design

The mTLS subsystem exposes a TlsConfig trait with three built-in implementations:

#![allow(unused)]
fn main() {
use schemabound::identity::mtls::{TlsConfig, FileTlsConfig, InlinePemConfig};

#[async_trait]
trait TlsConfig {
    async fn load_ca_cert(&self) -> Result<Vec<u8>, MtlsError>;
    async fn load_server_cert(&self) -> Result<Vec<u8>, MtlsError>;
    async fn load_server_key(&self) -> Result<Vec<u8>, MtlsError>;
}

struct FileTlsConfig {
    ca_path: PathBuf,
    server_cert_path: PathBuf,
    server_key_path: PathBuf,
}

struct InlinePemConfig {
    ca_pem: String,
    server_cert_pem: String,
    server_key_pem: String,
}
}

This design keeps transport details out of the runtime — certificate material can come from disk files (development), inline strings in config YAML/JSON (container deployments), or any future source that implements TlsConfig.

Loading from Files

Use FileTlsConfig to point at files generated by schemabound-certgen:

#![allow(unused)]
fn main() {
use schemabound::identity::mtls::{TlsConfig, FileTlsConfig};

let config = FileTlsConfig {
    ca_path: "./certs/ca.crt".into(),
    server_cert_path: "./certs/server.crt".into(),
    server_key_path: "./certs/server.key".into(),
};
}

Dev Mode Bypass

During development, skip client certificate verification with the DevTlsConfig wrapper:

#![allow(unused)]
fn main() {
let config = DevTlsConfig::wrap(file_config)?;
}

This disables mutual TLS enforcement for the client verification step while still allowing server-side mTLS to function. Do not use in production.

Integration With gRPC

The runtime enforces mTLS via environment configuration — no code changes required. Set the following environment variables in your deployment to enable mutual TLS for all inbound and outbound connections:

The gRPC interceptor layer validates client certificates against the configured CA on every incoming connection. Outbound connections to other SCHEMABOUND services automatically present your server certificate for peer verification.

Production Checklist

• Use a dedicated CA for production (do not reuse development certificates)
• Store private keys in a secrets manager or encrypted vault
• Set certificate expiry alerts (use --days appropriately)
• Rotate client certificates on employee offboarding
• Verify all services present valid client certificates before accepting connections
• Disable SCHEMABOUND_MTLS_DEV_MODE in production deployments