---
title: "Cuairteachadh na h-iuchrach-mhaighstir is nan iuchraichean-soidhnidh, agus ruigsinneachd èiginn"
description: "Cuairtich iuchair-mhaighstir a dhìonas teisteanasan stòraichte agus cleachd ruigsinneachd èiginn."
image: "https://docs.quirelms.com/og.png"
---

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

# Cuairteachadh na h-iuchrach-mhaighstir is nan iuchraichean-soidhnidh, agus ruigsinneachd èiginn

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

Na smachdan ann an earrann 14 de 21-compliance.md a dh’iarras neach-sgrùdaidh nan ainm. Seo am modh-obrach; ’s iad na clàran a chruthaicheas e an fhianais.

## Na h-iuchraichean <!--quire:the-keys-->

Tha gach teisteanas stòraichte air a sheulachadh le iuchair-chrioptachaidh dàta (DEK) ùr. Tha an DEK air a pasgadh leis an iuchair-mhaighstir (an KEK), agus tha iomradh na h-iuchrach-mhaighstir air a stòradh ri thaobh (`key_ref`, no an t-iomradh taobh a-staigh luach pacaichte). Bidh cuairteachadh na h-iuchrach-mhaighstir ag ath-phasgadh nan DEK. Cha dì-chrioptaich no ath-chrioptaich e teisteanas.

| Roghainn | Brìgh |
| --- | --- |
| `QUIRE_MASTER_KEY` | An iuchair-mhaighstir làithreach: 32 baidht, base64. Thèid gach dìomhaireachd ùr a phasgadh innte |
| `QUIRE_MASTER_KEY_VERSION` | Leubail an tionndaidh. `v1` mura h-eil i suidhichte. Meudaich e gach turas a dh’atharraicheas tu an iuchair |
| `QUIRE_MASTER_KEY_RETIRED` | Iuchraichean na bu tràithe a dh’fhaodadh fhathast dìomhaireachdan a dhìon, mar `v1=<base64>,v0=<base64>`. Leugh a-mhàin, na sgrìobh |

Leughaidh an t-sreath-lìn, an neach-obrach agus àithne `bun run kek:rotate` na trì roghainnean ceudna. Feumaidh na h-aon luachan a bhith aca uile, no chan urrainn do dh’aon dhiubh fosgladh na sheulaich fear eile.

Gun `QUIRE_MASTER_KEY`, cumaidh gach fo-shiostam iuchair a thig e à `QUIRE_SECRET_KEY`. Obraichidh seo; tha duilleag slàinte an t-siostaim a’ sealltainn gu bheil an t-inbhe air a dhol sìos agus bidh an iuchair fhathast furasta a leughadh an dèidh dhut prìomh iuchair a shuidheachadh, agus sin mar a ghluaiseas a’ chiad chuairteachadh a h-uile càil air falbh bhuaipe. Faodaidh neach sam bith a leughas àrainneachd a’ phròiseis gach teisteanas stòraichte a dhì-chrioptachadh; mar sin bu chòir iuchair-mhaighstir a bhith aig stàladh riochdachaidh, ann an stòr dhìomhaireachdan seach sa chùl-taic cheudna ris an stòr-dàta.

## Cuairtich <!--quire:rotating-->

Tha aois na h-iuchrach ri fhaicinn ann an Consol Àrd-chabhsaire, Tèarainteachd, Iuchair-mhaighstir agus mar mheatraig `quire.secrets.master_key.age` (làithean). Sgrìobhaidh an clàr làitheil `platform.key_age` (03:41 UTC) inntrigeadh cuimhneachaidh ann an sreath sgrùdaidh an àrd-chabhsaire nuair a ruigeas an iuchair 365 latha, agus a-rithist gach 30 latha gus an tèid a cuairteachadh. Dèan cuairteachadh nuair a thig an cuimhneachan, agus uair sam bith a dh’fhaodadh iuchair a bhith fosgailte.

1. Cruthaich an iuchair ùr: `openssl rand -base64 32`.
2. Suidhich `QUIRE_MASTER_KEY` rithe agus `QUIRE_MASTER_KEY_VERSION` chun ath leubail (`v2`). Gluais an t-seann iuchair gu `QUIRE_MASTER_KEY_RETIRED` mar `v1=<old base64>`. Cùm lethbhreac den dà iuchair an àiteigin eile seach air an aoigh seo.
3. Cleachd an t-sreath-lìn agus an neach-obrach leis na roghainnean ùra. Thèid dìomhaireachdan ùra a phasgadh a-nis fo `env:QUIRE_MASTER_KEY:v2`; fosglaidh feadhainn shean fhathast leis an iuchair a chaidh a leigeil dhith.
4. Iarr an cuairteachadh leis an adhbhar a thèid a chlàradh ann an sreath an sgrùdaidh:
   - anns a’ chonsol: Tèarainteachd, Iuchair-mhaighstir, Cuairtich an iuchair-mhaighstir; no
   - ann an slige leis an aon àrainneachd: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Ath-phaisgidh an neach-obrach pìos dhiubh gach mionaid (clàr `platform.key_rotation` a’ chlàradair) agus leanaidh e às dèidh ath-thòiseachaidh. Gus crìoch a chur air ann an aon sheisean: `bun run kek:rotate run`. Cumaibh sùil leis `bun run kek:rotate status`.
