---
title: "Biguherîna kilîta sereke û kilîta qedandin, û gihîştina gagiz"
description: "Kilîta sereke ku têketnaverên parastî parastî dike biguherîne, û gihîştina gagiz bikar bîne."
image: "https://docs.quirelms.com/og.png"
---

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

# Biguherîna kilîta sereke û kilîta qedandin, û gihîştina gagiz

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

Kontrolên di 21-compliance.md beş 14 de ku denetmêr bi nav daxwaz dike. Ev rûpel procedûr e; supayên ku wê dide dîtin evidans in.

## Kilît <!--quire:the-keys-->

Her têketnaver ku tê parastin bi kilîteke nû ya şifrakirina datayê (DEK) tê mühûrkirin. DEK bi kilîta sereke (KEK) tê veşartîn, û nîşankera kilîta sereke li alî wê tê parastin (`key_ref`, an nîşankera di nawa nirxekî veşartî de). Biguherîna kilîta sereke DEKan dîsa veşarî dike. Her tim têketnavek şifra nake an dîsa şifra nake.

| Mîhaz | Mani |
| --- | --- |
| `QUIRE_MASTER_KEY` | Kilîta sereke ya niha: 32 hejmara, base64. Her nepûrekî nû bi wê tê veşartîn |
| `QUIRE_MASTER_KEY_VERSION` | Nîşanera nûşeya wê. Gava neyê sazkirin `v1`. Her car ku tu kilîtê biguherînî bilind bike |
| `QUIRE_MASTER_KEY_RETIRED` | Kilîtên berê yên ku nepûr parastî in dikarin hê di bin wê bin, wek `v1=<base64>,v0=<base64>`. Tenê dixwînin, her tim ne nivîsin |

Navûpa web, worker û fermana `bun run kek:rotate` heman sê mîhazan dixwînin. Hemû divê heman nirxan bin, an yek ji wan nikare ewî veke ku digerek mühûrkiriye.

Bê `QUIRE_MASTER_KEY` her subsistem kilîta ku ji `QUIRE_SECRET_KEY` derdike parastî dike. Ew karekî dike, rûpela sagiya pergalê wê wekî kêm nîşan dike, û dûpiştî ku tu kilîteke sereke saz bikî hê dixwînî ye, ku bi vê re gurîştina yekem her tişt ji wê ve digure. Her kes ku dikare pêşandanîya prosesê bixwîne dikare her têketnaver parastî şifra, ji ber vê sazkirinek production divê kilîteke sereke heye, ku di daneke nepûrê de tê parastin û ne di heman veparîstinê de wek danegirşê.

## Biguherîn <!--quire:rotating-->

Temaû dema kilîtê di konsola platform, Parastin, Kilîta sereke de dide xweyîn, û wek metrîka `quire.secrets.master_key.age` (roj). Pêşnîşana rojane ya `platform.key_age` (03:41 UTC) gava kilît bibe 365 roj di zencîra denetinê de tiştekî bîranînê nivîsî dike, û her 30 rojan dîsa heta biguherînê. Bi bîranînê biguherîne, û her car ku kilît dibe hatiye rakerandin.

1. Kilîta nû çêke: `openssl rand -base64 32`.
2. `QUIRE_MASTER_KEY` bi wê saz bike û `QUIRE_MASTER_KEY_VERSION` bi nîşanera piştî (`v2`). Kilîta kevn bavêje `QUIRE_MASTER_KEY_RETIRED` wek `v1=<old base64>`. Kopîya herduyan di cîgeke dinî ji vê serverê biparîzê.
3. Navûpa web û worker bi mîhazên nû bezoste. Nepûrên nû niha di `env:QUIRE_MASTER_KEY:v2` de tên veşartîn; yên kevn hê bi kilîta bêjestî ve tên vekirin.
4. Biguherînê bixwaze, bi aboka ku di serîdana denetinê de dimîne:
   - di konsolê de: Parastin, Kilîta sereke, Kilîta sereke biguherîne; an
   - di shellê bi heman derdikevarinê de: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Worker her deqîqeyek parçeke dîsa veşarî dike (pêşnîşana planerê ya `platform.key_rotation`) û dûpiştî destpekvekê dewam dike. Ji bo temamkirina wê bi nivîşanekî: `bun run kek:rotate run`. Wê bi `bun run kek:rotate status` saz bike.
