Šifrovaný vault pro secrets¶

Bezpečné úložiště přihlašovacích údajů pomocí vault-tool

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-19

1. Přehled¶

MazeVault podporuje šifrovaný vault soubor (secrets.vault) jako bezpečnou alternativu k ukládání citlivých přihlašovacích údajů v .env souborech. Vault používá šifrování AES-256-GCM s odvozením klíčů Argon2id — stejné kryptografické standardy, jaké se používají pro šifrování secret hodnot v databázi.

Zpětná kompatibilita

Vault je plně volitelný. Bez konfigurace vaultu MazeVault funguje přesně jako dříve pomocí proměnných prostředí z .env. Můžete migrovat secrets postupně — systém se pro jakýkoli secret, který není nalezen ve vaultu, vrátí k proměnným prostředí.

Architektura¶

graph LR
    VK["🔑 vault.key<br/>(soubor s heslem)"] --> D["🔓 Dešifrovat"]
    VF["🏦 secrets.vault<br/>(šifrovaný soubor)"] --> D
    D --> MG["🛡️ memguard<br/>(zamčená paměť)"]
    MG --> BE["⚙️ Backend"]
    MG --> OCSP["📡 OCSP Responder"]

    classDef key fill:#FFF8E1,stroke:#FF9800,stroke-width:2px,color:#E65100
    classDef vault fill:#E8EAF6,stroke:#3F51B5,stroke-width:2px,color:#283593
    classDef decrypt fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px,color:#2E7D32
    classDef service fill:#EBF5FB,stroke:#2196F3,stroke-width:2px,color:#1565C0

    class VK key
    class VF vault
    class D decrypt
    class MG decrypt
    class BE,OCSP service

Co je chráněno¶

Vault uchovává až 27 citlivých přihlašovacích údajů včetně:

Kategorie	Proměnné
Kritické	`MAZEVAULT_MASTER_KEY`, `MAZEVAULT_JWT_KEY`, `DATABASE_URL`, `REDIS_URL`, `MAZEVAULT_SYNC_SECRET`
SSO / OAuth	`ENTRA_CLIENT_SECRET`, `GITHUB_CLIENT_SECRET`, `GITLAB_CLIENT_SECRET`
Integrační tokeny	`AGENT_BINARY_GITHUB_TOKEN`, `GATEWAY_BOOTSTRAP_TOKEN`, `DYNATRACE_TOKEN`
Notifikace	`SMTP_USERNAME/PASSWORD`, `SMSEAGLE_`, `JIRA_`, `TEAMS_WEBHOOK_URL`, `O365_*`
Licence	`BUILD_AUTH_SECRET`, `LICENSE_PUBLIC_KEY`
Infrastruktura	`SESSION_SECRET`, `POSTGRES_PASSWORD`, `REDIS_PASSWORD`

Bezpečnostní vlastnosti¶

Vlastnost	Implementace
Šifrování	AES-256-GCM (NIST SP 800-38D)
Odvození klíče	Argon2id (RFC 9106) — 64 MB paměti, 3 iterace, 4 vlákna
Ochrana paměti	Secrets uložené v `memguard` zamčených bufferech (mlock, ochranné stránky, vyloučení z výpisů paměti)
Formát souboru	Binární — hlavička `MVT1` + náhodná sůl + náhodný nonce + šifrovaný obsah
Práce s heslem	Vždy ze souboru — nikdy jako argumenty příkazů nebo proměnné prostředí

2. Začínáme¶

Předpoklady¶

MazeVault backend je nainstalován a spuštěn
Přístup k hostitelskému serveru (SSH nebo konzole)
Binárka vault-tool (součástí backend kontejneru)

Krok 1: Vygenerujte klíč vaultu¶

vault-tool init --key-file /opt/mazevault/vault.key

Vytvoří kryptograficky náhodný 32-bajtový soubor s heslem. Zabezpečte ho:

chmod 400 /opt/mazevault/vault.key
chown root:root /opt/mazevault/vault.key

Kritické — Zálohujte klíč

Bez vault.key nelze vault dešifrovat. Ihned ho zálohujte na bezpečné offline úložiště (viz Záloha a obnova).

