implementing-tls

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing TLS

实现TLS

Purpose

目标

Implement Transport Layer Security (TLS) for encrypting network communications and authenticating services. Generate certificates, automate certificate lifecycle management with Let's Encrypt or internal CAs, configure TLS 1.3, implement mutual TLS for service authentication, and debug common certificate issues.

实现传输层安全（TLS）以加密网络通信并完成服务认证。包括生成证书、使用Let's Encrypt或内部CA自动化证书生命周期管理、配置TLS 1.3、实现用于服务认证的双向TLS（mTLS），以及调试常见证书问题。

When to Use This Skill

适用场景

Trigger this skill when:

Setting up HTTPS for web applications or APIs
Securing service-to-service communication in microservices
Implementing mutual TLS (mTLS) for zero-trust networks
Generating certificates for development or production
Automating certificate renewal and rotation
Debugging certificate validation errors
Configuring TLS termination at load balancers
Setting up internal PKI for corporate networks

在以下场景中使用本技能：

为Web应用或API搭建HTTPS
保障微服务架构中的服务间通信安全
在零信任网络中实现双向TLS（mTLS）
为开发或生产环境生成证书
自动化证书续期与轮换
调试证书验证错误
在负载均衡器上配置TLS终止
为企业网络搭建内部PKI

Quick Start

快速入门

For Development (Local HTTPS)

开发环境（本地HTTPS）

Use mkcert for trusted local certificates:

bash

undefined

使用mkcert生成受信任的本地证书：

bash

undefined

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

undefined

undefined

For Production (Public HTTPS)

生产环境（公网HTTPS）

Kubernetes with cert-manager:

bash

undefined

Kubernetes + cert-manager：

bash

undefined

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: admin@example.com privateKeySecretRef: name: letsencrypt-prod-key solvers: - http01: ingress: class: nginx EOF


**Traditional servers with Certbot:**
```bash


**传统服务器 + Certbot：**
```bash

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/

undefined

undefined

For Internal Services (Internal PKI)

内部服务（企业网络）

Generate internal CA with CFSSL:

bash

undefined

使用CFSSL生成内部CA：

bash

undefined

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


See `examples/cfssl-ca/` for complete configuration files.

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 Configuration Best Practices

TLS 1.3 配置最佳实践

Protocol Versions

协议版本

Enable TLS 1.3 and 1.2 only:

nginx

undefined

仅启用TLS 1.3和1.2：

nginx

undefined

Nginx

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


Disable obsolete protocols: SSLv3, TLS 1.0, TLS 1.1.

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


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

Cipher Suites

加密套件

TLS 1.3 (5 cipher suites):

TLS_AES_256_GCM_SHA384           # Recommended
TLS_CHACHA20_POLY1305_SHA256     # Mobile-optimized
TLS_AES_128_GCM_SHA256           # Performance

TLS 1.2 fallback:

nginx

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

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 降级方案：

nginx

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

Security Features

安全特性

Perfect Forward Secrecy (PFS): Use ephemeral key exchanges (ECDHE)
OCSP Stapling: Enable for performance and privacy
HSTS: Force HTTPS with
```
Strict-Transport-Security
```
header
Disable compression: Prevent CRIME attacks

For detailed TLS 1.3 configuration, see

references/tls13-best-practices.md

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

详细的TLS 1.3配置请查看

references/tls13-best-practices.md

。

Decision Framework

决策框架

Certificate Type Selection

证书类型选择

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

需要TLS证书？
│
├─ 面向公网（互联网用户）？
│  │
│  ├─ 单域名 → 采用HTTP-01挑战的Let's Encrypt
│  │  工具：certbot、cert-manager
│  │  验证方式：HTTP验证
│  │
│  └─ 多子域名 → 采用DNS-01挑战的Let's Encrypt
│     工具：带DNS插件的certbot、cert-manager
│     验证方式：DNS TXT记录
│     支持：通配符证书（*.example.com）
│
└─ 内部服务（企业网络）？
   │
   ├─ 开发环境 → mkcert或自签名证书
│  工具：mkcert（受信任）、openssl（基础）
│  无需自动化
│
   └─ 生产环境 → 内部CA
      │
      ├─ 小规模（<10个服务） → CFSSL
│  可接受手动管理
│
      └─ 大规模（100+服务） → Vault PKI或cert-manager
         动态密钥、自动轮换

Automation Tool Selection

自动化工具选择

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

