PushizoDocs
OperasyonRunbook'lar

Runbook: Veri anahtarı (DEK) rotasyonu

Sağlayıcı kimlik bilgileri (APNs p8, FCM private_key, VAPID private key) envelope encryption ile saklanır (ADR-0008): MASTER_KEY yalnızca veri anahtarlarını (DEK) sarar; her kayıt aktif DEK ile v2.<kid>.<iv>.<tag>.<ct>…

Sağlayıcı kimlik bilgileri (APNs p8, FCM private_key, VAPID private key) envelope encryption ile saklanır (ADR-0008): MASTER_KEY yalnızca veri anahtarlarını (DEK) sarar; her kayıt aktif DEK ile v2.<kid>.<iv>.<tag>.<ct> biçiminde şifrelenir.

Ne zaman?

  • Düzenli: 90 günde bir.
  • Olay: DEK'in sızdığından şüphelenildiğinde, yetkili bir çalışan ayrıldığında, veritabanı yedeği dışarı çıktığında.

Komut

npm run keys:rotate
```text
Yapılanlar (tek transaction):
1. Yeni DEK üretilir ve `MASTER_KEY` ile sarılarak `data_keys` tablosuna aktif olarak yazılır.
2. Önceki aktif anahtar `retired` olur.
3. `channel_configs.secret_enc` ve webhook gizlileri/özel başlıkları eski DEK ile çözülüp yeni DEK ile yeniden şifrelenir; `secret_kid` güncellenir.

Çıktı örneği:
```text
Veri anahtarı döndürüldü: dek_01… → dek_02…; yeniden şifrelenen kayıt: 3
```text

Kullanılmayan eski anahtarları silmek için (rotasyondan en az 2 dakika sonra; API/worker süreçleri aktif anahtarı 60 sn önbelleğe alır ve bu sürede eski anahtarla yazabilir):
```bash
npm run keys:rotate -- --purge-only
```text
Temizlik kanal kimlik bilgileri ile webhook gizli/önceki gizli ve özel başlıklarında kullanılan anahtarları atlar. `--purge` rotasyonla birlikte çalışır ama yeni emekliye ayrılan anahtarı bekleme süresi nedeniyle silmez.

## MASTER_KEY değişimi
`MASTER_KEY` yalnızca sarmalanmış DEK'leri ve doğrudan şifrelenmiş birkaç alanı (MFA gizli anahtarları, SDK identity secret'ları) korur.
1. Yeni 32 baytlık anahtar üretin: `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`.
2. `.env` içinde `MASTER_KEY` değerini yeni anahtarla değiştirin; eski değeri komuta verin:
```bash
npm run keys:rewrap -- --old=<eski-base64>
```text
(veya eski anahtarı `MASTER_KEY_PREVIOUS` ortam değişkeninde verin). Komut tek transaction içinde `data_keys.wrapped_dek`, `mfa_factors.secret_enc` (yalnızca TOTP; kurtarma kodları tek yönlü özet olduğundan dokunulmaz) ve `apps.sdk_secret_enc` alanlarını yeni anahtarla yeniden şifreler.
3. API ve worker süreçlerini yeniden başlatın; `POST /internal/v1/apps/{appId}/channels/{channel}/validate` ile bir kanalın çözülebildiğini ve bir MFA girişinin çalıştığını doğrulayın.

## Doğrulama
- `npm run test:integration` içinde "anahtar rotasyonu" ve "MASTER_KEY yeniden sarmalama" testleri: rotasyon/yeniden sarmalama sonrası kimlik bilgisi çözülür ve doğrulama başarılıdır.
- Rotasyon sırasında API çalışmaya devam edebilir; çözümde `kid`'e göre DEK yüklendiğinden eski ve yeni kayıtlar birlikte okunabilir.

Bu sayfada