---
title: "Juya maɓallin babba da na sa hannu, da damar gaggawa"
description: "Juya maɓallin babba da ke kare shaidar shiga da aka adana, kuma yi amfani da damar gaggawa idan dole."
image: "https://docs.quirelms.com/og.png"
---

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

# Juya maɓallin babba da na sa hannu, da damar gaggawa

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

Matakan sarrafawa a sashe na 14 na 21-compliance.md da mai tantancewa ke nema da suna.
Wannan shafi shi ne tsarin aiki; bayanan da yake samarwa su ne hujja.

## Maɓallan <!--quire:the-keys-->

Ana kulle kowace shaidar shiga da sabon maɓallin ɓoye bayanai (DEK). Ana lulluɓe
DEK da maɓallin babba (KEK), kuma ana adana nuni ga maɓallin babba kusa da shi
(`key_ref`, ko nuni a cikin ƙimar da aka tattara). Juya maɓallin babba yana sake
lulluɓe DEK. Ba ya taɓa warware sirrin shiga ko sake ɓoye shi.

| Saiti | Ma'ana |
| --- | --- |
| `QUIRE_MASTER_KEY` | Maɓallin babba na yanzu: bytes 32, base64. Ana lulluɓe kowane sabon sirri da shi |
| `QUIRE_MASTER_KEY_VERSION` | Alamar sigarsa. `v1` idan ba a saita ba. Ɗaga ta duk lokacin da ka canza maɓalli |
| `QUIRE_MASTER_KEY_RETIRED` | Tsofaffin maɓallan da sirri da aka adana zai iya amfani da su, kamar `v1=<base64>,v0=<base64>`. Ana karantawa, ba a rubutawa ba |

Sashen yanar gizo, mai aiki da umarnin `bun run kek:rotate` duk suna karanta saituna
uku iri ɗaya. Dole ƙimomin su yi daidai, ko ɗaya ba zai iya buɗe abin da ɗayan
ya kulle ba.

Idan babu `QUIRE_MASTER_KEY`, kowane sashe yana ci gaba da amfani da maɓallin da
yake samo daga `QUIRE_SECRET_KEY`. Wannan yana aiki, shafin Lafiyar Tsari yana nuna
raguwar lafiya, kuma bayanai suna nan a karantawa bayan saita maɓallin babba; haka
ake fara cire komai daga tsohon maɓalli. Duk wanda zai iya karanta yanayin aiki
zai iya warware duk shaidar shiga da aka adana, saboda haka shigarwar samarwa ya
kamata ta samu maɓallin babba a cikin ma'ajiyar sirri, ba a ajiyar bayanai ɗaya ba.

## Juya maɓalli <!--quire:rotating-->

Ana nuna shekarun maɓalli a Platform console, Security, Master key, da ma'aunin
`quire.secrets.master_key.age` (kwanaki). Jadawalin kullum `platform.key_age`
(03:41 UTC) yana rubuta tunatarwa a sarkar tantancewa ta dandamali idan maɓalli ya
kai kwana 365, sannan duk bayan kwana 30 har sai an juya shi. Juya bisa tunatarwar
da kuma duk lokacin da maɓalli zai iya fallasa.

1. Ƙirƙiri sabon maɓalli: `openssl rand -base64 32`.
2. Saita `QUIRE_MASTER_KEY` da shi, sannan `QUIRE_MASTER_KEY_VERSION` zuwa alama
   ta gaba (`v2`). Matsar da tsohon maɓalli zuwa `QUIRE_MASTER_KEY_RETIRED` a matsayin
   `v1=<old base64>`. Riƙe kwafi biyun a wani wuri dabam da wannan uwar garke.
3. Sanya sashen yanar gizo da mai aiki da sabbin saituna. Yanzu ana lulluɓe sababbin
   sirrika ƙarƙashin `env:QUIRE_MASTER_KEY:v2`; ana ci gaba da buɗe tsofaffi ta
   maɓalli da aka yi ritaya.
4. Nemi a juya maɓalli, tare da dalilin da za a adana a rajistar tantancewa:
   - a console: Security, Master key, Rotate the master key; ko
   - a harsashi mai irin yanayin aiki: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Mai aiki yana sake lulluɓe wani sashe a kowane minti (jadawalin
   `platform.key_rotation` na mai tsara aiki), sannan ya ci gaba bayan sake farawa.
   Domin kammala a lokaci guda: `bun run kek:rotate run`. Bibiyar da
   `bun run kek:rotate status`.
