Rotació de la clau mestra i de les claus de signatura, i accés d’emergència

Roteu la clau mestra que protegeix les credencials desades i utilitzeu l’accés d’emergència.

Els controls que un auditor demana pel nom a 21-compliance.md, secció 14. Aquesta pàgina descriu el procediment; els registres que genera en són les proves.

Les claus

Cada credencial desada se segella amb una clau de xifratge de dades nova (DEK). La clau mestra (KEK) embolcalla la DEK, i la referència de la clau mestra es desa al seu costat (key_ref o la referència dins d’un valor empaquetat). Rotar la clau mestra torna a embolcallar les DEK. No desxifra ni torna a xifrar cap credencial.

Configuració	Significat
`QUIRE_MASTER_KEY`	Clau mestra actual: 32 bytes, base64. Amb aquesta clau s’embolcallen tots els secrets nous
`QUIRE_MASTER_KEY_VERSION`	Etiqueta de versió. Si no s’estableix, `v1`. Augmenteu-la cada vegada que canvieu la clau
`QUIRE_MASTER_KEY_RETIRED`	Claus anteriors que encara poden protegir secrets, en format `v1=<base64>,v0=<base64>`. Només es llegeixen, mai no s’hi escriu

La capa web, el worker i l’ordre bun run kek:rotate llegeixen els mateixos tres valors. Tots han de coincidir; altrament, algun no podrà obrir el que un altre ha segellat.

Si no s’estableix QUIRE_MASTER_KEY, cada subsistema conserva la clau que deriva de QUIRE_SECRET_KEY. Funciona; la pàgina de salut del sistema n’indica la degradació, i la clau continua sent llegible després d’establir-ne una de mestra, cosa que permet que la primera rotació la retiri completament. Qualsevol persona que pugui llegir les variables d’entorn del procés pot desxifrar totes les credencials desades; per això una instal·lació de producció ha de tenir una clau mestra, guardada en un magatzem de secrets i separada de la còpia de seguretat de la base de dades.

Rotar

L’antiguitat de la clau apareix a la consola de la plataforma, a Security, Master key, i a la mètrica quire.secrets.master_key.age (dies). La tasca diària platform.key_age (03:41 UTC) escriu un recordatori a la cadena d’auditoria de la plataforma quan la clau arriba als 365 dies i ho repeteix cada 30 dies fins que es rota. Feu la rotació quan aparegui el recordatori i sempre que hi hagi la possibilitat que la clau s’hagi exposat.

Genereu una clau nova: openssl rand -base64 32.
Establiu-hi QUIRE_MASTER_KEY i augmenteu QUIRE_MASTER_KEY_VERSION a la següent etiqueta (v2). Moveu l’antiga clau a QUIRE_MASTER_KEY_RETIRED com a v1=<old base64>. Deseu una còpia de totes dues claus fora d’aquest host.
Desplegueu la capa web i el worker amb els nous valors. Els secrets nous s’embolcallen amb env:QUIRE_MASTER_KEY:v2; els antics encara s’obren amb la clau retirada.
Sol·liciteu la rotació amb el motiu que ha de constar al registre d’auditoria:
- a la consola: Security, Master key, Rotate the master key; o
- en un terminal amb el mateix entorn: bun run kek:rotate request --reason "Annual rotation, ticket SEC-114".
El worker torna a embolcallar una part cada minut (segons la tasca de l’scheduler platform.key_rotation) i reprèn la feina després d’un reinici. Per acabar-ho d’una tirada, executeu bun run kek:rotate run. Consulteu-ne el progrés amb bun run kek:rotate status.
Quan el registre indiqui que la rotació s’ha completat amb zero pendents i zero errors, elimineu la clau retirada de QUIRE_MASTER_KEY_RETIRED i torneu a desplegar. Fins llavors, conserveu-la: els valors que no s’han pogut moure continuen protegits per l’antiga.

Què recorre la tasca

Tots els magatzems que contenen DEK embolcallades: els que enumera SEALED_STORES (apps/worker/src/key-rotation.ts). Els magatzems de la base de control es processen allà mateix; els dels registres de l’organització es recorren d’una organització en una, amb row-level security i dins de la base de dades corresponent. Per tant, també es rota a la base dedicada de qualsevol tenant assignat a una base pròpia. Una prova falla si l’esquema afegeix una columna amb una clau embolcallada que no apareix a la llista; una altra falla si la revisió de credencials classifica una columna segellada que la llista no inclou.

El registre

ops.key_rotation: una fila per rotació, amb el motiu, qui l’ha sol·licitat, l’estat i els totals (tornades a embolcallar, ja actuals, pendents i fallides).
ops.key_rotation_progress: una fila per magatzem i àmbit un cop recorreguts, amb les referències de clau que no s’han pogut llegir i el nombre de valors sota cadascuna. Una rotació represa salta aquestes files.
Cadena d’auditoria de la plataforma: platform/key_rotation_request (amb el motiu), un platform/key_rotation_store per magatzem amb els recomptes, i platform/key_rotation_complete o platform/key_rotation_fail; platform/key_age_reminder per al recordatori.
Mètriques: quire.secrets.master_key.age i quire.secrets.rewrap.outstanding (valors que l’última rotació no ha pogut moure).

