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

Rota a clave mestra que protexe as credenciais almacenadas e utiliza o acceso de emerxencia.

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

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

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.

Xera a clave nova: openssl rand -base64 32.
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.
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.
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".
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.
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

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

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

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

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

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).