6. Idan rikodi ya nuna an kammala juya maɓalli tare da **sifili da ba a warware ba
   da sifili da suka gaza**, cire maɓallin ritaya daga `QUIRE_MASTER_KEY_RETIRED`
   sannan sake tura sassan. Har sai lokacin, riƙe shi: ƙimar da ba a iya matsarwa
   har yanzu tana kulle da tsohon maɓallin.

### Abin da aikin ke bi <!--quire:what-the-job-walks-->

Kowane ma'ajiya da ke riƙe DEK da aka lulluɓe: waɗanda ke cikin
`SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Ana duba ma'ajiyar sarrafawa
a ma'ajiyar sarrafawa; ana duba ta ƙungiyoyi ɗaya bayan ɗaya ƙarƙashin tsaron
matakin layi, a kowace ma'ajiya da ƙungiyar take ciki, saboda haka maɓallin
ƙungiyar da aka keɓe zuwa ma'ajiyar kanta yana juyawa a wurin. Gwaji yana gaza
idan tsarin ya ƙara shafi maɓalli a kulle amma jerin bai ambace shi ba; wani gwajin
kuma yana gaza idan nazarin takardun shaidar shiga ya ware shafi a kulle da jerin
ya manta.

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

- `ops.key_rotation`: layi ɗaya ga kowane juya maɓalli, tare da dalilinsa, wanda
  ya nema, matsayinsa da jimillarsa (sake lulluɓe, yana kan yanzu, ba a warware ba,
  ya gaza).
- `ops.key_rotation_progress`: layi ga kowane ma'ajiya da iyaka idan an duba,
  tare da nuni ga maɓallan da ba a iya karantawa da yawan ƙimomin kowanne. Juya
  da aka ci gaba daga baya yana tsallake waɗannan.
- Sarkar tantancewa ta dandamali: `platform/key_rotation_request` (tare da
  dalili), `platform/key_rotation_store` guda ɗaya ga kowane ma'ajiya da
  ƙididdigarsa, da `platform/key_rotation_complete` ko
  `platform/key_rotation_fail`; `platform/key_age_reminder` ga tunatarwa.
- Ma'aunai: `quire.secrets.master_key.age` da
  `quire.secrets.rewrap.outstanding` (ƙimomin da juya na ƙarshe bai iya matsarwa ba).

### Idan akwai ƙimomi da ba a warware ba <!--quire:when-values-are-unresolved-->

Ƙima marar warwarewa tana kulle ƙarƙashin nuni ga maɓalli da shigarwar ba ta da,
ko kuma ba ta cikin tsarin da shafinta ya yi alƙawari. Rikodin ci gaba yana nuna
nuni (misali `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Mayar da maɓallin zuwa
`QUIRE_MASTER_KEY_RETIRED` sannan sake juya maɓalli, ko idan maɓallin ya ɓace har
abada, mai gudanarwar ƙungiyar ya sake shigar da shaidar; sai a kulle ta da
maɓallin yanzu. Juya da ya gaza yana nuna kuskurensa a rikodi; gyara musabbabin,
sannan sake nema.

## Maɓallan sa hannu <!--quire:signing-keys-->

Banda maɓallin babba, kowace ƙungiya tana sa hannu ga alamar OpenID Connect da
saƙonnin LTI da nata maɓallin RSA, wanda ake wallafawa a `/.well-known/jwks.json`.
Mai sarrafa shigarwa ba ya buƙatar yin wani abu. Jadawalin sa'a-safa
`platform.signing_keys` yana wallafa magaji kwana bakwai kafin tsohon ya kai
kwana casa'in; bayan mako magajin zai fara sa hannu, tsohon kuma ya shiga ritaya;
kwana casa'in bayan haka ana share tsohon daga saitin maɓalli. Ana rubuta kowane
mataki a matsayin `platform/signing_key_advance` a sarkar tantancewar dandamali.

Domin musanya maɓallin ƙungiya da wuri, misali bayan fallasa:

- a console: Security, Master key, Publish a new signing key (yana buƙatar
  `platform/keys_manage`); ko
- a harsashi mai yanayin mai aiki: `bun run kek:rotate signing-keys rotate
  --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate
  signing-keys status` yana lissafa maɓallan kowace ƙungiya bisa mataki.