6. Nuair a sheallas an clàr gun deach an cuairteachadh a chrìochnachadh le **neoni gun fhuasgladh agus neoni fàilligeadh**, thoir air falbh an t-seann iuchair à `QUIRE_MASTER_KEY_RETIRED` agus cleachd a-rithist e. Cùm i gus an uair sin: tha luach nach b’ urrainn dhi gluasad fhathast paisgte fon t-seann iuchair.

### Na thèid an obair troimhe <!--quire:what-the-job-walks-->

Gach stòr a chumas DEK paisgte: an fheadhainn ann an `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Thèid stòran bunait smachd a choiseachd san stòr-dàta smachd; thèid stòran buidhne a choiseachd aon bhuidheann aig aon àm fo tèarainteachd ìre-shreathan, anns an stòr-dàta far a bheil a’ bhuidheann. Mar sin thèid neach-gabhail a tha ceangailte ri stòr-dàta sònraichte a chuairteachadh anns an stòr-dàta sin. Fàilligidh deuchainn nuair a chuireas an sgeama colbh iuchair-phaisgte ris nach eil air ainmeachadh san liosta, agus fàilligidh tè eile nuair nach fhaic lèirmheas theisteanasan colbh seulaichte a tha air chall às an liosta.

### An clàr <!--quire:the-record-->

- `ops.key_rotation`: aon sreath airson gach cuairteachadh, le adhbhar, cò dh’iarr e, inbhe agus àireamhan (ath-phasgta, làithreach mar-thà, gun fhuasgladh, air fàilligeadh).
- `ops.key_rotation_progress`: sreath airson gach stòr is raon a chaidh a choiseachd, le iomraidhean iuchrach nach gabhadh leughadh agus cia mheud luach a bha fo gach tè. Leumaidh cuairteachadh a thèid ath-thòiseachadh thairis orra sin.
- Sreath sgrùdaidh an àrd-chabhsaire: `platform/key_rotation_request` (leis an adhbhar), aon `platform/key_rotation_store` gach stòr le àireamhan, agus `platform/key_rotation_complete` no `platform/key_rotation_fail`; `platform/key_age_reminder` airson a’ chuimhneachaidh.
- Meatraigean: `quire.secrets.master_key.age` agus `quire.secrets.rewrap.outstanding` (luachan nach b’ urrainn don chuairteachadh mu dheireadh gluasad).

### Nuair a tha luachan gun fhuasgladh <!--quire:when-values-are-unresolved-->

Tha luach gun fhuasgladh paisgte fo iomradh iuchrach nach eil aig an stàladh seo, no chan eil e san chruth a tha an colbh a’ gealltainn. Ainmichidh an clàr adhartais an t-iomradh (mar eisimpleir `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Cuir an iuchair air ais ann an `QUIRE_MASTER_KEY_RETIRED` agus ruith cuairteachadh eile; no, ma tha an iuchair air chall gu bràth, iarr air rianaire na buidhne an teisteanas a chur a-steach a-rithist, agus thèid a sheulachadh leis an iuchair làithreach. Seallaidh cuairteachadh a dh’fhàillig a mhearachd air a’ chlàr; ceartaich an t-adhbhar agus iarr a-rithist e.

## Iuchraichean-soidhnidh <!--quire:signing-keys-->

Air leth bhon iuchair-mhaighstir, soidhnichidh gach buidheann tòcan OpenID Connect agus teachdaireachdan LTI leis an iuchair RSA aice fhèin, air fhoillseachadh aig `/.well-known/jwks.json`. Chan fheum an gnìomhaiche dad a dhèanamh an seo. Foillsichidh an clàr uairail `platform.signing_keys` iuchair a thig na h-àite seachd làithean mus tig 90 latha na h-iuchrach làithrich gu crìch; seachdain às dèidh sin tòisichidh an tè ùr air soidhnigeadh agus thèid an t-seann tè a chur a-mach à seirbheis; agus às dèidh 90 latha eile thèid an t-seann iuchair a sguabadh às agus às an t-seata. Tha gach ceum na inntrigeadh `platform/signing_key_advance` ann an sreath sgrùdaidh an àrd-chabhsaire.

Gus iuchair buidhne a chur na h-àite tràth, mar eisimpleir an dèidh nochdadh:

- sa chonsol: Tèarainteachd, Iuchair-mhaighstir, Foillsich iuchair-soidhnidh ùr (feumar `platform/keys_manage`); no
- ann an slige le àrainneachd an neach-obrach: `bun run kek:rotate signing-keys rotate --tenant <slug or id> --reason "Key exposed, INC-3310"`. Tha `bun run kek:rotate signing-keys status` a’ liostadh iuchraichean gach buidhne a rèir ìre.

