---
title: "Pusingan kunci induk dan kunci tandatangan, serta akses break-glass"
description: "Pusingkan kunci induk yang melindungi kelayakan tersimpan, dan gunakan akses break-glass."
image: "https://docs.quirelms.com/og.png"
---

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

# Pusingan kunci induk dan kunci tandatangan, serta akses break-glass

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

Kawalan dalam 21-compliance.md seksyen 14 yang diminta oleh seorang juruaudit
mengikut nama. Halaman ini ialah prosedurnya; rekod yang dihasilkannya ialah
bukti.

## Kunci-kunci tersebut <!--quire:the-keys-->

Setiap kelayakan tersimpan disulitkan dengan satu kunci penyulitan data (DEK) yang
baharu. DEK dibungkus oleh kunci induk (KEK), dan rujukan kunci induk disimpan
sebelahnya (`key_ref`, atau rujukan di dalam satu nilai berpaket). Memusingkan kunci
induk membungkus semula DEK-DEK. Ia tidak pernah menyahsulit atau menyulit semula
satu kelayakan.

| Tetapan | Makna |
| --- | --- |
| `QUIRE_MASTER_KEY` | Kunci induk semasa: 32 bait, base64. Setiap rahsia baharu dibungkus di bawahnya |
| `QUIRE_MASTER_KEY_VERSION` | Label versinya. `v1` apabila tidak ditetapkan. Naikkan ia setiap kali anda mengubah kunci |
| `QUIRE_MASTER_KEY_RETIRED` | Kunci terdahulu yang mungkin masih menyimpan rahsia di bawahnya, sebagai `v1=<base64>,v0=<base64>`. Dibaca, tidak pernah ditulis |

Lapisan web, pekerja dan arahan `bun run kek:rotate` membaca ketiga-tiga tetapan ini.
Ketiga-tiganya mesti mempunyai nilai yang sama, atau salah satunya tidak dapat
membuka apa yang disulitkan oleh yang lain.

Tanpa `QUIRE_MASTER_KEY`, setiap subsistem mengekalkan kunci yang diturunkannya
daripada `QUIRE_SECRET_KEY`. Itu berfungsi, halaman Kesihatan platform
memaparkannya sebagai merosot, dan ia kekal boleh dibaca selepas anda menetapkan
satu kunci induk, yang merupakan cara pusingan pertama memindahkan segalanya
daripadanya. Sesiapa yang boleh membaca persekitaran proses boleh menyahsulit setiap
kelayakan tersimpan, jadi sebuah pemasangan produksi sepatutnya mempunyai satu kunci
induk, disimpan dalam satu kedai rahsia dan bukan dalam sandaran yang sama dengan
pangkalan data.

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

Umur kunci dipaparkan pada Konsol platform, Keselamatan, Kunci induk, dan sebagai
metrik `quire.secrets.master_key.age` (hari). Jadual harian `platform.key_age`
(03:41 UTC) menulis satu entri peringatan ke rantai audit platform apabila kunci
mencapai 365 hari, dan sekali lagi setiap 30 hari sehingga ia diputarkan. Putarkan
pada peringatan itu, dan setiap kali sebuah kunci mungkin telah terdedah.

1. Jana kunci baharu: `openssl rand -base64 32`.
2. Tetapkan `QUIRE_MASTER_KEY` kepadanya dan `QUIRE_MASTER_KEY_VERSION` kepada
   label seterusnya (`v2`). Pindahkan kunci lama ke `QUIRE_MASTER_KEY_RETIRED`
   sebagai `v1=<old base64>`. Simpan satu salinan kedua-duanya di tempat lain
   selain hos ini.
3. Lepaskan lapisan web dan pekerja dengan tetapan baharu. Rahsia baharu kini
   dibungkus di bawah `env:QUIRE_MASTER_KEY:v2`; yang lama masih dibuka melalui
   kunci yang bersara.
