---
title: "Rotation de la clé principale et des clés de signature, et accès d’urgence"
description: "Faire tourner la clé principale qui protège les justificatifs enregistrés et utiliser l’accès d’urgence."
image: "https://docs.quirelms.com/og.png"
---

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

# Rotation de la clé principale et des clés de signature, et accès d’urgence

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

Les contrôles de la section 14 de 21-compliance.md qu’un auditeur demande par leur nom. Cette page décrit la procédure; les dossiers qu’elle produit constituent les preuves.

## Les clés <!--quire:the-keys-->

Chaque justificatif enregistré est scellé avec une nouvelle clé de chiffrement des données (DEK). La clé DEK est enveloppée par la clé principale (la KEK), et la référence de la clé principale est conservée à côté (`key_ref`, ou la référence à l’intérieur d’une valeur empaquetée). La rotation de la clé principale réenveloppe les clés DEK. Elle ne déchiffre et ne chiffre jamais de nouveau un justificatif.

| Paramètre | Signification |
| --- | --- |
| `QUIRE_MASTER_KEY` | Clé principale actuelle : 32 octets en base64. Tous les nouveaux secrets sont enveloppés avec celle-ci |
| `QUIRE_MASTER_KEY_VERSION` | Étiquette de sa version. `v1` si elle n’est pas définie. Incrémentez-la à chaque changement de clé |
| `QUIRE_MASTER_KEY_RETIRED` | Anciennes clés pouvant encore protéger des secrets, sous la forme `v1=<base64>,v0=<base64>`. Elles servent à lire, jamais à écrire |

La couche Web, le processus de travail et la commande `bun run kek:rotate` lisent les trois mêmes paramètres. Ils doivent tous avoir les mêmes valeurs, sinon l’un d’eux ne pourra pas ouvrir ce qu’un autre a scellé.

Sans `QUIRE_MASTER_KEY`, chaque sous-système conserve la clé dérivée de `QUIRE_SECRET_KEY`. Cela fonctionne; la page de santé du système indique toutefois un état dégradé. La clé reste lisible après la définition d’une clé principale, ce qui permet à la première rotation de tout migrer. Toute personne capable de lire l’environnement du processus peut déchiffrer tous les justificatifs enregistrés; une installation de production devrait donc avoir une clé principale conservée dans un coffre de secrets, séparément de la sauvegarde de la base de données.

## Effectuer une rotation <!--quire:rotating-->

L’âge de la clé apparaît dans Console de plateforme, Sécurité, Clé principale, et sous la métrique `quire.secrets.master_key.age` (jours). La tâche quotidienne `platform.key_age` (03:41 UTC) ajoute une entrée de rappel à la chaîne d’audit de la plateforme lorsque la clé atteint 365 jours, puis tous les 30 jours jusqu’à sa rotation. Effectuez la rotation au rappel et chaque fois qu’une clé a pu être exposée.

1. Générez la nouvelle clé : `openssl rand -base64 32`.
2. Définissez `QUIRE_MASTER_KEY` sur sa valeur et `QUIRE_MASTER_KEY_VERSION` sur la prochaine étiquette (`v2`). Déplacez l’ancienne clé dans `QUIRE_MASTER_KEY_RETIRED` sous la forme `v1=<old base64>`. Gardez une copie des deux clés ailleurs que sur cet hôte.
3. Déployez la couche Web et le processus de travail avec les nouveaux paramètres. Les nouveaux secrets sont désormais enveloppés sous `env:QUIRE_MASTER_KEY:v2`; les anciens restent accessibles à l’aide de la clé retirée.
4. Demandez la rotation en indiquant la raison qui figurera dans le journal d’audit :
   - dans la console : Sécurité, Clé principale, Faire tourner la clé principale; ou
   - dans un terminal utilisant le même environnement : `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. Le processus de travail réenveloppe une partie à la fois chaque minute (tâche du planificateur `platform.key_rotation`) et reprend après un redémarrage. Pour tout terminer d’un coup : `bun run kek:rotate run`. Suivez l’avancement avec `bun run kek:rotate status`.
6. Lorsque le registre indique que la rotation est terminée avec **zéro élément non résolu et zéro échec**, retirez l’ancienne clé de `QUIRE_MASTER_KEY_RETIRED` et redéployez. Gardez-la jusque-là : toute valeur qu’elle n’a pas pu déplacer reste enveloppée avec cette ancienne clé.

### Parcours de la tâche <!--quire:what-the-job-walks-->

La tâche parcourt tous les stockages qui contiennent une DEK enveloppée, ceux de `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). Les stockages de la base de contrôle sont parcourus sur cette base; ceux des organisations le sont une organisation à la fois, sous la sécurité au niveau des lignes, dans la base qui contient l’organisation, afin qu’un locataire rattaché à une base dédiée y fasse l’objet de la rotation. Un test échoue si le schéma ajoute une colonne de clé enveloppée absente de la liste; un autre échoue si l’examen des justificatifs classe comme scellée une colonne oubliée.

### Registre <!--quire:the-record-->

- `ops.key_rotation` : une ligne par rotation, avec sa raison, la personne qui l’a demandée, son état et ses totaux (réenveloppés, déjà à jour, non résolus, échoués).
- `ops.key_rotation_progress` : une ligne par stockage et portée parcourus, avec les références de clés impossibles à lire et le nombre de valeurs sous chacune. Une rotation reprise ignore ces éléments.
- Chaîne d’audit de la plateforme : `platform/key_rotation_request` (avec la raison), une entrée `platform/key_rotation_store` par stockage avec ses nombres, puis `platform/key_rotation_complete` ou `platform/key_rotation_fail`; `platform/key_age_reminder` pour le rappel.
- Métriques : `quire.secrets.master_key.age` et `quire.secrets.rewrap.outstanding` (valeurs que la dernière rotation n’a pas pu déplacer).