Quan queden valors pendents

Un valor queda pendent si està embolcallat amb una referència de clau que aquesta instal·lació no té o si no segueix el format que indica la columna. El registre de progrés n’indica la referència (per exemple env:QUIRE_MASTER_KEY:v0 (unreadable)). Restaureu aquesta clau a QUIRE_MASTER_KEY_RETIRED i torneu a executar la rotació o, si s’ha perdut definitivament, feu que l’administrador de l’organització torni a introduir la credencial perquè se segelli amb la clau actual. El registre de les rotacions fallides n’indica l’error; resoleu-lo i torneu a sol·licitar la rotació.

Claus de signatura

Són independents de la clau mestra: cada organització signa els seus tokens OpenID Connect i els missatges LTI amb una clau RSA pròpia, publicada a /.well-known/jwks.json. No cal que intervingui cap operador. La tasca horària platform.signing_keys publica una clau successor set dies abans que la vigent compleixi noranta dies. Una setmana més tard, la nova clau comença a signar i l’antiga passa a estar en retirada; noranta dies després se suprimeix i deixa el conjunt de claus. Cada pas és un registre platform/signing_key_advance a la cadena d’auditoria de la plataforma.

Per substituir abans d’hora la clau d’una organització, per exemple si s’ha exposat:

a la consola: Security, Master key, Publish a new signing key (cal tenir platform/keys_manage); o bé
en un terminal amb l’entorn del worker: bun run kek:rotate signing-keys rotate --tenant <slug or id> --reason "Key exposed, INC-3310". bun run kek:rotate signing-keys status mostra les claus de totes les organitzacions i la seva fase.

La clau nova es publica immediatament i comença a signar al cap de set dies, quan es retira l’actual. La setmana de solapament és intencionada: les parts que confien en Quire guarden el conjunt de claus a la memòria cau i un solapament més curt provocaria errors en totes les eines alhora. La clau en retirada es conserva al conjunt durant noranta dies més perquè se segueixin verificant els tokens que ja havia signat. Si l’exposició obliga a deixar de confiar-hi abans, suprimiu-ne la fila amb l’accés propi de l’operador a la base de dades i un registre del canvi (l’accés d’emergència és només de lectura); aleshores fallen les verificacions dels tokens signats amb aquella clau. La rotació forçada queda a la cadena d’auditoria com a platform/signing_key_rotate, amb el motiu. Per embolcallar la clau nova, el worker necessita la mateixa configuració de QUIRE_MASTER_KEY que la capa web; l’ordre bun run kek:rotate de la clau mestra també embolcalla les claus de signatura amb la resta (oauth_signing_key forma part de SEALED_STORES).

Accés d’emergència a producció

Ningú no té accés permanent a producció. Si una incidència no pot esperar, un propietari concedeix accés d’emergència a Platform console, Security, Break-glass access.

Una concessió especifica l’àmbit (una organització o el registre de la plataforma), un motiu d’almenys 20 caràcters que indiqui l’incident o el tiquet i una durada d’entre 5 i 240 minuts. Caduca automàticament: es comprova l’hora a cada instrucció.
Es pot concedir al mateix propietari que la crea o a un altre propietari (modalitat de dues persones). Només la persona a qui s’ha concedit el permís el pot utilitzar. Per concedir-lo cal platform/break_glass_issue, i per utilitzar-lo platform/break_glass_use; de manera predeterminada tots dos permisos només són per a propietaris.
Les instruccions s’executen a través del gateway, no amb una sessió directa a la base de dades: només es pot llegir, una instrucció cada vegada, dins de l’organització o del registre de control, amb un temps d’espera de cinc segons i un màxim de 500 files. Els valors binaris es mostren amb la mida.
La cadena d’auditoria de la plataforma registra la concessió (amb el motiu), la revocació, cada instrucció abans d’executar-la (platform/break_glass_statement, amb el resultat denied per a les instruccions rebutjades) i cada resultat (platform/break_glass_result). ops.break_glass_statement desa els ID de les entrades d’auditoria; així, la concessió enllaça amb les entrades corresponents.
No es poden fer escriptures. Un canvi que no pugui esperar una versió s’ha de fer amb l’accés propi de l’operador a la base de dades, en un registre de canvi independent i fora d’aquest producte; aquest registre ha d’incloure la referència de l’incident que s’ha indicat aquí.

No es concedeixen credencials de base de dades perquè un inici de sessió de Postgres continua actiu més enllà de la sessió que l’ha demanat, evita la seguretat a nivell de fila de l’aplicació i no pot escriure a la cadena d’auditoria del producte. Les seves instruccions només apareixerien als registres del servidor, si algú els hagués publicat. El gateway fa que l’auditoria formi part de l’accés i no sigui només una pràctica que l’envolta.

Per respondre una petició d’auditoria, enumereu les concessions del període (Break-glass access), obriu l’historial d’una concessió per veure les instruccions i els ID de les entrades d’auditoria, i consulteu aquestes entrades a la cadena d’auditoria de la plataforma. bun run audit:verify --platform comprova la integritat de la cadena.