---
title: "Hloov master key thiab signing key; kev nkag thaum muaj xwm ceev"
description: "Hloov master key uas tiv thaiv ntaub ntawv nkag khaws cia, thiab siv kev nkag thaum muaj xwm ceev."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/hmn/llms.txt
> Use this file to discover all available pages before exploring further.

# Hloov master key thiab signing key; kev nkag thaum muaj xwm ceev

<span id="master-key-and-signing-key-rotation-and-break-glass-access"></span>

Cov kev tswj hauv ntu 14 ntawm 21-compliance.md uas tus tshuaj xyuas thov npe meej. Nplooj no yog txheej txheem; cov ntaub ntawv uas nws tsim yog pov thawj.

## Cov key <!--quire:the-keys-->

Txhua credential khaws cia raug foob siv data encryption key (DEK) tshiab. Master key (KEK) qhwv DEK, thiab nws tus cim khaws ib sab (`key_ref`, lossis tus cim hauv packed value). Hloov master key tsuas rov qhwv DEK xwb. Nws tsis decrypt lossis rov encrypt credential.

| Chaw teeb tsa | Lub ntsiab lus |
| --- | --- |
| `QUIRE_MASTER_KEY` | Master key tam sim no: 32 byte, base64. Secret tshiab raug qhwv hauv qab nws |
| `QUIRE_MASTER_KEY_VERSION` | Cim version. Yog tsis teeb ces `v1`. Nce thaum twg hloov key |
| `QUIRE_MASTER_KEY_RETIRED` | Key qub uas tej secret tseem siv tau: `v1=<base64>,v0=<base64>`. Nyeem xwb, tsis sau |

Web tier, worker thiab command `bun run kek:rotate` nyeem tib peb qhov setting. Lawv yuav tsum muaj tib tus nqi, yog tsis li ib qhov qhib tsis tau yam uas lwm qhov foob.

Yog tsis muaj `QUIRE_MASTER_KEY`, txhua subsystem khaws key uas nws tsim los ntawm `QUIRE_SECRET_KEY`. Qhov no ua haujlwm, nplooj System health qhia tias qib kev noj qab haus huv poob, thiab tom qab koj teeb master key nws tseem nyeem tau; thawj qhov hloov key siv qhov no tshem txhua yam tawm. Txhua tus nyeem process environment tau decrypt tau txhua credential khaws cia, yog li production installation yuav tsum muaj master key hauv secret store, tsis txhob khaws nrog database hauv tib thaub qab.

## Hloov key <!--quire:rotating-->

Hnub nyoog key qhia hauv Platform console, Security, Master key thiab metric `quire.secrets.master_key.age` (hnub). Txhua hnub schedule `platform.key_age` (03:41 UTC) ntxiv lus ceeb toom rau platform audit chain thaum key muaj 365 hnub, ces rov ceeb toom txhua 30 hnub txog thaum hloov. Hloov thaum ceeb toom tuaj thiab txhua zaus uas tej zaum key xau.

1. Tsim key tshiab: `openssl rand -base64 32`.
2. Teem `QUIRE_MASTER_KEY` ua key ntawd thiab `QUIRE_MASTER_KEY_VERSION` ua cim tom ntej (`v2`). Muab key qub tso rau `QUIRE_MASTER_KEY_RETIRED` ua `v1=<old base64>`. Khaws ob key lwm qhov uas tsis yog host no.
3. Deploy web tier thiab worker nrog setting tshiab. Secret tshiab raug qhwv hauv `env:QUIRE_MASTER_KEY:v2`; secret qub tseem qhib tau ntawm key retired.
4. Thov hloov key nrog laj thawj uas yuav khaws hauv audit trail:
   - hauv console: Security, Master key, Rotate the master key; lossis
   - hauv shell siv environment tib yam: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Worker rov qhwv ib feem txhua feeb (schedule `platform.key_rotation`) thiab rov ua haujlwm tom qab restart. Xav ua kom tag ib zaum: `bun run kek:rotate run`. Saib xwm txheej siv `bun run kek:rotate status`.
6. Thaum record qhia tias hloov tiav nrog **zero unresolved thiab zero failed**, rho key retired ntawm `QUIRE_MASTER_KEY_RETIRED` thiab deploy dua. Txog thaum ntawd cia nws nyob: tus nqi uas txav tsis tau tseem raug qhwv nrog key qub.

### Yam uas haujlwm ntsuam <!--quire:what-the-job-walks-->

Txhua store uas muaj DEK qhwv: cov uas teev hauv `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Taug cov store ntawm control database hauv control database; taug cov store koom haum ib koom haum zuj zus raws row-level security, hauv database uas khaws koom haum ntawd, kom tenant pinned rau database tshwj xeeb hloov hauv database ntawd. Test yuav poob yog schema ntxiv wrapped-key column uas daim npe tsis hais txog; lwm test poob yog credential review cais sealed column uas daim npe plam.

### Daim record <!--quire:the-record-->

- `ops.key_rotation`: ib kab rau txhua qhov hloov key, nrog laj thawj, tus thov, xwm txheej thiab tag nrho lej (rov qhwv, twb tshiab, daws tsis tau, poob).
- `ops.key_rotation_progress`: ib kab rau txhua store thiab scope tom qab taug, nrog key reference uas nyeem tsis tau thiab pes tsawg tus nqi hauv qab txhua reference. Thaum rov khiav qhov hloov, hla cov no.
- Platform audit chain: `platform/key_rotation_request` (nrog laj thawj), ib `platform/key_rotation_store` rau txhua store nrog nws cov lej, thiab `platform/key_rotation_complete` lossis `platform/key_rotation_fail`; lus ceeb toom yog `platform/key_age_reminder`.
- Metrics: `quire.secrets.master_key.age` thiab `quire.secrets.rewrap.outstanding` (cov nqi uas hloov zaum kawg txav tsis tau).

### Thaum muaj tus nqi daws tsis tau <!--quire:when-values-are-unresolved-->

Tus nqi daws tsis tau yog raug qhwv nrog key reference uas qhov kev nruab no tsis muaj, lossis nws daim ntawv tsis phim qhov column cog lus. Progress record qhia reference (piv txwv `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Ntxiv key ntawd rov rau `QUIRE_MASTER_KEY_RETIRED` thiab hloov dua, lossis yog key ploj lawm tiag tiag, kom tus thawj coj ntawm koom haum sau credential tshiab; nws mam raug foob siv key tam sim no. Kev hloov uas poob qhia error hauv record; kho qhov ua rau thiab thov dua.