Krok 2: Migrujte existující secrets¶

Pokud již máte .env soubor s citlivými hodnotami:

vault-tool migrate-env \
  --env-file /opt/mazevault/.env \
  --vault-file /opt/mazevault/secrets.vault \
  --key-file /opt/mazevault/vault.key

Extrahuje pouze 27 známých citlivých klíčů z .env a zašifruje je do vaultu. Necitlivá konfigurace (porty, feature flagy atd.) zůstává v .env.

Krok 3: Nakonfigurujte MazeVault pro použití vaultu¶

Přidejte tyto proměnné do .env nebo prostředí:

# Cesta k šifrovanému vault souboru
MAZEVAULT_VAULT_FILE=/opt/mazevault/secrets.vault

# Cesta ke klíči vaultu (soubor s heslem)
MAZEVAULT_VAULT_KEY_FILE=/opt/mazevault/vault.key

Krok 4: Ověřte¶

# Vypište secrets uložené ve vaultu
vault-tool list --vault-file /opt/mazevault/secrets.vault --key-file /opt/mazevault/vault.key

# Restartujte MazeVault a zkontrolujte health
docker compose restart backend ocsp-responder
curl -sk https://localhost/api/v1/health | jq .

Krok 5: Odeberte secrets z `.env` (volitelné)¶

Po ověření můžete odstranit citlivé hodnoty z .env a eliminovat tak expozici v čitelné podobě. Vault má přednost; .env slouží jako fallback.

3. Reference CLI `vault-tool`¶

Příkazy¶

Příkaz	Popis
`init`	Vygeneruje nový náhodný klíč vaultu
`encrypt`	Vytvoří šifrovaný vault z JSON vstupu (stdin)
`decrypt`	Dešifruje a zobrazí obsah vaultu
`add`	Přidá nebo aktualizuje jeden secret
`list`	Vypíše názvy secrets (bez hodnot)
`rotate-key`	Přešifruje vault novým heslem
`migrate-env`	Extrahuje citlivé klíče z `.env` do vaultu

`init` — Vygenerovat klíč vaultu¶

vault-tool init --key-file vault.key

Vytvoří 32-bajtový náhodný soubor s heslem. Nastavte oprávnění na 400 (čtení pouze pro vlastníka).

`migrate-env` — Migrace z `.env`¶

vault-tool migrate-env \
  --env-file .env \
  --vault-file secrets.vault \
  --key-file vault.key

Načte .env, extrahuje známé citlivé klíče a zapíše secrets.vault. Necitlivé klíče jsou ignorovány.

`add` — Přidat nebo aktualizovat secret¶

echo "muj-novy-token" | vault-tool add \
  --vault-file secrets.vault \
  --key-file vault.key \
  --name DYNATRACE_TOKEN

Čte hodnotu ze stdin. Pokud secret již existuje, je přepsán.

`list` — Vypsat názvy secrets¶

vault-tool list --vault-file secrets.vault --key-file vault.key

Zobrazí pouze názvy — hodnoty se tímto příkazem nikdy nezobrazují.

`decrypt` — Zobrazit obsah vaultu¶

# Pouze názvy (výchozí)
vault-tool decrypt --vault-file secrets.vault --key-file vault.key

# S hodnotami (používejte opatrně)
vault-tool decrypt --vault-file secrets.vault --key-file vault.key --show-values

Operační bezpečnost

Používejte --show-values pouze v zabezpečených terminálových relacích. Hodnoty secrets v historii terminálu mohou představovat riziko.

`rotate-key` — Rotace hesla vaultu¶

# Vygenerujte nové heslo
vault-tool init --key-file vault.key.new

# Přešifrujte vault novým heslem
vault-tool rotate-key \
  --vault-file secrets.vault \
  --key-file vault.key \
  --new-key-file vault.key.new

# Nahraďte starý klíč
mv vault.key.new vault.key
chmod 400 vault.key

`encrypt` — Vytvoření vaultu z JSON¶

echo '{"MAZEVAULT_MASTER_KEY": "base64value...", "DATABASE_URL": "postgres://..."}' | \
  vault-tool encrypt --vault-file secrets.vault --key-file vault.key

