---
title: "Rotación de claves mestras e de sinatura e acceso de emerxencia"
description: "Rota a clave mestra que protexe as credenciais almacenadas e utiliza o acceso de emerxencia."
image: "https://docs.quirelms.com/og.png"
---

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

# Rotación de claves mestras e de sinatura e acceso de emerxencia

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

Os controis da sección 14 de 21-compliance.md que un auditor pide polo seu nome. Esta páxina describe o procedemento; os rexistros que xera son as probas.

## As claves <!--quire:the-keys-->

Cada credencial almacenada cífrase cunha clave de cifrado de datos (DEK) nova. A clave mestra (KEK) cifra a DEK e a referencia da clave mestra gárdase ao seu carón (`key_ref` ou a referencia incluída nun valor empaquetado). Ao rotar a clave mestra, vólvense cifrar as DEK. Nunca se descifra nin se volve cifrar unha credencial.

| Axuste | Significado |
| --- | --- |
| `QUIRE_MASTER_KEY` | Clave mestra actual: 32 bytes en base64. Cifra todas as claves novas |
| `QUIRE_MASTER_KEY_VERSION` | Etiqueta da súa versión. `v1` se non se define. Auméntaa cada vez que cambies a clave |
| `QUIRE_MASTER_KEY_RETIRED` | Claves anteriores que aínda poden protexer segredos, co formato `v1=<base64>,v0=<base64>`. Só se len; nunca se escriben nelas |

A capa web, o traballador e o comando `bun run kek:rotate` len os mesmos tres axustes. Deben ter os mesmos valores ou algún deles non poderá abrir o que cifrou outro.

Se non se define `QUIRE_MASTER_KEY`, cada subsistema conserva a clave que deriva de `QUIRE_SECRET_KEY`. Funciona; a páxina de estado do sistema indícao como degradado e segue sendo lexible cando se establece unha clave mestra. Así é como a primeira rotación deixa de utilizala. Calquera persoa que poida ler o entorno do proceso pode descifrar todas as credenciais almacenadas; por iso, unha instalación de produción debería ter unha clave mestra gardada nun almacén de segredos e fóra da mesma copia de seguridade que a base de datos.

## Rotación <!--quire:rotating-->

A antigüidade da clave aparece na consola da plataforma, en Seguridade, Clave mestra, e na métrica `quire.secrets.master_key.age` (días). A tarefa diaria `platform.key_age` (03:41 UTC) escribe un recordatorio na cadea de auditoría da plataforma ao chegar a 365 días e, despois, cada 30 días ata que se rote. Rota a clave cando apareza o recordatorio e sempre que poida quedar exposta.

1. Xera a clave nova: `openssl rand -base64 32`.
2. Establece `QUIRE_MASTER_KEY` co seu valor e `QUIRE_MASTER_KEY_VERSION` coa seguinte etiqueta (`v2`). Traslada a clave anterior a `QUIRE_MASTER_KEY_RETIRED` co formato `v1=<old base64>`. Garda copias de ambas fóra deste host.
3. Despregue a capa web e o traballador cos axustes novos. A partir de agora, os segredos novos cífranse baixo `env:QUIRE_MASTER_KEY:v2`; os anteriores aínda se abren coa clave retirada.
4. Solicita a rotación cun motivo que quede rexistrado na auditoría:
   - na consola: Seguridade, Clave mestra, Rotar a clave mestra; ou
   - nun shell co mesmo entorno: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. O traballador volve cifrar unha porción por minuto (a tarefa do planificador `platform.key_rotation`) e retoma o traballo tras un reinicio. Para completalo dunha soa vez: `bun run kek:rotate run`. Consulta o progreso con `bun run kek:rotate status`.
6. Cando o rexistro indique que a rotación rematou con **zero sen resolver e cero fallos**, elimina a clave retirada de `QUIRE_MASTER_KEY_RETIRED` e volve despregar. Mantena ata entón: os valores que non puido migrar seguen cifrados coa clave anterior.

### O que percorre a tarefa <!--quire:what-the-job-walks-->

Percorre todos os almacéns con DEK cifradas: os que se inclúen en `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Os almacéns da base de datos de control percorren esa base; os almacéns das organizacións percorren unha organización cada vez, con seguridade a nivel de fila e na base de datos que lle corresponda, para que unha persoa inquilina vinculada a unha base dedicada rote nesa base. Unha proba falla se se engade ao esquema unha columna de clave cifrada que non aparece na lista, e outra falla se a revisión das credenciais clasifica unha columna cifrada que falta na lista.

### O rexistro <!--quire:the-record-->

- `ops.key_rotation`: unha fila por rotación, co motivo, quen a solicitou, o estado e os totais (cifradas de novo, xa actualizadas, sen resolver e fallidas).
- `ops.key_rotation_progress`: unha fila por almacén e ámbito percorridos, coas referencias das claves que non puido ler e o número de valores que utilizaba cada unha. Ao retomar unha rotación, estas filas permítenlle saltar o traballo xa feito.
- Cadea de auditoría da plataforma: `platform/key_rotation_request` (co motivo), un evento `platform/key_rotation_store` por almacén cos seus totais e `platform/key_rotation_complete` ou `platform/key_rotation_fail`; `platform/key_age_reminder` para os recordatorios.
- Métricas: `quire.secrets.master_key.age` e `quire.secrets.rewrap.outstanding` (valores que a última rotación non puido migrar).

### Se hai valores sen resolver <!--quire:when-values-are-unresolved-->

Un valor queda sen resolver se está cifrado cunha referencia de clave que esta instalación non ten ou se non ten o formato que espera a súa columna. O rexistro do progreso indica a referencia (por exemplo, `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Volve introducir a clave en `QUIRE_MASTER_KEY_RETIRED` e inicia outra rotación; se a clave se perdeu definitivamente, a persoa administradora da organización debe volver introducir a credencial, que se cifrará coa clave actual. Os rexistros de rotacións fallidas amosan o erro; corrixe a causa e volve solicitala.

