implementing-tls

TLS の実装

目的

ネットワーク通信を暗号化し、サービスを認証するために Transport Layer Security（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';

セキュリティ機能

• Perfect Forward Secrecy（PFS）：一時鍵交換（ECDHE）を使用します
• OCSP Stapling：パフォーマンスとプライバシーのために有効にします
• 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（サーバーのみを認証）を使用する場合：

• パブリック Web サイト（ユーザーがサーバーを信頼する）
• ベアラートークンを使用する 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	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

証明書のライフサイクル

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 での証明書生成を自動化