guides_tls_setup

---

category: "⚙️ Operations/Admin" version: "v1.3.0" status: "✅" date: "22.12.2025"

⚙️ TLS/SSL Setup Guide for ThemisDB

Complete guide to configuring TLS and mutual TLS for secure communication.

📋 Inhaltsverzeichnis

• 📋 Übersicht
• ✨ Features
• 🚀 Quick Start
• 📖 Certificate Generation
• 💡 Best Practices
• 🔧 Troubleshooting
• 📚 Weitere Ressourcen
• 📝 Changelog

---

📋 Übersicht

ThemisDB supports both HTTP and HTTPS modes with optional mutual TLS (mTLS) for enhanced security. This guide covers certificate generation, configuration, and testing.

Stand: 22. Dezember 2025
Version: 1.3.0
Kategorie: ⚙️ Operations/Admin

---

✨ Features

• 🔒 TLS 1.3 Support - Modern protocol with perfect forward secrecy
• 🔐 Mutual TLS (mTLS) - Client certificate verification
• 🛡️ Strong Ciphers - ECDHE-RSA-AES256-GCM-SHA384 and more
• 📋 Security Headers - HSTS, X-Frame-Options, CSP
• ✅ Certificate Chain Validation - Full chain verification

---

🚀 Quick Start

---

Overview

ThemisDB supports both HTTP and HTTPS modes with optional mutual TLS (mTLS) for enhanced security. This guide covers certificate generation, configuration, and testing.

Security Features

Transport Layer Security (TLS)

• TLS 1.3 Support: Modern, secure protocol with perfect forward secrecy
• TLS 1.2 Fallback: Configurable for compatibility with legacy clients
• Strong Cipher Suites: ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ChaCha20-Poly1305
• Disabled Weak Protocols: SSLv2, SSLv3, TLSv1.0, TLSv1.1 explicitly disabled

Mutual TLS (mTLS)

• Client Certificate Verification: Enforce client authentication with X.509 certificates
• Certificate Chain Validation: Verify certificates against trusted CA bundle
• Client Identity Logging: Extract and log client certificate DN for audit trails

HTTP Security Headers

• HSTS (Strict-Transport-Security): Forces HTTPS for 1 year with subdomain inclusion
• X-Frame-Options: Prevents clickjacking attacks (DENY)
• X-Content-Type-Options: Prevents MIME type sniffing (nosniff)
• Content-Security-Policy: Restricts content sources (default-src 'self')

---

Certificate Generation

Using the Test Certificate Script

For development and testing only, use the provided script to generate self-signed certificates:

# Generate certificates in default location (config/certs)
./scripts/generate_test_certs.sh

# Generate certificates in custom location
./scripts/generate_test_certs.sh /path/to/certs

This script generates:

• CA certificate and key (ca.crt, ca.key) - Root authority for signing
• Server certificate and key (server.crt, server.key) - For HTTPS endpoint
• Client certificate and key (client.crt, client.key) - For mTLS authentication
• Full chain files (server-fullchain.pem, client-bundle.pem) - Combined PEM formats

Production Certificates

For production environments, obtain certificates from a trusted Certificate Authority (CA):

