2nd/10_Wiki/Topics/Coding/Security_mTLS_Patterns.md

---
id: security-mtls-patterns
title: mTLS — 양방향 인증서 / 서비스 간 신뢰
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [security, mtls, tls, vibe-coding]
tech_stack: { language: "TS / Node / nginx / Envoy", applicable_to: ["Backend", "DevOps"] }
applied_in: []
aliases: [mutual TLS, client cert, mTLS, service mesh, SPIFFE, cert rotation]
---

# mTLS

> 일반 TLS = 서버만 인증서. **mTLS = 클라이언트도 인증서**. 서비스 간 신뢰 / Zero-trust 네트워크. 운영 부담 = 인증서 회전. **Service mesh (Istio / Linkerd)** 가 자동.

## 📖 핵심 개념
- 클라가 서버 cert 검증 + 서버가 클라 cert 검증.
- Private CA 가 양쪽 발급.
- SPIFFE: cloud-native identity 표준 (URI = spiffe://trust-domain/svc/...).
- Mesh: sidecar proxy 가 mTLS 자동 처리.

## 💻 코드 패턴

### CA + cert 생성 (수동)
```bash
# CA
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -days 3650 -out ca.crt -subj "/CN=My CA"

# Server cert
openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr -subj "/CN=api.local"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt -days 365

# Client cert (서비스 A 용)
openssl genrsa -out client-a.key 4096
openssl req -new -key client-a.key -out client-a.csr -subj "/CN=service-a"
openssl x509 -req -in client-a.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client-a.crt -days 365
```

### Node server (https + client verify)
```ts
import https from 'node:https';
import fs from 'node:fs';

const server = https.createServer({
  cert: fs.readFileSync('server.crt'),
  key: fs.readFileSync('server.key'),
  ca: fs.readFileSync('ca.crt'),         // 클라 cert 의 CA
  requestCert: true,
  rejectUnauthorized: true,
}, (req, res) => {
  const cert = (req.socket as any).getPeerCertificate();
  if (!cert?.subject) return res.statusCode = 401, res.end();
  // cert.subject.CN 으로 클라 식별
  if (!isAllowed(cert.subject.CN)) return res.statusCode = 403, res.end();
  res.end('ok');
});

server.listen(8443);
```

### Node client
```ts
import https from 'node:https';
const agent = new https.Agent({
  cert: fs.readFileSync('client-a.crt'),
  key: fs.readFileSync('client-a.key'),
  ca: fs.readFileSync('ca.crt'),
});

const r = await fetch('https://api.local:8443/data', { agent } as any);
```

### nginx (reverse proxy mTLS)
```nginx
server {
  listen 8443 ssl;
  ssl_certificate     /etc/nginx/server.crt;
  ssl_certificate_key /etc/nginx/server.key;
  ssl_client_certificate /etc/nginx/ca.crt;
  ssl_verify_client on;
  ssl_verify_depth 2;

  location / {
    proxy_set_header X-Client-CN $ssl_client_s_dn_cn;
    proxy_pass http://backend:3000;
  }
}
```

App 은 그냥 `X-Client-CN` 헤더로 클라 식별.

### Istio (자동 mTLS)
```yaml
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata: { name: default, namespace: prod }
spec:
  mtls: { mode: STRICT }
---
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata: { name: api-allow }
spec:
  selector: { matchLabels: { app: api } }
  rules:
  - from:
    - source: { principals: ["cluster.local/ns/prod/sa/web"] }
```

→ 모든 service 간 mTLS 자동, 인증서는 Istio 가 자동 회전.

### Cert-manager (Kubernetes)
```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata: { name: api-cert }
spec:
  secretName: api-tls
  duration: 90d  # 90일
  renewBefore: 30d # 30일 전 자동 갱신
  issuerRef: { name: my-ca, kind: ClusterIssuer }
  dnsNames: [api.local]
```

### SPIFFE / SPIRE
```
spiffe://example.com/ns/prod/sa/api
```

Workload identity 자동 발급, 짧은 lifetime (1h), auto-rotate.

## 🤔 의사결정 기준
| 환경 | 추천 |
|---|---|
| K8s + 서비스 많음 | Istio / Linkerd 자동 mTLS |
| Cloud-native identity | SPIFFE / SPIRE |
| 단일 서비스 + 외부 partner | nginx + cert-manager |
| AWS | App Mesh / Private CA |
| 개발 / Test | mkcert |
| 매우 작은 팀 | 일반 TLS + bearer token 충분 |

## ❌ 안티패턴
- **인증서 만료 모니터링 없음**: 갑자기 모든 통신 끊김.
- **CA 키 leak**: 모든 cert 위조 가능. 보호 + 회전.
- **Cert 1년 짜리 + 수동 갱신**: 잊혀짐. cert-manager / 짧은 lifetime.
- **CN / SAN 검증 안 함**: 임의 cert 통과.
- **Self-signed prod**: 클라 인식 못 함. 개인 CA.
- **mTLS + ALB / CDN 불호환**: 일부 LB 가 client cert 못 forward.
- **CRL / OCSP 검증 안 함**: revoke 된 cert 그대로.

## 🤖 LLM 활용 힌트
- Service mesh 가 자동 mTLS — 직접 구현 권장 X.
- cert-manager + 짧은 lifetime + auto-rotate.
- App 은 mesh 가 인증한 client identity 헤더만 보면 OK.

## 🔗 관련 문서
- [[DevOps_Kubernetes_Basics]]
- [[DevOps_Secrets_Rotation_Automation]]
- [[Security_OWASP_Top_10_Practical]]