PaperclipOrg
Claude Agent Skill · by Wshobson

Mtls Configuration

Solid reference for implementing mutual TLS across service meshes, with working configs for Istio, Linkerd, and SPIFFE/SPIRE. The debugging section actually hel

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill mtls-configuration
Works with Paperclip

How Mtls Configuration fits into a Paperclip company.

Mtls Configuration drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md342 lines
Expand
---name: mtls-configurationdescription: Configure mutual TLS (mTLS) for zero-trust service-to-service communication. Use when implementing zero-trust networking, certificate management, or securing internal service communication.--- # mTLS Configuration Comprehensive guide to implementing mutual TLS for zero-trust service mesh communication. ## When to Use This Skill - Implementing zero-trust networking- Securing service-to-service communication- Certificate rotation and management- Debugging TLS handshake issues- Compliance requirements (PCI-DSS, HIPAA)- Multi-cluster secure communication ## Core Concepts ### 1. mTLS Flow ```┌─────────┐                              ┌─────────┐│ Service │                              │ Service ││    A    │                              │    B    │└────┬────┘                              └────┬────┘     │                                        │┌────┴────┐      TLS Handshake          ┌────┴────┐│  Proxy  │◄───────────────────────────►│  Proxy  ││(Sidecar)│  1. ClientHello             │(Sidecar)││         │  2. ServerHello + Cert      │         ││         │  3. Client Cert             │         ││         │  4. Verify Both Certs       │         ││         │  5. Encrypted Channel       │         │└─────────┘                              └─────────┘``` ### 2. Certificate Hierarchy ```Root CA (Self-signed, long-lived)    │    ├── Intermediate CA (Cluster-level)    │       │    │       ├── Workload Cert (Service A)    │       └── Workload Cert (Service B)    │    └── Intermediate CA (Multi-cluster)            │            └── Cross-cluster certs``` ## Templates ### Template 1: Istio mTLS (Strict Mode) ```yaml# Enable strict mTLS mesh-wideapiVersion: security.istio.io/v1beta1kind: PeerAuthenticationmetadata:  name: default  namespace: istio-systemspec:  mtls:    mode: STRICT---# Namespace-level override (permissive for migration)apiVersion: security.istio.io/v1beta1kind: PeerAuthenticationmetadata:  name: default  namespace: legacy-namespacespec:  mtls:    mode: PERMISSIVE---# Workload-specific policyapiVersion: security.istio.io/v1beta1kind: PeerAuthenticationmetadata:  name: payment-service  namespace: productionspec:  selector:    matchLabels:      app: payment-service  mtls:    mode: STRICT  portLevelMtls:    8080:      mode: STRICT    9090:      mode: DISABLE # Metrics port, no mTLS``` ### Template 2: Istio Destination Rule for mTLS ```yamlapiVersion: networking.istio.io/v1beta1kind: DestinationRulemetadata:  name: default  namespace: istio-systemspec:  host: "*.local"  trafficPolicy:    tls:      mode: ISTIO_MUTUAL---# TLS to external serviceapiVersion: networking.istio.io/v1beta1kind: DestinationRulemetadata:  name: external-apispec:  host: api.external.com  trafficPolicy:    tls:      mode: SIMPLE      caCertificates: /etc/certs/external-ca.pem---# Mutual TLS to external serviceapiVersion: networking.istio.io/v1beta1kind: DestinationRulemetadata:  name: partner-apispec:  host: api.partner.com  trafficPolicy:    tls:      mode: MUTUAL      clientCertificate: /etc/certs/client.pem      privateKey: /etc/certs/client-key.pem      caCertificates: /etc/certs/partner-ca.pem``` ### Template 3: Cert-Manager with Istio ```yaml# Install cert-manager issuer for IstioapiVersion: cert-manager.io/v1kind: ClusterIssuermetadata:  name: istio-caspec:  ca:    secretName: istio-ca-secret---# Create Istio CA secretapiVersion: v1kind: Secretmetadata:  name: istio-ca-secret  namespace: cert-managertype: kubernetes.io/tlsdata:  tls.crt: <base64-encoded-ca-cert>  tls.key: <base64-encoded-ca-key>---# Certificate for workloadapiVersion: cert-manager.io/v1kind: Certificatemetadata:  name: my-service-cert  namespace: my-namespacespec:  secretName: my-service-tls  duration: 24h  renewBefore: 8h  issuerRef:    name: istio-ca    kind: ClusterIssuer  commonName: my-service.my-namespace.svc.cluster.local  dnsNames:    - my-service    - my-service.my-namespace    - my-service.my-namespace.svc    - my-service.my-namespace.svc.cluster.local  usages:    - server auth    - client auth``` ### Template 4: SPIFFE/SPIRE Integration ```yaml# SPIRE Server configurationapiVersion: v1kind: ConfigMapmetadata:  name: spire-server  namespace: spiredata:  server.conf: |    server {      bind_address = "0.0.0.0"      bind_port = "8081"      trust_domain = "example.org"      data_dir = "/run/spire/data"      log_level = "INFO"      ca_ttl = "168h"      default_x509_svid_ttl = "1h"    }     plugins {      DataStore "sql" {        plugin_data {          database_type = "sqlite3"          connection_string = "/run/spire/data/datastore.sqlite3"        }      }       NodeAttestor "k8s_psat" {        plugin_data {          clusters = {            "demo-cluster" = {              service_account_allow_list = ["spire:spire-agent"]            }          }        }      }       KeyManager "memory" {        plugin_data {}      }       UpstreamAuthority "disk" {        plugin_data {          key_file_path = "/run/spire/secrets/bootstrap.key"          cert_file_path = "/run/spire/secrets/bootstrap.crt"        }      }    }---# SPIRE Agent DaemonSet (abbreviated)apiVersion: apps/v1kind: DaemonSetmetadata:  name: spire-agent  namespace: spirespec:  selector:    matchLabels:      app: spire-agent  template:    spec:      containers:        - name: spire-agent          image: ghcr.io/spiffe/spire-agent:1.8.0          volumeMounts:            - name: spire-agent-socket              mountPath: /run/spire/sockets      volumes:        - name: spire-agent-socket          hostPath:            path: /run/spire/sockets            type: DirectoryOrCreate``` ### Template 5: Linkerd mTLS (Automatic) ```yaml# Linkerd enables mTLS automatically# Verify with:# linkerd viz edges deployment -n my-namespace # For external services without mTLSapiVersion: policy.linkerd.io/v1beta1kind: Servermetadata:  name: external-api  namespace: my-namespacespec:  podSelector:    matchLabels:      app: my-app  port: external-api  proxyProtocol: HTTP/1 # or TLS for passthrough---# Skip TLS for specific portapiVersion: v1kind: Servicemetadata:  name: my-service  annotations:    config.linkerd.io/skip-outbound-ports: "3306" # MySQL``` ## Certificate Rotation ```bash# Istio - Check certificate expiryistioctl proxy-config secret deploy/my-app -o json | \  jq '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | \  tr -d '"' | base64 -d | openssl x509 -text -noout # Force certificate rotationkubectl rollout restart deployment/my-app # Check Linkerd identitylinkerd identity -n my-namespace``` ## Debugging mTLS Issues ```bash# Istio - Check if mTLS is enabledistioctl authn tls-check my-service.my-namespace.svc.cluster.local # Verify peer authenticationkubectl get peerauthentication --all-namespaces # Check destination ruleskubectl get destinationrule --all-namespaces # Debug TLS handshakeistioctl proxy-config log deploy/my-app --level debugkubectl logs deploy/my-app -c istio-proxy | grep -i tls # Linkerd - Check mTLS statuslinkerd viz edges deployment -n my-namespacelinkerd viz tap deploy/my-app --to deploy/my-backend``` ## Best Practices ### Do's - **Start with PERMISSIVE** - Migrate gradually to STRICT- **Monitor certificate expiry** - Set up alerts- **Use short-lived certs** - 24h or less for workloads- **Rotate CA periodically** - Plan for CA rotation- **Log TLS errors** - For debugging and audit ### Don'ts - **Don't disable mTLS** - For convenience in production- **Don't ignore cert expiry** - Automate rotation- **Don't use self-signed certs** - Use proper CA hierarchy- **Don't skip verification** - Verify the full chain