1. Internal CA (e.g., Active Directory Certificate Services, HashiCorp Vault)
2. Public CA (e.g., Let's Encrypt, DigiCert, GlobalSign)
3. Enterprise PKI (integrate with existing organizational PKI infrastructure)

Let's Encrypt Example

# Install certbot
sudo apt-get install certbot

# Obtain certificate (HTTP-01 challenge)
sudo certbot certonly --standalone -d themisdb.example.com

# Certificates will be in /etc/letsencrypt/live/themisdb.example.com/
# - fullchain.pem (server certificate + intermediate CA)
# - privkey.pem (private key)

---

Configuration

Environment Variables

ThemisDB TLS configuration is controlled via environment variables:

Basic TLS (One-Way Authentication)

# Enable HTTPS
export THEMIS_TLS_ENABLED=1

# Server certificate (PEM format)
export THEMIS_TLS_CERT=/path/to/server.crt

# Server private key (PEM format)
export THEMIS_TLS_KEY=/path/to/server.key

# Minimum TLS version (TLSv1.2 or TLSv1.3, default: TLSv1.3)
export THEMIS_TLS_MIN_VERSION=TLSv1.3

# Optional: Custom cipher list (OpenSSL format)
# export THEMIS_TLS_CIPHER_LIST="ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256"

Mutual TLS (Two-Way Authentication)

# Enable HTTPS with mTLS
export THEMIS_TLS_ENABLED=1
export THEMIS_TLS_CERT=/path/to/server.crt
export THEMIS_TLS_KEY=/path/to/server.key

# CA certificate for client verification
export THEMIS_TLS_CA_CERT=/path/to/ca.crt

# Require client certificate (enforce mTLS)
export THEMIS_TLS_REQUIRE_CLIENT_CERT=1

Code Configuration (C++ API)

#include "server/http_server.h"

themis::server::HttpServer::Config config;
config.host = "0.0.0.0";
config.port = 8443; // Standard HTTPS port

// Enable TLS
config.enable_tls = true;
config.tls_cert_path = "/path/to/server.crt";
config.tls_key_path = "/path/to/server.key";
config.tls_min_version = "TLSv1.3";

// Enable mTLS
config.tls_ca_cert_path = "/path/to/ca.crt";
config.tls_require_client_cert = true;

auto server = std::make_unique<themis::server::HttpServer>(
    config, storage, secondary_index, graph_index, vector_index, tx_manager
);

---

Testing

Test HTTPS Connection (One-Way TLS)

# Health check with CA verification
curl --cacert config/certs/ca.crt https://localhost:8443/health

# Skip verification (development only)
curl -k https://localhost:8443/health

# Test with verbose output
curl -v --cacert config/certs/ca.crt https://localhost:8443/metrics

Test mTLS Connection (Mutual TLS)

# Authenticate with client certificate
curl --cacert config/certs/ca.crt \
     --cert config/certs/client.crt \
     --key config/certs/client.key \
     https://localhost:8443/health

# Test authenticated API endpoint
curl --cacert config/certs/ca.crt \
     --cert config/certs/client.crt \
     --key config/certs/client.key \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://localhost:8443/api/entities/test-key

Verify Certificate Details

# Inspect server certificate
openssl x509 -in config/certs/server.crt -text -noout

# Check certificate chain
openssl verify -CAfile config/certs/ca.crt config/certs/server.crt

# Test TLS handshake
openssl s_client -connect localhost:8443 -CAfile config/certs/ca.crt

# Test mTLS handshake with client cert
openssl s_client -connect localhost:8443 \
    -CAfile config/certs/ca.crt \
    -cert config/certs/client.crt \
    -key config/certs/client.key

---

Security Best Practices

Certificate Management

1. Private Key Protection: Store private keys with restricted permissions (chmod 600)
2. Certificate Rotation: Implement automated certificate renewal (e.g., Let's Encrypt auto-renewal)
3. Certificate Revocation: Monitor CRL/OCSP for revoked certificates (future enhancement)
4. Key Separation: Never reuse private keys across environments (dev/staging/prod)

Cipher Suite Selection

Default strong ciphers (automatically configured):

• ECDHE-RSA-AES256-GCM-SHA384 - Perfect Forward Secrecy (PFS) with AES-256
• ECDHE-RSA-AES128-GCM-SHA256 - PFS with AES-128 (performance/security balance)
• ECDHE-RSA-CHACHA20-POLY1305 - PFS with ChaCha20 (mobile/IoT devices)

Avoid weak ciphers (automatically disabled):

• RC4, MD5, 3DES, DES, EXPORT ciphers
• Anonymous DH (aDH), NULL encryption

TLS Version Policy

• Recommended: TLS 1.3 only (modern clients, highest security)
• Compatible: TLS 1.2+ (legacy client support, still secure)
• Prohibited: TLS 1.1, TLS 1.0, SSLv3, SSLv2 (deprecated, known vulnerabilities)

mTLS Use Cases

Enable mutual TLS for:

• Service-to-Service Communication (microservices authentication)
• High-Security APIs (financial, healthcare, government sectors)
• Zero-Trust Networks (verify every client connection)
• Compliance Requirements (PCI-DSS, HIPAA, GDPR)

---

Troubleshooting

Common Errors

1. TLS initialization failed: No such file or directory

Cause: Certificate or key file path is incorrect.
Solution: Verify paths with ls -l $THEMIS_TLS_CERT and ensure files are readable.

2. TLS handshake error: certificate verify failed

Cause: Client cannot verify server certificate (CA not trusted).
Solution: Add --cacert with CA certificate or install CA in system trust store.

3. mTLS: no client certificate presented despite requirement

Cause: Client did not provide certificate in mTLS mode.
Solution: Ensure client uses --cert and --key flags, or disable mTLS requirement.

4. SSL shutdown error: stream truncated

Cause: Client closed connection abruptly (normal during testing).
Solution: Non-critical, can be ignored in development.

Debug TLS Issues

# Enable OpenSSL debug logging
export SSLKEYLOGFILE=/tmp/sslkeys.log
curl --cacert config/certs/ca.crt https://localhost:8443/health

# Analyze TLS handshake with tcpdump
sudo tcpdump -i lo -w /tmp/tls.pcap port 8443
# Open /tmp/tls.pcap in Wireshark with SSLKEYLOGFILE for decryption

# Check server logs for TLS details
tail -f data/logs/themis.log | grep -i "tls\|ssl\|handshake"

---

Future Enhancements

Planned TLS/PKI features:

• OCSP Stapling (RFC 6066) for certificate revocation checking
• Certificate Pinning for HSM/TSA outbound connections
• Automated Let's Encrypt integration with ACME protocol
• Hardware Security Module (HSM) integration for private key storage
• Certificate Transparency (CT) log monitoring
• TLS session resumption (session IDs, session tickets)

---

References

• RFC 8446: TLS 1.3
• Mozilla SSL Configuration Generator
• OWASP TLS Cheat Sheet
• Qualys SSL Labs Server Test
• NIST SP 800-52 Rev. 2: TLS Guidelines

---

Support

For issues or questions:

• Security Issues: Report to service@themisdb.org (do not open public issues)
• General Help: GitHub Issues or Discussions
• Documentation: https://docs.themisdb.io/security/tls