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:
| File | Purpose |
|---|---|
ca.crt | Root CA certificate (distribute to all clients) |
ca.key | Root CA private key (keep secure, never distribute) |
server.crt | Server certificate signed by the CA |
server.key | Server private key |
client.crt | Client certificate signed by the CA |
client.key | Client private key |
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 from environment variables or files at startup. The runtime validates PEM format and rejects malformed material with a clear error message.
Environment Variables
| Variable | Purpose |
|---|---|
SCHEMABOUND_MTLS_CA_CERT | Path to CA certificate file (or inline PEM) |
SCHEMABOUND_MTLS_SERVER_CERT | Path to server certificate file |
SCHEMABOUND_MTLS_SERVER_KEY | Path to server private key file |
SCHEMABOUND_MTLS_CLIENT_CA_CERT | Path to client CA bundle for verifying client certificates |
Loading from Files
Point the environment variables at files generated by schemabound-certgen:
export SCHEMABOUND_MTLS_CA_CERT=./certs/ca.crt
export SCHEMABOUND_MTLS_SERVER_CERT=./certs/server.crt
export SCHEMABOUND_MTLS_SERVER_KEY=./certs/server.key
export SCHEMABOUND_MTLS_CLIENT_CA_CERT=./certs/ca.crt
Dev Mode Bypass
During development, skip client certificate verification with:
export SCHEMABOUND_MTLS_DEV_MODE=true
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’s gRPC interceptor automatically enforces mTLS when certificates are configured. Client certificates are verified against the CA bundle on every incoming connection. Server certificates are presented during outbound connections to other SCHEMABOUND services.
No code changes are required — certificate configuration is purely environmental:
#![allow(unused)]
fn main() {
use schemabound::grpc;
let server = grpc::build_server()
.with_mtls(ca_cert_path, server_cert_path, server_key_path)?;
server.serve().await?;
}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
--daysappropriately) - Rotate client certificates on employee offboarding
- Verify all services present valid client certificates before accepting connections
- Disable
SCHEMABOUND_MTLS_DEV_MODEin production deployments