部署环境？
│
├─ Kubernetes → cert-manager
│  原生CRDs、Ingress集成
│  支持：Let's Encrypt、Vault、CA、自签名
│
├─ 传统服务器（VM） → Certbot（公网）或CFSSL（内部）
│  插件：nginx、apache、DNS提供商
│  通过cron/systemd自动续期
│
├─ 微服务（任意平台） → HashiCorp Vault PKI
│  动态密钥、短期证书
│  API驱动、服务网格集成
│
└─ 开发工作站 → mkcert
   自动被浏览器信任

Standard TLS vs Mutual TLS (mTLS)

标准TLS vs 双向TLS（mTLS）

Use Standard TLS (server-only authentication) when:

Public websites (users trust server)
APIs with bearer tokens (separate auth layer)
Services behind API gateway
Simple architectures (<5 services)

Use Mutual TLS (both authenticate) when:

Service-to-service in microservices
High security requirements (financial, healthcare)
Machine-to-machine APIs
Zero-trust networks
No shared network trust

See

references/mtls-guide.md

for mTLS implementation patterns.

使用标准TLS（仅服务器认证）的场景：

公网站点（用户信任服务器）
使用Bearer令牌的API（独立认证层）
API网关后的服务
简单架构（<5个服务）

使用双向TLS（双向认证）的场景：

微服务间通信
高安全要求场景（金融、医疗）
机器对机器API
零信任网络
无共享网络信任

mTLS实现模式请查看

references/mtls-guide.md

。

Common Workflows

常见工作流

Generate Self-Signed Certificate

生成自签名证书

Quick generation with SANs:

bash

undefined

带SAN的快速生成：

bash

undefined

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

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"


For detailed examples including CFSSL and mkcert, see `references/certificate-generation.md` and `examples/self-signed/`.

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


包含CFSSL和mkcert的详细示例请查看`references/certificate-generation.md`和`examples/self-signed/`。

Setup Let's Encrypt Automation

搭建Let's Encrypt自动化流程

With Certbot (traditional servers):

bash

undefined

使用Certbot（传统服务器）：

bash

undefined

Standalone mode (port 80 must be free)

独立模式（80端口需空闲）

sudo certbot certonly --standalone -d example.com -d www.example.com

Webroot mode (no service interruption)

Webroot模式（无服务中断）

sudo certbot certonly --webroot -w /var/www/html -d example.com

DNS challenge (wildcard support)

DNS挑战（支持通配符）

sudo certbot certonly --manual --preferred-challenges dns
-d example.com -d "*.example.com"

Test renewal

测试续期

sudo certbot renew --dry-run


**With cert-manager (Kubernetes):**
```yaml

sudo certbot renew --dry-run


**使用cert-manager（Kubernetes）：**
```yaml

Ingress with automatic certificate

自动获取证书的Ingress

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


See `references/automation-patterns.md` for complete automation guides.

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`。

Configure Mutual TLS (mTLS)

配置双向TLS（mTLS）

Server configuration (Nginx):

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;
    }
}

Client request with certificate:

bash

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

See

references/mtls-guide.md

and

examples/mtls-nginx/

for complete mTLS implementations.

服务器配置（Nginx）：

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;
    }
}

带证书的客户端请求：

bash

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

完整mTLS实现请查看

references/mtls-guide.md

和

examples/mtls-nginx/

。

Debug TLS Issues

调试TLS问题

Test TLS connection:

bash

undefined

测试TLS连接：

bash

undefined

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

测试指定TLS版本

openssl s_client -connect example.com:443 -tls1_3

Test with client certificate (mTLS)

带客户端证书测试（mTLS）

openssl s_client -connect api.example.com:443
-cert client.crt -key client.key -CAfile ca.crt


**Examine certificate:**
```bash

openssl s_client -connect api.example.com:443
-cert client.crt -key client.key -CAfile ca.crt


**检查证书：**
```bash

View certificate details

查看证书详情

openssl x509 -in cert.pem -noout -text

Check expiration

检查过期时间

openssl x509 -in cert.pem -noout -dates

Check Subject Alternative Names

检查主题备用名称（SAN）

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

Verify certificate chain

验证证书链

openssl verify -CAfile ca.crt cert.pem


**Verify key and certificate match:**
```bash

openssl verify -CAfile ca.crt cert.pem


**验证密钥与证书匹配：**
```bash

Certificate modulus

证书模数

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

Key modulus (must match)

密钥模数（必须匹配）

openssl rsa -in key.pem -noout -modulus | md5sum


**Common errors and solutions:**

| Error | Cause | Solution |
|-------|-------|----------|
| `certificate has expired` | Certificate validity passed | Renew certificate, check system clock |
| `unable to get local issuer certificate` | CA not in trust store | Add CA cert to system trust store |
| `Hostname mismatch` | CN/SAN doesn't match hostname | Regenerate cert with correct SANs |
| `handshake failure` | TLS version/cipher mismatch | Enable TLS 1.2+, check cipher suites |
| `certificate signed by unknown authority` | Missing intermediate certs | Include full chain in server config |

See `references/debugging-tls.md` for comprehensive troubleshooting guide.

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`。