### Valeurs non résolues <!--quire:when-values-are-unresolved-->

Une valeur non résolue est enveloppée avec une référence de clé absente de cette installation ou ne respecte pas la forme attendue par sa colonne. Le registre d’avancement indique la référence (par exemple `env:QUIRE_MASTER_KEY:v0 (unreadable)`). Rétablissez cette clé dans `QUIRE_MASTER_KEY_RETIRED` et lancez une nouvelle rotation ou, si elle est perdue définitivement, demandez à l’administrateur de l’organisation de saisir de nouveau le justificatif : il sera alors scellé avec la clé actuelle. Les rotations échouées indiquent leur erreur dans le registre; corrigez la cause, puis relancez-les.

## Clés de signature <!--quire:signing-keys-->

Indépendamment de la clé principale, chaque organisation signe ses jetons OpenID Connect et ses messages LTI avec sa propre clé RSA, publiée à `/.well-known/jwks.json`. Aucune intervention n’est nécessaire de votre part. La tâche horaire `platform.signing_keys` publie une nouvelle clé sept jours avant l’échéance des 90 jours de la clé actuelle; une semaine plus tard, la nouvelle clé commence à signer et l’ancienne passe à l’état de retrait; au bout de 90 jours, l’ancienne est supprimée du registre des clés. Chaque étape produit une entrée `platform/signing_key_advance` dans la chaîne d’audit de la plateforme.

Pour remplacer plus tôt la clé d’une organisation, par exemple après une exposition :

- dans la console : Sécurité, Clé principale, Publier une nouvelle clé de signature (nécessite `platform/keys_manage`); ou
- dans un terminal utilisant l’environnement du processus de travail : `bun run kek:rotate signing-keys rotate --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate signing-keys status` répertorie les clés de chaque organisation selon leur étape.

La nouvelle clé est publiée immédiatement et commence à signer après sept jours, au moment où l’ancienne est retirée. Ce délai d’une semaine est intentionnel : les parties utilisatrices mettent en cache le jeu de clés, et un chevauchement plus court fait échouer tous les outils à la fois. La clé retirée reste dans le jeu pendant 90 jours de plus afin que les jetons déjà signés continuent d’être vérifiés. Si l’exposition exige de cesser de lui faire confiance plus tôt, la suppression de sa ligne est une modification effectuée avec l’accès de l’exploitant à sa propre base de données, sous un registre de changements (l’accès d’urgence est en lecture seule); les jetons signés avec cette clé échoueront alors à la vérification. La rotation forcée est inscrite sous `platform/signing_key_rotate` dans la chaîne d’audit, avec sa raison. Le processus de travail a besoin des mêmes paramètres `QUIRE_MASTER_KEY` que la couche Web pour envelopper la nouvelle clé; la commande `bun run kek:rotate` pour la clé principale réenveloppe les clés de signature avec tout le reste (`oauth_signing_key` figure dans `SEALED_STORES`).

## Accès de production d’urgence <!--quire:break-glass-production-access-->

Personne ne détient un accès permanent à la production. Lorsqu’il faut agir sans attendre, un propriétaire accorde un accès d’urgence : Console de plateforme, Sécurité, Accès d’urgence.

- L’accès vise une portée (une organisation ou le registre de la plateforme), exige une raison d’au moins 20 caractères qui indique l’incident ou le billet, et dure de 5 à 240 minutes. Il expire automatiquement : l’heure est vérifiée à chaque instruction.
- Il peut être accordé à la personne propriétaire qui le crée ou à un autre propriétaire (procédure à deux personnes). Seule la personne désignée peut l’utiliser. L’émission exige `platform/break_glass_issue` et l’utilisation exige `platform/break_glass_use`; les deux autorisations sont réservées aux propriétaires par défaut.
- Les instructions passent par la passerelle, et non par une connexion à la base : elles sont en lecture seule, exécutées une à la fois, limitées à l’organisation ou au registre de contrôle, avec un délai maximal de cinq secondes et au plus 500 lignes. Les valeurs binaires sont affichées avec leur taille.
- La chaîne d’audit de la plateforme consigne l’émission (avec la raison), la révocation, chaque instruction avant son exécution (`platform/break_glass_statement`, y compris les refus avec le résultat `denied`) et chaque résultat (`platform/break_glass_result`). `ops.break_glass_statement` conserve les identifiants d’entrée d’audit; l’entrée d’émission peut ainsi être reliée à ses entrées d’audit.
- Aucune écriture n’est proposée. Pour un changement qui ne peut attendre une version, l’exploitant utilise son propre accès à la base sous son propre registre de changements, en dehors de ce produit; ce registre devrait citer la référence de l’incident indiquée ici.

Pourquoi ne pas distribuer des justificatifs de base de données? Une connexion PostgreSQL survit à la session qui l’a demandée, contourne la sécurité au niveau des lignes dont dépend l’application et ne peut pas écrire dans la chaîne d’audit de ce produit; ses instructions ne seraient donc vérifiables que si quelqu’un livrait le journal du serveur. La passerelle fait de la trace d’audit une caractéristique de l’accès lui-même, plutôt qu’une pratique parallèle.

Pour répondre à une demande d’audit : répertoriez les accès accordés pendant la période (Accès d’urgence), ouvrez l’historique d’un accès pour voir ses instructions et les identifiants d’entrée d’audit, puis lisez ces entrées dans la chaîne d’audit de la plateforme (`bun run audit:verify --platform` confirme l’intégrité de la chaîne).

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