4. Minta pusingan tersebut, dengan sebab yang akan berada dalam jejak audit:
   - dalam konsol: Keselamatan, Kunci induk, Putarkan kunci induk; atau
   - pada satu shell dengan persekitaran yang sama:
     `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Pekerja membungkus semula satu hirisan seminit (jadual `platform.key_rotation`
   pada perancang) dan menyambung semula selepas satu permulaan semula. Untuk
   menyiapkannya dalam satu dudukan: `bun run kek:rotate run`. Pantau dengannya
   `bun run kek:rotate status`.
6. Apabila rekod menunjukkan pusingan selesai dengan **sifar tidak selesai dan
   sifar gagal**, buang kunci yang bersara daripada `QUIRE_MASTER_KEY_RETIRED`
   dan lepaskan semula. Sehingga itu, kekalkan ia: satu nilai yang tidak dapat
   dipindahkannya masih dibungkus di bawah kunci lama.

### Apa yang ditelusuri tugas itu <!--quire:what-the-job-walks-->

Setiap stor yang memegang satu DEK yang dibungkus: yang dalam `SEALED_STORES`
(`apps/worker/src/key-rotation.ts`). Stor pangkalan data kawalan ditelusuri pada
pangkalan data kawalan; stor organisasi ditelusuri satu organisasi pada satu masa
di bawah keselamatan tahap baris, dalam mana-mana pangkalan data yang memegang
organisasi tersebut, supaya sebuah penyewa yang disemat pada pangkalan data khusus
diputarkan dalam pangkalan data itu. Sebuah ujian gagal apabila skema memperoleh
satu lajad kunci berbungkus yang tidak dinamakan oleh senarai, dan satu lagi apabila
semakan kelayakan mengklasifikasikan satu lajad tersulit yang terlepas oleh
senarai.

### Rekod tersebut <!--quire:the-record-->

- `ops.key_rotation`: satu baris setiap pusingan, dengan sebabnya, siapa yang
  memintanya, statusnya dan jumlahnya (dibungkus semula, sudah semasa, tidak
  selesai, gagal).
- `ops.key_rotation_progress`: satu baris setiap stor dan skop sebaik sahaja
  ditelusuri, dengan rujukan kunci yang tidak dapat dibacanya dan berapa banyak
  nilai berada di bawah setiap satu. Sebuah pusingan yang disambung semula
  melangkau ini.
- Rantai audit platform: `platform/key_rotation_request` (dengan sebabnya), satu
  `platform/key_rotation_store` setiap stor dengan kiraannya, dan
  `platform/key_rotation_complete` atau `platform/key_rotation_fail`;
  `platform/key_age_reminder` untuk peringatan itu.
- Metrik: `quire.secrets.master_key.age` dan `quire.secrets.rewrap.outstanding`
  (nilai yang tidak dapat dipindahkan oleh pusingan terakhir).

### Apabila nilai tidak selesai <!--quire:when-values-are-unresolved-->

Satu nilai tidak selesai dibungkus di bawah satu rujukan kunci yang tidak dipegang
oleh pemasangan ini, atau bukan dalam bentuk yang dijanjikan oleh lajadnya. Rekod
kemajuan menamakan rujukan tersebut (contohnya
`env:QUIRE_MASTER_KEY:v0 (unreadable)`). Pulihkan kunci itu ke dalam
`QUIRE_MASTER_KEY_RETIRED` dan jalankan satu lagi pusingan, atau, jika kunci itu
hilang selama-lamanya, minta pentadbir organisasi tersebut memasukkan kelayakan
semula: ia kemudian disulitkan di bawah kunci semasa. Pusingan yang gagal
memaparkan ralatnya pada rekod tersebut; baiki puncanya dan minta semula.

## Kunci tandatangan <!--quire:signing-keys-->

Berasingan daripada kunci induk: setiap organisasi menandatangani token OpenID
Connect dan mesej LTI dengan kunci RSA-nya sendiri, diterbitkan di
`/.well-known/jwks.json`. Tiada apa-apa di sini memerlukan seorang pengendali.
Jadual setiap jam `platform.signing_keys` menerbitkan satu pengganti tujuh hari
sebelum sembilan puluh hari kunci semasa tamat, seminggu kemudian pengganti itu
mula menandatangani dan kunci lama menjadi bersara, dan sembilan puluh hari
selepas itu kunci lama dipadam dan meninggalkan set kunci. Setiap langkah ialah
satu entri `platform/signing_key_advance` pada rantai audit platform.

Untuk menggantikan kunci sebuah organisasi lebih awal, contohnya selepas satu
pendedahan:

- dalam konsol: Keselamatan, Kunci induk, Terbitkan satu kunci tandatangan baharu
  (memerlukan `platform/keys_manage`); atau
- pada satu shell dengan persekitaran pekerja:
  `bun run kek:rotate signing-keys rotate --tenant <slug or id> --reason "Key exposed, INC-3310"`.
  `bun run kek:rotate signing-keys status` menyenaraikan kunci setiap organisasi
  mengikut peringkat.

Kunci baharu diterbitkan serta-merta dan mula menandatangani selepas tujuh hari,
apabila kunci semasa bersara. Minggu itu adalah disengajakan: pihak yang bergantung
menyimpan set kunci dalam cache, dan satu pertindihan yang lebih pendek akan
menggagalkan setiap alat serentak. Kunci yang bersara kekal dalam set kunci selama
sembilan puluh hari lagi supaya token yang sudah ia tandatangani terus disahkan;
jika pendedahan bermakna ia mesti berhenti dipercayai lebih awal, memadam barisnya
ialah satu perubahan yang dibuat dengan akses pangkalan data pengendali sendiri di
bawah satu rekod perubahan (akses break-glass hanya baca), dan token yang
ditandatanganinya kemudian gagal pengesahan. Pusingan paksa ialah
`platform/signing_key_rotate` dalam rantai audit, dengan sebabnya. Pekerja
memerlukan tetapan `QUIRE_MASTER_KEY` yang sama seperti lapisan web untuk
membungkus kunci baharu; `bun run kek:rotate` untuk kunci induk membungkus semula
kunci tandatangan dengan segala-galanya yang lain (`oauth_signing_key` berada
dalam `SEALED_STORES`).

## Akses produksi break-glass <!--quire:break-glass-production-access-->

Tiada siapa yang memegang akses berterusan kepada produksi. Apabila sesuatu tidak
boleh menunggu, seorang pemilik mengeluarkan satu gerakan break-glass: Konsol
platform, Keselamatan, Akses break-glass.

- Satu gerakan mempunyai satu skop (satu organisasi, atau registri platform), satu
  sebab sekurang-kurangnya 20 aksara yang menamakan insiden atau tiket, dan satu
  tetingkap 5 hingga 240 minit. Ia tamat tempoh dengan sendirinya: ia disemak terhadap jam
  pada setiap pernyataan.
- Ia boleh dikeluarkan kepada pemilik yang mengeluarkannya, atau kepada pemilik
  lain (borang dua orang). Hanya orang ia dikeluarkan kepada yang boleh
  menggunakannya. Mengeluarkan memerlukan `platform/break_glass_issue` dan
  menggunakan memerlukan `platform/break_glass_use`; kedua-duanya hanya pemilik
  secara lalai.
- Pernyataan berjalan melalui gerbang, bukan pada satu log masuk pangkalan data:
  hanya baca, satu pada satu masa, terhad kepada organisasi atau registri kawalan,
  dengan satu had masa lima saat dan paling banyak 500 baris. Nilai binari
  dipaparkan mengikut saiz.
- Rantai audit platform merekodkan pengeluaran (dengan sebabnya), pembatalan, setiap
  pernyataan sebelum ia berjalan (`platform/break_glass_statement`, yang ditolak
  dengan hasil `denied`) dan setiap hasil (`platform/break_glass_result`).
  `ops.break_glass_statement` memegang id entri audit, jadi rekod pengeluaran
  bersambung kepada entri auditnya.
- Penulisan tidak ditawarkan. Satu perubahan yang tidak boleh menunggu satu
  keluaran menggunakan akses pangkalan data pengendali sendiri di bawah rekod
  perubahannya sendiri, di luar produk ini, dan rekod itu sepatutnya memetik rujukan
  insiden yang digunakan di sini.

Mengapa tidak mengeluarkan kelayakan pangkalan data: satu log masuk Postgres
mengatasi sesi yang memintanya, memintas keselamatan tahap baris yang bergantung
kepada aplikasi, dan tidak dapat menulis ke rantai audit produk ini, jadi
pernyataannya hanya akan diaudit setakat seseorang menghantar log pelayan. Gerbang
menjadikan jejak audit sebagai satu sifat akses dan bukan satu amalan di
sekelilingnya.

Untuk menjawab satu permintaan audit: senaraikan gerakan dalam tempoh tersebut
(Akses break-glass), buka sejarah satu gerakan untuk pernyataannya dan id entri
audit, dan baca entri-entri itu pada rantai audit platform
(`bun run audit:verify --platform` membuktikan rantai itu utuh).

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