implementing-tls

实施 TLS

目的

实施传输层安全协议（TLS），以加密网络通信并验证服务身份。生成证书，使用 Let's Encrypt 或内部 CA 自动管理证书生命周期，配置 TLS 1.3，为服务身份验证实施双向 TLS，并排查常见证书问题。

何时使用此技能

在以下情况下使用此技能：

• 为 Web 应用或 API 设置 HTTPS
• 保护微服务中的服务间通信
• 为零信任网络实施双向 TLS（mTLS）
• 为开发或生产环境生成证书
• 自动续期和轮换证书
• 排查证书验证错误
• 配置负载均衡器上的 TLS 终止
• 为企业网络设置内部 PKI

快速入门

开发环境（本地 HTTPS）

使用 mkcert 获取受信任的本地证书：

# Install mkcert
brew install mkcert  # macOS
# sudo apt install mkcert  # Linux

# Install local CA
mkcert -install

# Generate certificate
mkcert example.com localhost 127.0.0.1
# Creates: example.com+2.pem and example.com+2-key.pem

生产环境（公共 HTTPS）

使用 cert-manager 的 Kubernetes：

# Install cert-manager
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager --create-namespace \
  --set installCRDs=true

# Create Let's Encrypt issuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

使用 Certbot 的传统服务器：

# Install certbot
sudo apt install certbot

# Obtain certificate
sudo certbot certonly --standalone -d example.com -d www.example.com
# Certificates saved to /etc/letsencrypt/live/example.com/

内部服务（内部 PKI）

使用 CFSSL 生成内部 CA：

# Install CFSSL
brew install cfssl  # macOS

# Create CA
cfssl genkey -initca ca-csr.json | cfssljson -bare ca

# Generate server certificate
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem \
  -config=ca-config.json -profile=server \
  server-csr.json | cfssljson -bare server

完整配置文件请参阅 examples/cfssl-ca/。

TLS 1.3 配置最佳实践

协议版本

仅启用 TLS 1.3 和 1.2：

# Nginx
ssl_protocols TLSv1.3 TLSv1.2;
ssl_prefer_server_ciphers off;  # Let client choose

禁用过时的协议：SSLv3、TLS 1.0、TLS 1.1。

加密套件

TLS 1.3（5 种加密套件）：

TLS_AES_256_GCM_SHA384           # Recommended
TLS_CHACHA20_POLY1305_SHA256     # Mobile-optimized
TLS_AES_128_GCM_SHA256           # Performance

TLS 1.2 回退配置：

ssl_ciphers 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-CHACHA20-POLY1305';

安全功能

• 前向保密（PFS）：使用临时密钥交换（ECDHE）
• OCSP 装订：启用以提升性能和隐私保护
• HSTS：通过 Strict-Transport-Security 标头强制使用 HTTPS
• 禁用压缩：防止 CRIME 攻击

TLS 1.3 配置详情请参阅 references/tls13-best-practices.md。

决策框架

证书类型选择

Need TLS certificate?
│
├─ Public-facing (internet users)?
│  │
│  ├─ Single domain → Let's Encrypt with HTTP-01
│  │  Tools: certbot, cert-manager
│  │  Challenge: HTTP verification
│  │
│  └─ Multiple subdomains → Let's Encrypt with DNS-01
│     Tools: certbot with DNS plugin, cert-manager
│     Challenge: DNS TXT records
│     Supports: Wildcard certificates (*.example.com)
│
└─ Internal (corporate network)?
   │
   ├─ Development → mkcert or self-signed
   │  Tools: mkcert (trusted), openssl (basic)
   │  No automation needed
   │
   └─ Production → Internal CA
      │
      ├─ Small scale (<10 services) → CFSSL
      │  Manual management acceptable
      │
      └─ Large scale (100+ services) → Vault PKI or cert-manager
         Dynamic secrets, automatic rotation

自动化工具选择

Environment?
│
├─ Kubernetes → cert-manager
│  Native CRDs, Ingress integration
│  Supports: Let's Encrypt, Vault, CA, self-signed
│
├─ Traditional servers (VMs) → Certbot (public) or CFSSL (internal)
│  Plugins: nginx, apache, DNS providers
│  Automated renewal via cron/systemd
│
├─ Microservices (any platform) → HashiCorp Vault PKI
│  Dynamic secrets, short-lived certs
│  API-driven, service mesh integration
│
└─ Developer workstation → mkcert
   Trusted by browser automatically