4. Režimy nasazení¶

On-Premise (souborový režim)¶

Nejjednodušší režim. secrets.vault i vault.key jsou na stejném hostiteli:

MAZEVAULT_VAULT_FILE=/opt/mazevault/secrets.vault
MAZEVAULT_VAULT_KEY_FILE=/opt/mazevault/vault.key

Oprávnění souborů:

Soubor	Oprávnění	Vlastník
`vault.key`	`0400`	`root:root`
`secrets.vault`	`0600`	`root:root`

Azure (heslo v Key Vault)¶

Pro Azure nasazení může být heslo uloženo v Azure Key Vault místo lokálního souboru. MazeVault použije Managed Identity k jeho získání:

MAZEVAULT_VAULT_FILE=/opt/mazevault/secrets.vault
MAZEVAULT_VAULT_AKV_URL=https://myvault.vault.azure.net
MAZEVAULT_VAULT_AKV_SECRET=mazevault-vault-key   # volitelné, výchozí název

V tomto režimu není na disku potřeba soubor vault.key — heslo se stáhne z Azure Key Vault při startu pomocí Managed Identity systému.

Legacy (bez vaultu)¶

Pokud MAZEVAULT_VAULT_FILE není nastaveno, MazeVault funguje v režimu legacy — veškerá konfigurace se čte z proměnných prostředí / .env jako dříve. Žádné změny nejsou potřeba.

5. Jak to funguje¶

Sekvence při startu¶

sequenceDiagram
    participant E as .env soubor
    participant V as secrets.vault
    participant P as VaultProvider
    participant S as Backend služby

    E->>P: godotenv.Load()
    alt MAZEVAULT_VAULT_FILE nastaven
        alt + AKV URL nastaven
            P->>P: Stáhnout heslo z Azure Key Vault
        else + KEY_FILE nastaven
            P->>P: Načíst heslo z vault.key
        end
        V->>P: Dešifrovat secrets.vault
        P->>P: Uložit do memguard zamčených bufferů
    else Vault není nakonfigurován
        P->>P: Použít režim pouze env (legacy)
    end

    P->>S: provider.Get("NAZEV_SECRETU")
    Note over P,S: Hodnota z vaultu → env fallback → prázdný řetězec

Pořadí řešení secrets¶

Pro každé vyhledání secretu:

Vault — Pokud secret existuje v šifrovaném vaultu, použije se
Prostředí — Fallback na os.Getenv() (z .env nebo systémového prostředí)
Prázdné — Pokud ani jeden zdroj nemá hodnotu, vrátí se prázdný řetězec

To umožňuje postupnou migraci: přesouvejte secrets do vaultu jeden po jednom, zatímco .env nadále funguje pro dosud nemigrované hodnoty.

6. Záloha a obnova¶

Kritické soubory¶

Soubor	Priorita zálohy	Dopad ztráty
`secrets.vault`	Kritická	Všechny šifrované přihlašovací údaje ztraceny
`vault.key`	Kritická	Nelze dešifrovat vault — trvalá ztráta dat
`.env`	Důležitá	Necitlivá konfigurace musí být znovu vytvořena

Postup zálohy¶

# Záloha vaultu a klíče na bezpečné místo
cp /opt/mazevault/secrets.vault /secure-backup/secrets.vault.$(date +%Y%m%d)
cp /opt/mazevault/vault.key /secure-backup/vault.key.$(date +%Y%m%d)

# Ověření integrity zálohy
vault-tool list \
  --vault-file /secure-backup/secrets.vault.$(date +%Y%m%d) \
  --key-file /secure-backup/vault.key.$(date +%Y%m%d)

Doporučení pro úložiště¶

Požadavek	Doporučení
Fyzické oddělení	Uložte zálohu `vault.key` na jiném fyzickém místě než `secrets.vault`
Offline úložiště	USB disk, hardwarový token nebo zapečetěná obálka v trezoru
Řízení přístupu	Přístup pouze pro oprávněné administrátory
Ověření	Čtvrtletně: ověřte, že záloha dokáže dešifrovat testovací data
Retence	Trvalá — uchovávejte všechny verze (pro historickou obnovu dat)

Postup obnovy¶

