pki Module

Certificate Authority and TLS certificate generation.

Import

from fscm.modules import pki

Requirements

pip install "fscm[pki]"

This installs the cryptography package.

Functions

create_ca

Create a Certificate Authority.

from fscm.modules import pki

pki.create_ca(
    ca_dir="/etc/myapp/ca",
    common_name="My App CA",
    organization="My Organization",
    validity_days=3650  # 10 years
)

Creates: - ca.key — CA private key - ca.crt — CA certificate

Parameters:

Name	Type	Default	Description
ca_dir	str	required	Directory to store CA files
common_name	str	required	CA common name
organization	str	None	Organization name
country	str	None	Country code (e.g., "US")
state	str	None	State/province
locality	str	None	City
validity_days	int	3650	Certificate validity
key_size	int	4096	RSA key size

---

create_cert_for_service

Create a certificate signed by the CA.

from fscm.modules import pki

pki.create_cert_for_service(
    ca_dir="/etc/myapp/ca",
    cert_dir="/etc/myapp/certs",
    common_name="api.example.com",
    san_dns=["api.example.com", "api"],
    san_ip=["10.0.0.5"],
    validity_days=365
)

Creates: - api.example.com.key — Service private key - api.example.com.crt — Service certificate

Parameters:

Name	Type	Default	Description
ca_dir	str	required	CA directory
cert_dir	str	required	Output directory
common_name	str	required	Certificate CN
san_dns	list	None	DNS Subject Alternative Names
san_ip	list	None	IP Subject Alternative Names
validity_days	int	365	Certificate validity
key_size	int	2048	RSA key size

Examples

Internal PKI Setup

#!/usr/bin/env python3
"""Set up internal PKI for microservices."""

import fscm
from fscm.modules import pki

CA_DIR = "/etc/pki/ca"
CERTS_DIR = "/etc/pki/certs"

def setup_pki():
    # Create directories
    fscm.mkdir(CA_DIR, mode="0700")
    fscm.mkdir(CERTS_DIR, mode="0755")

    # Create CA
    pki.create_ca(
        ca_dir=CA_DIR,
        common_name="Internal CA",
        organization="My Company",
        validity_days=3650
    )

    # Create service certificates
    services = [
        {
            "name": "api",
            "dns": ["api.internal", "api"],
            "ip": ["10.0.0.10"]
        },
        {
            "name": "database",
            "dns": ["db.internal", "postgres"],
            "ip": ["10.0.0.20"]
        },
        {
            "name": "cache",
            "dns": ["cache.internal", "redis"],
            "ip": ["10.0.0.30"]
        }
    ]

    for svc in services:
        pki.create_cert_for_service(
            ca_dir=CA_DIR,
            cert_dir=CERTS_DIR,
            common_name=f"{svc['name']}.internal",
            san_dns=svc["dns"],
            san_ip=svc["ip"],
            validity_days=365
        )
        print(f"Created certificate for {svc['name']}")

    # Set permissions
    fscm.chmod(f"{CERTS_DIR}/*.key", "0600")
    fscm.chmod(f"{CERTS_DIR}/*.crt", "0644")

if __name__ == "__main__":
    setup_pki()

mTLS Configuration

import fscm
from fscm.modules import pki

def setup_mtls_service(service_name: str, service_ip: str):
    """Set up mutual TLS for a service."""
    CA_DIR = "/etc/pki/ca"
    CERT_DIR = f"/etc/{service_name}/tls"

    # Create cert directory
    fscm.mkdir(CERT_DIR, mode="0750", owner=f"{service_name}:ssl-cert")

    # Generate certificate
    pki.create_cert_for_service(
        ca_dir=CA_DIR,
        cert_dir=CERT_DIR,
        common_name=f"{service_name}.internal",
        san_dns=[f"{service_name}.internal", service_name],
        san_ip=[service_ip]
    )

    # Copy CA cert for verification
    fscm.run(f"cp {CA_DIR}/ca.crt {CERT_DIR}/ca.crt")

    # Set ownership
    fscm.chown(CERT_DIR, f"{service_name}:ssl-cert", flags="-R")

    print(f"""
mTLS configured for {service_name}:
  Certificate: {CERT_DIR}/{service_name}.internal.crt
  Key:         {CERT_DIR}/{service_name}.internal.key
  CA:          {CERT_DIR}/ca.crt
""")

# Usage
setup_mtls_service("api", "10.0.0.10")

Certificate for Nginx

import fscm
from fscm.modules import pki

def setup_nginx_ssl(domain: str):
    """Set up SSL certificate for nginx."""
    CA_DIR = "/etc/pki/ca"

    # Generate certificate
    pki.create_cert_for_service(
        ca_dir=CA_DIR,
        cert_dir="/etc/nginx/ssl",
        common_name=domain,
        san_dns=[domain, f"www.{domain}"],
        validity_days=365
    )

    # Nginx SSL config
    ssl_config = f"""
ssl_certificate /etc/nginx/ssl/{domain}.crt;
ssl_certificate_key /etc/nginx/ssl/{domain}.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;
"""
    fscm.file(f"/etc/nginx/snippets/ssl-{domain}.conf", ssl_config)

    print(f"Include in nginx: include snippets/ssl-{domain}.conf;")

setup_nginx_ssl("example.com")

CLI Tool

fscm includes a CLI for PKI operations:

# Create CA
fscm-pki create-ca --dir /etc/pki/ca --cn "My CA"

# Create certificate
fscm-pki create-cert \
  --ca-dir /etc/pki/ca \
  --out-dir /etc/pki/certs \
  --cn api.example.com \
  --san-dns api.example.com \
  --san-ip 10.0.0.5

Security Notes

1. Protect the CA key — Store in secure location with 0600 permissions
2. Short-lived certificates — Prefer 1 year or less validity
3. Separate CA — Use dedicated CA for internal services
4. Key rotation — Plan for certificate renewal before expiry
5. HSM support — For production, consider hardware security modules