Foillsichear an iuchair ùr sa bhad agus tòisichidh i air soidhnigeadh an dèidh seachd làithean nuair a thèid an iuchair làithreach a leigeil dhith. Tha an t-seachdain sin a dh’aona ghnothach: tasgaidh pàrtaidhean earbsach seata na h-iuchrach, agus dh’fhàilligheadh a h-uile inneal aig an aon àm le tar-lùbadh nas giorra. Fanaidh an iuchair a tha ga leigeil dhith san t-seata airson 90 latha eile gus an lean tòcan a chaidh a soidhnigeadh leatha orra a bhith air an dearbhadh. Ma tha an nochdadh a’ ciallachadh nach bu chòir earbsa a bhith innte nas tràithe, ’s e atharrachadh a nì an gnìomhaiche le ruigsinneachd stòr-dàta fhèin fo chlàr atharrachaidh a th’ ann a sreath a sguabadh às (tha ruigsinneachd èiginn leughaidh a-mhàin), agus fàilligidh dearbhadh tòcan a chaidh a soidhnigeadh leatha. Tha an cuairteachadh èignichte clàraichte mar `platform/signing_key_rotate` ann an sreath sgrùdaidh an àrd-chabhsaire leis an adhbhar. Feumaidh an aon roghainn `QUIRE_MASTER_KEY` a bhith aig an neach-obrach agus aig an t-sreath-lìn gus an iuchair ùr a phasgadh; nì `bun run kek:rotate` airson an iuchair-mhaighstir ath-phasgadh air iuchraichean-soidhnidh còmhla ris a’ chòrr (`oauth_signing_key` ann an `SEALED_STORES`).

## Ruigsinneachd èiginn riochdachaidh <!--quire:break-glass-production-access-->

Chan eil ruigsinneachd sheasmhach gu riochdachadh aig duine sam bith. Nuair nach urrainn rudeigin feitheamh, bheir sealbhadair cead èiginn seachad: Consol Àrd-chabhsaire, Tèarainteachd, Ruigsinneachd èiginn.

- Tha raon aig cead (aon bhuidheann no clàr an àrd-chabhsaire), adhbhar co-dhiù 20 caractar ag ainmeachadh na tachartais no na tiogaid, agus uinneag 5 gu 240 mionaid. Thig e gu crìch leis fhèin: thèid sùil a thoirt air a’ ghleoc airson gach aithris.
- Faodar a chur chun an t-sealbhadair a dh’iarras e no gu sealbhadair eile (dòigh dithis). Chan urrainn ach don neach dha an deach a thoirt a chleachdadh. Feumar `platform/break_glass_issue` airson a thoirt seachad agus `platform/break_glass_use` airson a chleachdadh; ’s ann do shealbhadairean a-mhàin a tha an dà chuid mar bhun-roghainn.
- Bidh aithrisean a’ dol tron gheata seach logadh a-steach stòr-dàta: leughadh a-mhàin, aon aig aon àm, cuingichte ris a’ bhuidhinn no ris a’ chlàr smachd, le ùine-ama còig diogan agus 500 sreath aig a’ char as motha. Tha luachan dàna air an sealltainn a rèir meud.
- Clàraidh sreath sgrùdaidh an àrd-chabhsaire an cead (leis an adhbhar), a chùl-ghairm, gach aithris mus ruith i (`platform/break_glass_statement`, feadhainn a chaidh a dhiùltadh leis an toradh `denied`) agus gach toradh (`platform/break_glass_result`). Tha IDan inntrigidhean sgrùdaidh aig `ops.break_glass_statement`, agus mar sin thèid clàr an aontachaidh a cheangal ris na h-inntrigidhean sgrùdaidh aige.
- Chan eil sgrìobhadh ri fhaighinn. Airson atharrachadh nach urrainn feitheamh ri tionndadh, cleachdaidh an gnìomhaiche a ruigsinneachd stòr-dàta fhèin fo chlàr atharrachaidh fhèin, taobh a-muigh a’ bhathair seo; bu chòir don chlàr iomradh na tachartais a chaidh a chleachdadh an seo ainmeachadh.

Carson nach toir thu teisteanasan stòr-dàta seachad? Mairidh logadh a-steach PostgreSQL nas fhaide na an seisean a dh’iarr e, seachnaidh e tèarainteachd ìre-shreathan air a bheil an t-aplacaid an urra agus chan urrainn dha sgrìobhadh gu sreath sgrùdaidh a’ bhathair seo; cha bhiodh na h-aithrisean aige air an sgrùdadh nas fhaide na log an fhrithealaiche nam biodh cuideigin air a lìbhrigeadh. Nì an geata lorg an sgrùdaidh na phàirt den ruigsinneachd, seach cleachdadh mun cuairt oirre.

Gus freagairt a thoirt do dh’iarrtas sgrùdaidh: liostaich na ceadan san ùine (Ruigsinneachd èiginn), fosgail eachdraidh ceada airson na h-aithrisean agus IDan nan inntrigidhean sgrùdaidh aige, agus leugh na h-inntrigidhean sin ann an sreath sgrùdaidh an àrd-chabhsaire (`bun run audit:verify --platform` a’ dearbhadh gu bheil an t-sreath slàn).

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