6. Gava supayê nîşan dide ku biguherîn bi **sifirê neçareser û sifirê serket** temam bûye, kilîta bêjestî ji `QUIRE_MASTER_KEY_RETIRED` rake û dîsa bezoste. Heta wê demê wê biparîzê: nirxekek ku nikarî veguherîne hê di kilîta kevn de veşartî ye.

### Erek çi dişopîne <!--quire:what-the-job-walks-->

Her daneke ku DEKê veşartî dihêle: wên di `SEALED_STORES` de (`apps/worker/src/key-rotation.ts`). Danên danegirşa kontrolê li ser danegirşa kontrolê tên şopîn; danên rêxistin bi rêxistinek bi parastina rizê tên şopîn, li danegirşê ku rêxistin dihêle, ji ber vê tenantekî veşartî li danegirşê wekî taybet di wê danegirşê de biguherîne. Ceribandekek serket gava mîgar ûstûlekî kilîta veşartî pezîr dike ku lîste nav nade, an digere gava çawaskiriya têketnaver ûstûleke mühûrkirî ku lîste derdike tê hezkirin.

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

- `ops.key_rotation`: rizyek ji bo her biguherînek, bi aboka wê, kê daxwaz kirîye, derengama wê û tevahî wê (veşartî nû, hê niha, neçareser, serket).
- `ops.key_rotation_progress`: rizyek ji bo her daneû scope gava şopîn bûn, bi nîşankera kilîtên ku nikarî bixwîne û çend nirx di bin her yek de. Biguherînek ku dewam dike wan derdike.
- Zencîra denetinê ya platform: `platform/key_rotation_request` (bi aboka wê), `platform/key_rotation_store` ji bo her dane bi hejmara wê, û `platform/key_rotation_complete` an `platform/key_rotation_fail`; `platform/key_age_reminder` ji bo bîranînê.
- Metrîk: `quire.secrets.master_key.age` û `quire.secrets.rewrap.outstanding` (nirxên ku gurîştina dawî nikarî veguherîne).

### Gava nirx neçareser in <!--quire:when-values-are-unresolved-->