标准 TLS 与双向 TLS（mTLS）

在以下情况下使用标准 TLS（仅验证服务端）：

• 公共网站（用户信任服务端）
• 使用承载令牌的 API（通过独立的身份验证层处理）
• 位于 API 网关之后的服务
• 简单的架构（少于 5 个服务）

在以下情况下使用双向 TLS（双方均进行身份验证）：

• 微服务中的服务间通信
• 安全要求较高的场景（金融、医疗保健）
• 机器间 API
• 零信任网络
• 不存在共享的网络信任

mTLS 实施模式请参阅 references/mtls-guide.md。

常见工作流

生成自签名证书

快速生成包含 SAN 的证书：

# Create OpenSSL config
cat > san.cnf <<EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = v3_req

[dn]
CN = example.com

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = example.com
DNS.2 = www.example.com
DNS.3 = api.example.com
IP.1 = 192.168.1.100
EOF

# Generate key and certificate
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout server-key.pem -out server-cert.pem \
  -days 365 -config san.cnf -extensions v3_req

# Verify SANs
openssl x509 -in server-cert.pem -noout -text | grep -A 3 "Subject Alternative Name"

包含 CFSSL 和 mkcert 的详细示例，请参阅 references/certificate-generation.md 和 examples/self-signed/。

设置 Let's Encrypt 自动化

使用 Certbot（传统服务器）：

# Standalone mode (port 80 must be free)
sudo certbot certonly --standalone -d example.com -d www.example.com

# Webroot mode (no service interruption)
sudo certbot certonly --webroot -w /var/www/html -d example.com

# DNS challenge (wildcard support)
sudo certbot certonly --manual --preferred-challenges dns \
  -d example.com -d "*.example.com"

# Test renewal
sudo certbot renew --dry-run

使用 cert-manager（Kubernetes）：

# Ingress with automatic certificate
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - example.com
    secretName: example-com-tls
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

完整的自动化指南请参阅 references/automation-patterns.md。

配置双向 TLS（mTLS）

服务端配置（Nginx）：

server {
    listen 443 ssl;
    server_name api.example.com;

    # Server certificate
    ssl_certificate /etc/ssl/certs/server.crt;
    ssl_certificate_key /etc/ssl/private/server.key;

    # CA to verify client certificates
    ssl_client_certificate /etc/ssl/certs/ca.crt;
    ssl_verify_client on;
    ssl_verify_depth 2;

    # TLS 1.3
    ssl_protocols TLSv1.3;

    location / {
        proxy_pass http://backend;
        # Pass client cert info to backend
        proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
        proxy_set_header X-SSL-Client-S-DN $ssl_client_s_dn;
    }
}

使用证书发送客户端请求：

curl https://api.example.com/endpoint \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt

完整的 mTLS 实施示例请参阅 references/mtls-guide.md 和 examples/mtls-nginx/。

排查 TLS 问题

测试 TLS 连接：

# Basic connection test
openssl s_client -connect example.com:443

# Show certificate chain
openssl s_client -connect example.com:443 -showcerts

# Test specific TLS version
openssl s_client -connect example.com:443 -tls1_3

# Test with client certificate (mTLS)
openssl s_client -connect api.example.com:443 \
  -cert client.crt -key client.key -CAfile ca.crt

检查证书：

# View certificate details
openssl x509 -in cert.pem -noout -text

# Check expiration
openssl x509 -in cert.pem -noout -dates

# Check Subject Alternative Names
openssl x509 -in cert.pem -noout -text | grep -A 1 "Subject Alternative Name"

# Verify certificate chain
openssl verify -CAfile ca.crt cert.pem

验证密钥与证书是否匹配：

# Certificate modulus
openssl x509 -in cert.pem -noout -modulus | md5sum

# Key modulus (must match)
openssl rsa -in key.pem -noout -modulus | md5sum

常见错误及解决方案：

错误	原因	解决方案
certificate has expired	证书已过有效期	续期证书，检查系统时钟
unable to get local issuer certificate	CA 不在信任存储中	将 CA 证书添加到系统信任存储
Hostname mismatch	CN/SAN 与主机名不匹配	使用正确的 SAN 重新生成证书
handshake failure	TLS 版本或加密套件不匹配	启用 TLS 1.2 及以上版本，检查加密套件
certificate signed by unknown authority	缺少中间证书	在服务端配置中包含完整证书链

全面的故障排查指南请参阅 references/debugging-tls.md。

工具选择指南

