---
title: "Ратацыя галоўнага ключа і ключоў подпісу, аварыйны доступ"
description: "Ратуйце галоўны ключ, які абараняе захаваныя ўліковыя даныя, і карыстайцеся аварыйным доступам."
image: "https://docs.quirelms.com/og.png"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/be/llms.txt
> Use this file to discover all available pages before exploring further.
# Ратацыя галоўнага ключа і ключоў подпісу, аварыйны доступ
Кантролі, названыя ў раздзеле 14 дакумента 21-compliance.md, правяраюцца аўдытарам. Гэтая старонка апісвае працэдуру; доказы — запісы, якія яна стварае.
## Ключы
Кожныя захаваныя ўліковыя даныя запячатваюцца новым ключом шыфравання даных (DEK). Галоўны ключ (KEK) абгортвае DEK, а спасылка на галоўны ключ захоўваецца побач (`key_ref` або ўнутры запакаванай велічыні). Ратацыя галоўнага ключа паўторна абгортвае DEK. Уліковыя даныя ніколі не расшыфроўваюцца і не шыфруюцца нанова.
| Параметр | Значэнне |
| --- | --- |
| `QUIRE_MASTER_KEY` | Бягучы галоўны ключ: 32 байты, base64. Ім абгортваецца кожны новы сакрэт |
| `QUIRE_MASTER_KEY_VERSION` | Пазнака версіі. Калі не зададзена — `v1`. Павялічвайце яе пры кожнай змене ключа |
| `QUIRE_MASTER_KEY_RETIRED` | Старыя ключы, якімі яшчэ могуць быць запячатаны сакрэты, у фармаце `v1=,v0=`. Толькі чытанне, запісваць нельга |
Вэб-узровень, worker і каманда `bun run kek:rotate` чытаюць адны і тыя ж тры налады. Іх значэнні павінны супадаць, інакш адзін з кампанентаў не зможа адкрыць тое, што запячатаў іншы.
Без `QUIRE_MASTER_KEY` кожная падсістэма працягвае выкарыстоўваць ключ, вытворны ад `QUIRE_SECRET_KEY`. Гэта працуе, але старонка стану сістэмы паказвае пагаршэнне; пасля задання галоўнага ключа даныя па-ранейшаму чытаюцца, каб першая ратацыя магла перанесці ўсё пад яго. Любы, хто можа чытаць асяроддзе працэсу, здольны расшыфраваць усе захаваныя ўліковыя даныя; таму вытворчае ўсталяванне павінна мець галоўны ключ у сховішчы сакрэтаў, асобна ад рэзервовай копіі базы.
## Ратацыя
Узрост ключа паказваецца ў кансолі платформы, у раздзеле Security, Master key, і метрыцы `quire.secrets.master_key.age` (дні). Штодзённы расклад `platform.key_age` (03:41 UTC) запісвае напамін у ланцуг аўдыту платформы, калі ключу спаўняецца 365 дзён, а затым кожныя 30 дзён да ратацыі. Ратуйце ключ пасля напаміну і кожны раз, калі ён мог быць раскрыты.
1. Стварыце новы ключ: `openssl rand -base64 32`.
2. Задайце для яго `QUIRE_MASTER_KEY`, а для `QUIRE_MASTER_KEY_VERSION` — наступную пазнаку (`v2`). Перанясіце стары ключ у `QUIRE_MASTER_KEY_RETIRED` як `v1=`. Захоўвайце абедзве копіі ў месцы па-за гэтым хостам.
3. Разгарніце вэб-узровень і worker з новымі наладамі. Новыя сакрэты будуць абгортвацца пад `env:QUIRE_MASTER_KEY:v2`; старыя па-ранейшаму адкрываюцца праз выведзены ключ.
4. Запытайце ратацыю і пакажыце прычыну, якая застанецца ў аўдыце:
- у кансолі: Security, Master key, Rotate the master key; або
- у абалонцы з тым жа асяроддзем: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Worker абгортвае нанова частку даных раз у хвіліну (расклад планавальніка `platform.key_rotation`) і працягвае пасля перазапуску. Каб завяршыць за адзін запуск: `bun run kek:rotate run`. Сачыце за працэсам праз `bun run kek:rotate status`.
6. Калі запіс паказвае завершаную ратацыю з **нулявымі нявырашанымі і няўдалымі**, выдаліце стары ключ з `QUIRE_MASTER_KEY_RETIRED` і разгарніце зноў. Да гэтага часу захоўвайце яго: значэнне, якое не ўдалося перанесці, па-ранейшаму зашыфравана старым ключом.
### Што апрацоўвае заданне
Кожнае сховішча з абгорнутым DEK: пералік знаходзіцца ў `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Сховішчы базы кіравання апрацоўваюцца ў ёй; сховішчы арганізацый — па адной арганізацыі пад абаронай на ўзроўні радкоў, у той базе, дзе яна захоўваецца, таму кліент з выдзеленай базай ратуецца ў сваёй базе. Тэст падае, калі ў схеме з'яўляецца слупок з абгорнутым ключом, якога няма ў пераліку; яшчэ адзін тэст выяўляе, калі праверка ўліковых даных знаходзіць запячатаны слупок, прапушчаны пералікам.
### Запіс
- `ops.key_rotation`: адзін радок на ратацыю з прычынай, аўтарам запыту, станам і агульнымі вынікамі (пераабгорнута, ужо актуальнае, не вырашана, няўдала).
- `ops.key_rotation_progress`: радок на сховішча і абсяг пасля апрацоўкі з ключавымі спасылкамі, якія не ўдалося прачытаць, і колькасцю значэнняў пад кожнай. Працягнутая ратацыя прапускае іх.
- Ланцуг аўдыту платформы: `platform/key_rotation_request` з прычынай, `platform/key_rotation_store` для кожнага сховішча з вынікамі, і `platform/key_rotation_complete` або `platform/key_rotation_fail`; `platform/key_age_reminder` для напамінаў.
- Метрыкі: `quire.secrets.master_key.age` і `quire.secrets.rewrap.outstanding` (значэнні, якія апошняя ратацыя не змагла перанесці).
### Калі засталіся нявырашаныя значэнні
Нявырашанае значэнне зашыфравана ключом, якога няма ў гэтым усталяванні, або не адпавядае форме, абяцанай яго слупком. Запіс прагрэсу паказвае спасылку (напрыклад, `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Вярніце гэты ключ у `QUIRE_MASTER_KEY_RETIRED` і паўтарыце ратацыю або, калі ключ страчаны назаўсёды, папрасіце адміністратара арганізацыі ўвесці ўліковыя даныя зноў; яны будуць запячатаны бягучым ключом. У запісе няўдалай ратацыі паказваецца памылка: выпраўце прычыну і паўтарыце запыт.
## Ключы подпісу
Асобна ад галоўнага ключа: кожная арганізацыя падпісвае свае токены OpenID Connect і паведамленні LTI ўласным RSA-ключом, апублікаваным па адрасе `/.well-known/jwks.json`. Умяшанне аператара не патрабуецца. Штогадзінны расклад `platform.signing_keys` публікуе наступны ключ за сем дзён да заканчэння 90-дзённага тэрміну бягучага; праз тыдзень наступны ключ пачынае падпісваць, а стары становіцца папярэднім; праз яшчэ 90 дзён стары ключ выдаляецца з набору. Кожны крок запісваецца ў ланцуг аўдыту платформы пад `platform/signing_key_advance`.
Каб раней замяніць ключ арганізацыі, напрыклад пасля яго раскрыцця:
- у кансолі: Security, Master key, Publish a new signing key (патрэбна `platform/keys_manage`); або
- у абалонцы з асяроддзем worker: `bun run kek:rotate signing-keys rotate
--tenant --reason "Key exposed, INC-3310"`. `bun run kek:rotate
signing-keys status` пералічвае стадыі ключоў кожнай арганізацыі.
Новы ключ публікуецца адразу і пачынае падпісваць праз сем дзён, калі стары пераходзіць у стан папярэдняга. Гэты тыдзень патрэбны, бо атрымальнікі кэшуюць набор ключоў; карацейшае перакрыццё парушыла б усе інтэграцыі адначасова. Стары ключ застаецца ў наборы яшчэ 90 дзён, каб токены, якія ён ужо падпісаў, можна было правяраць. Калі праз раскрыццё яму трэба хутчэй перастаць давяраць, аператар можа выдаліць яго радок уласным доступам да базы ў межах запісанай змены (аварыйны доступ толькі для чытання); тады праверка токенаў, падпісаных гэтым ключом, не пройдзе. Прымусовая ратацыя запісваецца ў аўдыце як `platform/signing_key_rotate` з указаннем прычыны. Worker павінен мець тыя ж налады `QUIRE_MASTER_KEY`, што і вэб-узровень, каб абгарнуць новы ключ; `bun run kek:rotate` для галоўнага ключа пераабгортвае ключы подпісу разам з астатнімі (`oauth_signing_key` знаходзіцца ў `SEALED_STORES`).
## Аварыйны вытворчы доступ
Ніхто не мае сталага доступу да вытворчага асяроддзя. Калі нельга чакаць, уладальнік выдае аварыйны дазвол: кансоль платформы, Security, Break-glass access.
- Дазвол мае абсяг (адна арганізацыя або рэестр платформы), прычыну даўжынёй не менш за 20 сімвалаў з пазначэннем інцыдэнту або заяўкі і тэрмін ад 5 да 240 хвілін. Ён заканчваецца аўтаматычна; праверка выконваецца паводле гадзінніка для кожнага запыту.
- Дазвол можна выдаць сабе або іншаму ўладальніку (працэдура з удзелам двух людзей). Карыстацца ім можа толькі атрымальнік. Выдача патрабуе `platform/break_glass_issue`, выкарыстанне — `platform/break_glass_use`; па змаўчанні абодва дазволы толькі для ўладальнікаў.
- Запыты выконваюцца праз шлюз, а не праз злучэнне з базай: толькі чытанне, па адным, з абмежаваннем адной арганізацыяй або рэестрам кіравання, з тайм-аўтам 5 секунд і максімумам 500 радкоў. Двайковыя значэнні паказваюцца памерам.
- Ланцуг аўдыту платформы запісвае выдачу (з прычынай), адкліканне, кожны запыт перад выкананнем (`platform/break_glass_statement`, адхіленыя — з вынікам `denied`) і кожны адказ (`platform/break_glass_result`). У `ops.break_glass_statement` захоўваюцца ID запісаў аўдыту, таму запіс выдачы звязваецца з імі.
- Запіс прапаноўваць нельга. Калі змена не можа чакаць выпуску, аператар выкарыстоўвае ўласны доступ да базы ў межах асобнага запісу аб змене па-за гэтым прадуктам; у ім варта спаслацца на інцыдэнт, пазначаны тут.
Навошта не выдаваць уліковыя даныя базы: доступ Postgres перажывае сеанс, які запатрабаваў яго, абыходзіць бяспеку на ўзроўні радкоў, на якую абапіраецца праграма, і не можа запісаць у журнал аўдыту прадукта. Таму запыты аўдытуюцца толькі ў той ступені, у якой захаваны серверны журнал. Шлюз робіць аўдыт уласцівасцю самога доступу, а не працэдурай вакол яго.
Каб адказаць на запыт аўдыту: пералічыце дазволы за перыяд (Break-glass access), адкрыйце гісторыю дазволу з запытамі і ID запісаў аўдыту, а затым прачытайце гэтыя запісы ў ланцугу аўдыту платформы (`bun run audit:verify --platform` пацвярджае яго цэласнасць).
Source: https://docs.quirelms.com/be/ops/key-rotation/index.mdx