Ana wallafa sabon maɓalli nan take, kuma zai fara sa hannu bayan kwana bakwai,
yayin da na yanzu ke ritaya. An shirya makon da gangan: masu amfana suna adana
saitin maɓalli, kuma gajeren lokacin haɗuwa zai hana duk kayan aiki aiki lokaci guda.
Maɓallin ritaya yana nan a saitin na ƙarin kwana casa'in domin a ci gaba da tantance
alamomin da ya riga ya sa wa hannu; idan fallasar tana nufin dole a daina yarda da
shi da wuri, share layinsa canji ne da ake yi da damar ma'ajiyar bayanai ta mai
gudanarwa a ƙarƙashin rikodin canji (damar gaggawa karatu kawai ce), alamomin da
aka sa wa hannu da shi kuma za su gaza tantancewa. Ana adana juya tilas a matsayin
`platform/signing_key_rotate` a sarkar tantancewa tare da dalili. Mai aiki na buƙatar
saitunan `QUIRE_MASTER_KEY` iri ɗaya da sashen yanar gizo domin lulluɓe sabon maɓalli;
`bun run kek:rotate` na babban maɓalli yana sake lulluɓe maɓallan sa hannu tare da
sauran (`oauth_signing_key` yana cikin `SEALED_STORES`).

## Damar gaggawa ga samarwa <!--quire:break-glass-production-access-->

Babu wanda yake da damar shiga samarwa kullum. Idan wani abu ba zai iya jira ba,
mai shi yana ba da izinin gaggawa: Platform console, Security, Break-glass access.

- Izini yana da iyaka (ƙungiya ɗaya ko rajistar dandamali), dalilin aƙalla haruffa
  20 da ya ambaci matsala ko tikiti, da wa'adin minti 5 zuwa 240. Yana ƙarewa da
  kansa: ana gwada agogo ga kowace umarni.
- Ana iya ba shi ga mai shi da kansa ko wani mai shi (tsarin mutane biyu). Mai
  karɓa kaɗai ne zai iya amfani da shi. Bayarwa yana buƙatar
  `platform/break_glass_issue`, amfani kuma yana buƙatar `platform/break_glass_use`;
  a matsayin tsoho duka ga mai shi kawai.
- Umarnin yana gudana ta ƙofar shiga, ba shiga kai tsaye cikin ma'ajiya ba:
  karatu kawai, guda ɗaya a lokaci guda, a cikin ƙungiya ko rajistar sarrafawa,
  yana da iyakar daƙiƙa biyar da layuka 500. Ana nuna girman bayanan binary.
- Sarkar tantancewa ta dandamali tana rajistar bayarwa (tare da dalili), sokewa,
  kowane umarni kafin gudansa (`platform/break_glass_statement`, wanda aka ƙi
  kuma yana da sakamakon `denied`), da kowane sakamako
  (`platform/break_glass_result`). `ops.break_glass_statement` yana adana ID na
  shigarwar tantancewa, don haka ana haɗa rikodin bayarwa da shigarwarsa.
- Ba a bayar da rubutawa ba. Canjin da ba zai iya jira sakin siga ba yana amfani
  da damar ma'ajiyar bayanai ta mai gudanarwa a ƙarƙashin nasa rikodin canji,
  a wajen wannan samfurin, kuma rikodin ya kamata ya kawo lambar matsalar da aka
  yi amfani da ita a nan.

Dalilin da ba a ba da takardun shiga ma'ajiya ba: shiga Postgres yana wuce zaman da
ya nemi shi, yana kauce wa tsaron matakin layi da manhaja ta dogara da shi, kuma
ba zai iya rubutawa a sarkar tantancewar samfurin ba; don haka sai dai log ɗin uwar
garke ya ba da ɗan shaidar ayyukansa. Ƙofar shiga tana mai da hanyar tantancewa
mallakar izinin shiga, maimakon al'ada kawai a kewayensa.

Domin amsa buƙatar tantancewa: jera izinin da aka bayar a lokacin (Break-glass
access), buɗe tarihin izini domin ganin umarninsa da ID na shigarwar tantancewa,
sannan karanta waɗannan shigarwa a sarkar tantancewar dandamali
(`bun run audit:verify --platform` yana tabbatar da cikar sarkar).

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