## Claves de sinatura <!--quire:signing-keys-->

Estas claves son independentes da clave mestra: cada organización asina os seus tokens OpenID Connect e mensaxes LTI coa súa propia clave RSA, publicada en `/.well-known/jwks.json`.
Non é necesaria ningunha intervención da persoa operadora. A tarefa horaria `platform.signing_keys` publica unha clave sucesora sete días antes de que se cumpran os noventa días da actual; unha semana despois, a sucesora comeza a asinar e a anterior pasa a estar en retirada; ao cabo de noventa días elimínase a clave anterior e desaparece do conxunto. Cada paso deixa unha entrada `platform/signing_key_advance` na cadea de auditoría da plataforma.

Para substituír antes de tempo a clave dunha organización, por exemplo, se quedou exposta:

- na consola: Seguridade, Clave mestra, Publicar unha nova clave de sinatura (require `platform/keys_manage`); ou
- nun shell co entorno do traballador: `bun run kek:rotate signing-keys rotate
  --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate
  signing-keys status` enumera as claves de cada organización segundo a súa fase.

A clave nova publícase de inmediato e comeza a asinar sete días máis tarde, cando se retira a actual. Este prazo dunha semana é deliberado: as partes que verifican as sinaturas gardan en caché o conxunto de claves e un período de solapamento máis curto faría fallar todas as ferramentas á vez. A clave retirada permanece no conxunto durante 90 días máis para que se poidan verificar os tokens que xa asinou; se pola exposición cómpre deixar de confiar nela antes, a eliminación da súa fila realízase co acceso á base de datos propio da persoa operadora e cun rexistro de cambio (o acceso de emerxencia só permite lectura); a partir de entón, fallará a verificación dos tokens asinados con esa clave. A rotación forzada rexístrase como `platform/signing_key_rotate` na cadea de auditoría, xunto co motivo. O traballador precisa os mesmos axustes `QUIRE_MASTER_KEY` que a capa web para cifrar a nova clave; o comando `bun run kek:rotate` da clave mestra tamén volve cifrar as claves de sinatura xunto co resto (`oauth_signing_key` forma parte de `SEALED_STORES`).

## Acceso de emerxencia en produción <!--quire:break-glass-production-access-->

Ninguén ten acceso permanente á produción. Cando non se pode agardar, unha persoa propietaria concede acceso de emerxencia: consola da plataforma, Seguridade, Acceso de emerxencia.

- O permiso especifica un ámbito (unha organización ou o rexistro da plataforma), un motivo de polo menos 20 caracteres que identifique o incidente ou a incidencia e un período de 5 a 240 minutos. Caduca por si só: compróbase o reloxo con cada instrución.
- Pódese conceder á persoa propietaria que o emite ou a outra persoa propietaria (modalidade de dúas persoas). Só o destinatario pode utilizalo. Para concedelo requírese `platform/break_glass_issue` e para utilizalo `platform/break_glass_use`; de xeito predeterminado, ambos son exclusivos das persoas propietarias.
- As instrucións execútanse a través da pasarela e nunca mediante un inicio de sesión na base de datos: só lectura, unha á vez, limitada á organización ou ao rexistro de control, cun tempo límite de cinco segundos e un máximo de 500 filas. Os valores binarios móstranse co seu tamaño.
- A cadea de auditoría da plataforma rexistra a concesión (co motivo), a revogación, cada instrución antes de executala (`platform/break_glass_statement`, co resultado `denied` se se rexeita) e cada resultado (`platform/break_glass_result`). `ops.break_glass_statement` contén os identificadores das entradas de auditoría, polo que o rexistro da concesión se enlaza coas entradas correspondentes.
- Non se permite escribir. Se un cambio non pode agardar a unha versión, realízase co acceso propio da persoa operadora á base de datos, segundo o seu propio rexistro de cambios e fóra deste produto; ese rexistro debe citar a referencia do incidente utilizada aquí.

Por que non se conceden credenciais de base de datos: un inicio de sesión de Postgres dura máis que a sesión que o solicitou, evita a seguridade a nivel de fila na que confía a aplicación e non pode escribir na cadea de auditoría deste produto; as instrucións quedarían auditadas só ata onde chegase o rexistro do servidor enviado. A pasarela fai que a pista de auditoría forme parte inherente do acceso en vez de depender dunha práctica externa.

Para responder a unha solicitude de auditoría, enumera os permisos concedidos durante o período (Acceso de emerxencia), abre o historial dun deles para consultar as instrucións e os identificadores das entradas de auditoría, e revisa esas entradas na cadea de auditoría da plataforma (`bun run audit:verify --platform` comproba que a cadea estea intacta).

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