# Zkopírujte soubory na nasazovací server
cp /secure-backup/secrets.vault.20260419 /opt/mazevault/secrets.vault
cp /secure-backup/vault.key.20260419 /opt/mazevault/vault.key

# Nastavte správná oprávnění
chmod 600 /opt/mazevault/secrets.vault
chmod 400 /opt/mazevault/vault.key

# Ověřte čitelnost vaultu
vault-tool list --vault-file /opt/mazevault/secrets.vault --key-file /opt/mazevault/vault.key

# Restartujte služby
docker compose restart backend ocsp-responder
curl -sk https://localhost/api/v1/health | jq .

Obnova po havárii¶

Pokud je vault.key ztracen a neexistuje záloha, vault nelze obnovit. Musíte:

Vygenerovat nový klíč: vault-tool init --key-file vault.key
Ručně znovu vytvořit všechny secrets (z původních zdrojů: Azure portál, SMTP poskytovatel atd.)
Vytvořit nový vault: vault-tool encrypt --vault-file secrets.vault --key-file vault.key
Ihned zálohovat nový klíč

7. Rotace klíče¶

Pravidelně rotujte heslo vaultu nebo po podezření na kompromitaci:

# 1. Vygenerujte nové heslo
vault-tool init --key-file vault.key.new

# 2. Přešifrujte vault novým heslem
vault-tool rotate-key \
  --vault-file /opt/mazevault/secrets.vault \
  --key-file /opt/mazevault/vault.key \
  --new-key-file vault.key.new

# 3. Nahraďte starý klíč
mv vault.key.new /opt/mazevault/vault.key
chmod 400 /opt/mazevault/vault.key

# 4. Restartujte služby pro načtení s novým klíčem
docker compose restart backend ocsp-responder

# 5. Zálohujte nový klíč
cp /opt/mazevault/vault.key /secure-backup/vault.key.$(date +%Y%m%d)

# 6. Ověřte
vault-tool list --vault-file /opt/mazevault/secrets.vault --key-file /opt/mazevault/vault.key
curl -sk https://localhost/api/v1/health | jq .

Rotace nemění hodnoty secrets

Rotace klíče mění pouze šifrovací heslo. Secrets uvnitř zůstávají stejné — žádné změny konfigurace služeb nejsou potřeba.

8. OCSP Responder¶

OCSP Responder sdílí stejný soubor secrets.vault s backendem. Čte tři secrets:

Secret	Účel
`MAZEVAULT_MASTER_KEY`	Dešifrování uložených privátních klíčů CA
`DB_CONNECTION`	Připojovací řetězec PostgreSQL
`REDIS_URL`	URL Redis cache

Konfigurace je identická — nastavte MAZEVAULT_VAULT_FILE a MAZEVAULT_VAULT_KEY_FILE v prostředí OCSP Responderu. Pokud vault není nakonfigurován, OCSP Responder se vrátí k proměnným prostředí.

9. Řešení problémů¶

Příznak	Příčina	Řešení
`vault: cannot stat key file`	Klíč chybí nebo špatná cesta	Ověřte, že `MAZEVAULT_VAULT_KEY_FILE` ukazuje na správný soubor
`vault: decryption failed`	Špatné heslo nebo poškozený soubor	Použijte správný `vault.key`; obnovte ze zálohy
`vault key file has overly permissive permissions`	Příliš otevřená oprávnění	`chmod 400 vault.key`
`vault: file too small to be a valid vault`	Soubor je prázdný nebo zkrácený	Obnovte `secrets.vault` ze zálohy
Backend startuje, ale secrets jsou prázdné	Vault nakonfigurován, ale klíč chybí	Ověřte pomocí `vault-tool list`; přidejte chybějící klíč pomocí `vault-tool add`
Služby fungují bez vaultu	Očekávané — legacy fallback	Hodnoty z `.env` se používají, když vault není nakonfigurován nebo secret chybí

Související¶

Šifrování a správa klíčů — Kryptografické standardy
Správa klíčů — Životní cyklus klíčů a integrace HSM
Záloha a obnova — Postupy zálohy databáze a systému
Proměnné prostředí — Kompletní reference proměnných