Nirxeke neçareser bi nîşankerekî kilît ku vê sazkirinê tune veşartî ye, an ne di şîle ku ûstûl wê awête dike. Supaya pêşketinê nîşankera navdide (mîna `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Ew kilîtî `QUIRE_MASTER_KEY_RETIRED` vegerîne û biguherînekî din bixebitîne, an, ger kilît bi temavî derket, rêveberyê rêxistinê bivêje têketnaverê dîsa binivîse: lewra di kilîta niha de tê mühûrkirin. Biguherînên serket xeltê li supayê nîşan dide; abokê rastîrke û dîsa bixwaze.

## Kilîtên qedandin <!--quire:signing-keys-->

Cuda ji kilîta sereke: her rêxistin tokeyên OpenID Connect û peyamên LTI bi kilîta RSA a xwe qedê dike, ku di `/.well-known/jwks.json` de tê belavkirin. Tiştek li vir ji operator pêwîst nake. Pêşnîşana saetî ya `platform.signing_keys` hefteke berê ku sedî kilîta niha qediya bibe bişîneke dide belav, hefteke piştî wê bişîne dest pê dike qedandin û kilîta kevn dibe nûvend, û navî de rojek nedeyan kilîta kevn tê rakirin û ji kilîtan derdike. Her gav têgilîyeke `platform/signing_key_advance` di zencîra denetinê ya platform de ye.

Ji bo biguherîna zû a kilîta rêxistinek, mîna piştî rakerandinê:

- di konsolê de: Parastin, Kilîta sereke, Kilîteke qedandinê nû belav bike (pêwîst e `platform/keys_manage`); an
- di shellê bi derdikevariya worker de: `bun run kek:rotate signing-keys rotate
  --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate
  signing-keys status` kilîtên her rêxistinê bi astê li lîsteyê dide.

Kilîta nû bi tenê tê belavkirin û dûpiştî heftekeke qedandin dest pê dike, gava kilîta niha nûvend dike. Hefte bikûtîya e: relye partenên kilîtan divêşarin, û hevpariya kêmtr her amûrek bi tenê serneket dike. Kilîta nûvend neyî de di kilîtan de 90 rojan mayî digire ta tokeyên ku hê qedandiye hê tê rastînkirin; ger rakerandin tê were wêjîn ka divê zûtre bavêjî bêbaweriyê, rakina rizê wê guherdineke ye ku bi gihîştina danegirşê ya operator bi supaya guhertina xwe ye, derveyî vê berhevokê (gihîştina gagiz tenê dixwîne), û tokeyên bi wê qedandî piştî rastînkirinê serket dibe. Biguherîna epêç di zencîra denetinê de `platform/signing_key_rotate` ye, bi aboka re. Worker heman mîhazên `QUIRE_MASTER_KEY` ya navûpa web pêwîst dike ta kilîta nû veşarî bike; `bun run kek:rotate` ji bo kilîta sereke kilîtên qedandinê bi her tiştî din dîsa veşarî dike (`oauth_signing_key` di `SEALED_STORES` de ye).

## Gihîştina gagiz a production <!--quire:break-glass-production-access-->

Kesî gihîştina berdurekî ya production nahiye. Gava tiştek nikare bendê bike, sandiyareke ragihandî dike: Konsola platform, Parastin, Gihîştina gagiz.

- Sandiyekek scope heye (rêxistinek, an rejestra platform), abokekî ji kêmtirî 20 tîp ku tîba xete an bilez nîşan dike, û pencereyekî ji 5 heta 240 deqîqe. Bi xwe derdike: di her bayanê de bi dem re tê çawaskirin.
- Dikare weke sandiyarekê ragihandîne, an sandiyarekî din (şîla du kes). Tenê kesê ku wê ragihandiye bikar tîne. Ragihandî pêwîst e `platform/break_glass_issue` û bikaranîn pêwîst e `platform/break_glass_use`; herdu bi veberî tenê sandiyarek in.
- Bayan bi rêkî gateway tên xebitandin, ne bi têketina danegirşê: tenê dixwînin, carekê, bişopînî bo rêxistinê an bo rejestra kontrol, bi serhêndekewekî pênc seretan û bi kêmtirî 500 riz. Nirxên binary bi mezinahî tên nîşan.
- Zencîra denetinê ya platform ragihandî (bi aboka wê), bêjestîn, her bayan berî xebitandinê (`platform/break_glass_statement`, wan ê raqûlkirî bi encamê `denied`) û her encam (`platform/break_glass_result`) tomarkî dike. `ops.break_glass_statement` IDyên têgilîyên denetinê dihêle, ji ber vê supaya ragihandî bi têgilîyên denetin wê tê girêdan.
- Nivîsandin pêşkêş nake. Guherdinek ku nikare bendê wêşanê bikare gihîştina danegirşê ya operator bi supaya guhertina xwe re, derveyî vê berhevokê, û supay divê nîşankera tîba xete ya li vir bikar anîneye.

Ji bo çi têketnaverên danegirş neyên ragihandîn: têketinek Postgres ji seansa ku wê daxwaz kirîye bilindtir dibe, parastina rizê ya nivîsbariyê bigire, û nikare di zencîra denetinê ya vê berhevokê de nivîsî, ji ber vê bayanên wê tenê ta kêyê ku kes loga serwerê hatiye şandin tên denetîn. Gateway rihîna denetinê wek taybetmendiya gihîştî dike, ne wekî berhevkiriyekî li gorî wê.

Ji bo bersivdanî daxwaza denetinê: sandiyên di dema ve li lîsteyê bide (Gihîştina gagiz), dîroka sandiyekê veke ji bo bayanên wê û IDyên têgilîyên denetinê, û ew têgilîyan di zencîra denetinê ya platform de bixwîne (`bun run audit:verify --platform` piştrîn dike ku zencîr tam e).

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