用例	环境	推荐工具	替代方案
公共 HTTPS	Kubernetes	cert-manager	External Secrets Operator
公共 HTTPS	虚拟机/裸金属	Certbot	acme.sh
内部 PKI	任意	HashiCorp Vault	CFSSL、Smallstep
mTLS（K8s）	Kubernetes	cert-manager + Istio	Linkerd、Consul
mTLS（虚拟机）	传统环境	Vault PKI	CFSSL
本地开发	工作站	mkcert	自签名（OpenSSL）
调试	任意	OpenSSL s_client	curl -v
自动化	CI/CD	CFSSL API	Vault API

证书生命周期

1. Generate
   ├─ Development: mkcert, self-signed (OpenSSL)
   ├─ Production: Let's Encrypt, commercial CA
   └─ Internal: CFSSL, Vault PKI

2. Deploy
   ├─ Kubernetes: Mount as Secret volume
   ├─ VMs: Copy to /etc/ssl/ or application directory
   └─ Containers: Mount via Docker volumes

3. Monitor
   ├─ Check expiry: openssl x509 -noout -dates
   ├─ Prometheus: blackbox_exporter (probe_ssl_earliest_cert_expiry)
   └─ Alert: < 7 days before expiry

4. Renew
   ├─ Automated: certbot renew, cert-manager, Vault Agent
   ├─ Manual: Generate new CSR, reissue from CA
   └─ Timing: Renew 30 days before expiry

5. Rotate
   ├─ Zero-downtime: Load new cert, graceful reload
   ├─ Kubernetes: Update Secret, rolling restart
   └─ Service mesh: Automatic rotation (Istio, Linkerd)

证书格式

PEM（最常见）：

• 扩展名：.pem、.crt、.cer、.key
• Base64 编码的 ASCII 文本
• 用于：Apache、Nginx、OpenSSL

DER（二进制）：

• 扩展名：.der、.cer
• 二进制格式
• 用于：Java、Windows

PKCS#12 / PFX（容器）：

• 扩展名：.p12、.pfx
• 包含证书 + 私钥（受密码保护）
• 用于：Windows、Java 密钥库、浏览器

转换格式：

# PEM to DER
openssl x509 -in cert.pem -outform DER -out cert.der

# PEM to PKCS#12
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem

# PKCS#12 to PEM
openssl pkcs12 -in cert.p12 -out cert.pem -nodes

自动转换请参阅 scripts/convert-formats.sh。

参考资料

详细指南

• references/certificate-generation.md - 全面的生成示例（OpenSSL、CFSSL、mkcert）
• references/automation-patterns.md - 自动化深入指南（Certbot、cert-manager、Vault PKI）
• references/mtls-guide.md - mTLS 实现模式与架构
• references/debugging-tls.md - 故障排除指南，涵盖常见错误及解决方案
• references/tls13-best-practices.md - TLS 1.3 配置与安全功能

示例

可运行代码

• examples/self-signed/ - 自签名证书生成脚本
• examples/cfssl-ca/ - 使用 CFSSL 配置内部 CA（完整配置）
• examples/certbot/ - Let's Encrypt 自动化（独立模式、webroot、DNS 验证）
• examples/cert-manager/ - Kubernetes 证书管理（ClusterIssuer、Ingress）
• examples/mtls-nginx/ - 使用 Nginx 实现双向 TLS（服务端 + 客户端配置）
• examples/vault-pki/ - Vault PKI 集成与动态证书

脚本

实用工具

• scripts/check-cert-expiry.sh - 监控多个域名的证书到期时间
• scripts/validate-chain.sh - 验证证书链完整性
• scripts/test-tls-connection.sh - 使用各种选项测试 TLS 连接
• scripts/convert-formats.sh - 在 PEM、DER 和 PKCS#12 格式之间转换

相关技能

安全与身份验证：

• secret-management - 安全存储私钥（Vault、Kubernetes Secrets、HSM）
• auth-security - 应用级身份验证（OAuth、OIDC、JWT）
• security-hardening - 系统安全配置
• security-architecture - 全面的安全设计与威胁建模

基础设施：

• kubernetes-operations - Kubernetes 集群 TLS 配置
• load-balancing-patterns - 在负载均衡器处终止 TLS
• network-architecture - 网络安全设计

运维：

• deploying-applications - 在运行时注入证书
• observability - 监控证书健康状态与到期时间
• building-ci-pipelines - 在 CI/CD 中自动生成证书