## Signing key <!--quire:signing-keys-->

Cais ntawm master key: txhua koom haum kos npe rau OpenID Connect token thiab LTI lus nrog RSA key nyias, tshaj tawm ntawm `/.well-known/jwks.json`. Tus operator tsis tas ua dab tsi ntawm no. Schedule `platform.signing_keys` khiav txhua teev tshaj tus successor xya hnub ua ntej key tam sim no muaj cuaj caum hnub; ib lim tiam tom qab successor pib kos npe thiab key qub hloov ua retiring; cuaj caum hnub tom qab ntawd key qub raug rho tawm thiab ploj ntawm key set. Txhua kauj ruam teev ua `platform/signing_key_advance` hauv platform audit chain.

Yog xav hloov key ntawm koom haum ua ntej, xws li key xau:

- hauv console: Security, Master key, Publish a new signing key (xav tau `platform/keys_manage`); lossis
- hauv shell nrog environment ntawm worker: `bun run kek:rotate signing-keys rotate --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate signing-keys status` teev key koom haum txhua qhov raws theem.

Key tshiab tshaj tawm tam sim thiab pib kos npe tom qab xya hnub, thaum key tam sim no so. Tos ib lim tiam yog txhob lam: relying party cache key set, thiab lub sijhawm sib tshooj luv dua yuav ua rau txhua tool poob ib zaug. Key retiring tseem nyob hauv key set cuaj caum hnub ntxiv kom token uas nws twb kos tseem kuaj tau; yog qhov xau txhais tias yuav tsum tso kev ntseeg tseg sai dua, rho nws row yog ib qho hloov uas ua nrog operator tus database access raws change record (break-glass access nyeem xwb), ces token kos nrog key ntawd kuaj tsis dhau. Kev hloov yuam yog `platform/signing_key_rotate` hauv audit chain nrog laj thawj. Worker yuav tsum muaj `QUIRE_MASTER_KEY` settings tib yam li web tier kom qhwv key tshiab; `bun run kek:rotate` rau master key kuj rov qhwv signing key nrog lwm yam (`oauth_signing_key` nyob hauv `SEALED_STORES`).

## Kev nkag production thaum muaj xwm ceev <!--quire:break-glass-production-access-->

Tsis muaj leej twg muaj kev nkag production tas mus li. Thaum muaj teeb meem tos tsis tau, owner muab break-glass grant: Platform console, Security, Break-glass access.

- Grant muaj scope (ib lub koom haum lossis platform registry), laj thawj tsawg kawg 20 cim uas teev incident lossis ticket, thiab sijhawm 5 txog 240 feeb. Nws tas cia li; xyuas lub sijhawm txhua zaus khiav statement.
- Muab rau owner uas thov lossis lwm owner tau (ob tug neeg). Tsuas tus neeg tau txais siv tau. Kev muab yuav tsum muaj `platform/break_glass_issue`, kev siv yuav tsum muaj `platform/break_glass_use`; raws qhov qub ob qho tsuas yog owner.
- Statement khiav ntawm gateway, tsis yog database login: nyeem xwb, ib zaug zuj zus, txwv rau koom haum lossis control registry, timeout tsib vib nas this thiab ntau kawg 500 row. Binary value qhia raws loj.
- Platform audit chain sau kev muab (nrog laj thawj), kev rho tawm, txhua statement ua ntej khiav (`platform/break_glass_statement`, qhov tsis txais teev outcome `denied`) thiab txhua txiaj ntsig (`platform/break_glass_result`). `ops.break_glass_statement` khaws audit entry ID kom record muab txuas rau audit entries.
- Tsis muaj write. Hloov uas tos tsis tau release yuav siv operator tus kheej database access raws change record, sab nraum product no, thiab record yuav tsum hais txog incident reference ntawm no.

Vim li cas tsis muab database credential: Postgres login nyob ntev dua session thov nws, hla row-level security uas app siv, thiab sau tsis tau rau audit chain ntawm product, ces statement tsuas raug tshuaj xyuas txog thaum ib tug xa server log xwb. Gateway ua kom audit trail yog ib feem ntawm kev nkag, es tsis yog ib qho kev coj ua nyob ib sab.

Teb audit request: teev grant hauv lub sijhawm ntawd (Break-glass access), qhib keeb kwm grant saib statement thiab audit entry ID, ces nyeem cov entry hauv platform audit chain (`bun run audit:verify --platform` ua pov thawj tias chain tseem ruaj).

Source: https://docs.quirelms.com/hmn/ops/key-rotation/index.mdx