Tool Selection Guide

工具选择指南

Use Case	Environment	Recommended Tool	Alternative
Public HTTPS	Kubernetes	cert-manager	External Secrets Operator
Public HTTPS	VMs/Bare Metal	Certbot	acme.sh
Internal PKI	Any	HashiCorp Vault	CFSSL, Smallstep
mTLS (K8s)	Kubernetes	cert-manager + Istio	Linkerd, Consul
mTLS (VMs)	Traditional	Vault PKI	CFSSL
Local Dev	Workstation	mkcert	Self-signed (OpenSSL)
Debugging	Any	OpenSSL s_client	curl -v
Automation	CI/CD	CFSSL API	Vault API

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

Certificate Lifecycle

证书生命周期

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)

1. 生成
   ├─ 开发环境：mkcert、自签名（OpenSSL）
   ├─ 生产环境：Let's Encrypt、商业CA
   └─ 内部服务：CFSSL、Vault PKI

2. 部署
   ├─ Kubernetes：以Secret卷挂载
   ├─ VM：复制到/etc/ssl/或应用目录
   └─ 容器：通过Docker卷挂载

3. 监控
   ├─ 检查过期时间：openssl x509 -noout -dates
   ├─ Prometheus：blackbox_exporter（probe_ssl_earliest_cert_expiry）
   └─ 告警：过期前7天触发

4. 续期
   ├─ 自动化：certbot renew、cert-manager、Vault Agent
   ├─ 手动：生成新CSR、从CA重新签发
   └─ 时机：过期前30天续期

5. 轮换
   ├─ 零停机：加载新证书、优雅重启
   ├─ Kubernetes：更新Secret、滚动重启
   └─ 服务网格：自动轮换（Istio、Linkerd）

Certificate Formats

证书格式

PEM (most common):

Extensions: .pem, .crt, .cer, .key
Base64 encoded, ASCII text
Used by: Apache, Nginx, OpenSSL

DER (binary):

Extensions: .der, .cer
Binary format
Used by: Java, Windows

PKCS#12 / PFX (container):

Extensions: .p12, .pfx
Contains certificate + private key (password protected)
Used by: Windows, Java keystores, browsers

Convert formats:

bash

undefined

PEM（最常用）：

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

DER（二进制）：

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

PKCS#12 / PFX（容器格式）：

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

格式转换：

bash

undefined

PEM to DER

PEM转DER

openssl x509 -in cert.pem -outform DER -out cert.der

PEM to PKCS#12

PEM转PKCS#12

openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem

PKCS#12 to PEM

PKCS#12转PEM

openssl pkcs12 -in cert.p12 -out cert.pem -nodes


See `scripts/convert-formats.sh` for automated conversion.

openssl pkcs12 -in cert.p12 -out cert.pem -nodes


自动化转换脚本请查看`scripts/convert-formats.sh`。

References

参考资料

Detailed Guides

详细指南

references/certificate-generation.md - Comprehensive generation examples (OpenSSL, CFSSL, mkcert)
references/automation-patterns.md - Automation deep-dive (Certbot, cert-manager, Vault PKI)
references/mtls-guide.md - mTLS implementation patterns and architecture
references/debugging-tls.md - Troubleshooting guide with common errors and solutions
references/tls13-best-practices.md - TLS 1.3 configuration and security features

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

示例

Working Code

可用代码

examples/self-signed/ - Self-signed certificate generation scripts
examples/cfssl-ca/ - Internal CA setup with CFSSL (complete configuration)
examples/certbot/ - Let's Encrypt automation (standalone, webroot, DNS challenges)
examples/cert-manager/ - Kubernetes certificate management (ClusterIssuer, Ingress)
examples/mtls-nginx/ - Mutual TLS with Nginx (server + client configuration)
examples/vault-pki/ - Vault PKI integration and dynamic certificates

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

脚本

Utility Tools

实用工具

scripts/check-cert-expiry.sh - Monitor certificate expiration across multiple domains
scripts/validate-chain.sh - Verify certificate chain integrity
scripts/test-tls-connection.sh - Test TLS connections with various options
scripts/convert-formats.sh - Convert between PEM, DER, and PKCS#12 formats

scripts/check-cert-expiry.sh - 监控多个域名的证书过期情况
scripts/validate-chain.sh - 验证证书链完整性
scripts/test-tls-connection.sh - 多选项测试TLS连接
scripts/convert-formats.sh - PEM、DER、PKCS#12格式互转