PD-41 — Créer service PRE avec NuCypher/Umbral (Proxy Re-Encryption) (EPIC : PD-189 — CRYPTO)¶

1. Objectif¶

Définir le contrat canonique d’un service de Proxy Re-Encryption (PRE) basé sur NuCypher/Umbral, fournissant des fonctions exposées et vérifiables permettant : - de générer des clés de re-chiffrement (re-encryption keys) via generateReKey(), - de re-chiffrer un chiffré (ciphertext) via reEncrypt() sans révéler le plaintext, - de valider la conformité cryptographique et structurelle des entrées/sorties,

afin de permettre le partage contrôlé de données chiffrées entre un propriétaire et un destinataire, avec exigences de sécurité, robustesse, auditabilité et prévisibilité contractuelle.

2. Périmètre / Hors périmètre¶

Périmètre¶

• Installation et disponibilité d’une bibliothèque Umbral compatible (langage/runtime à préciser).
• Définition d’une interface de service exposant au minimum :
• generateReKey()
• reEncrypt()
• validate() (validation des formats et propriétés attendues)
• Gestion de formats d’entrée/sortie explicitement définis (encodage, versionnage, champs requis).
• Vérification des préconditions cryptographiques (types de clés, paramètres, compatibilité).
• Gestion des erreurs et invariants de non-divulgation.
• Journalisation d’audit sans fuite de secrets.

Hors périmètre¶

• Choix et gestion du schéma de chiffrement des documents (AES-GCM, etc.) : hors périmètre.
• Gestion des identités/PKI, distribution de clés publiques, attestation : hors périmètre (sauf champs nécessaires au service).
• Politiques d’accès métier (qui a le droit de partager quoi) : hors périmètre.
• Réseau décentralisé NuCypher (staking, nodes, policies) : hors périmètre.
• Intégration UI/UX et workflows applicatifs : hors périmètre.
• Mesures de résistance à l’informatique quantique : hors périmètre.

3. Définitions¶

• PRE (Proxy Re-Encryption) : primitive cryptographique permettant à un proxy de transformer un ciphertext chiffré pour A en un ciphertext déchiffrable par B, sans apprendre le plaintext.
• Umbral : schéma PRE (NuCypher) basé sur des primitives ECC.
• Alice : propriétaire initial des données chiffrées.
• Bob : destinataire cible (lecteur autorisé).
• Proxy : service réalisant la transformation (re-encryption) sans accès au plaintext.
• ReKey / re-encryption key : artefact permettant la transformation A→B.
• Ciphertext : donnée chiffrée.
• Capsule : métadonnée cryptographique Umbral associée au ciphertext (structure exacte à préciser).
• KFrag / CFrag : fragments de rekey et de re-encryption (terminologie Umbral, structure à préciser).
• Validation : contrôles de format, version, cohérence, et propriétés cryptographiques exigées.

4. Invariants (non négociables)¶

1. Le service PRE ne doit jamais exposer, journaliser, ou dériver le plaintext à partir des entrées.
2. Le service PRE ne doit jamais exiger la fourniture de clés privées d’Alice ou de Bob.
3. Les entrées et sorties doivent être versionnées (formatVersion) pour garantir compatibilité et non-ambiguïté.
4. Toute opération doit être déterministe quant à la validation : mêmes entrées → mêmes résultats de validation (succès/échec).
5. Toute erreur doit être fail-closed : aucun résultat partiel ne doit être retourné comme valide.
6. Les artefacts cryptographiques (ReKey/CFrag/Capsule) doivent être liés à un identifiant de contexte unique contextId ; toute opération avec des artefacts portant un contextId absent, divergent ou multiple est rejetée.
7. Le service doit imposer des limites de taille sur toutes les entrées (champs, artefacts, requêtes, cardinalités) pour prévenir DoS ; tout dépassement entraîne un rejet PAYLOAD_TOO_LARGE fail-closed.
8. Le service doit produire des traces d’audit ne contenant aucun secret (pas de ciphertext, pas de capsules, pas de fragments en clair ; uniquement des identifiants et empreintes si nécessaires) et respectant les listes normatives des champs autorisés/interdits.

5. Flux nominaux¶

Flux N1 — Installation et disponibilité Umbral¶

1. Le service démarre et déclare la version de la bibliothèque Umbral utilisée.
2. Le service expose un endpoint/commande de health indiquant :
3. version du service,
4. version Umbral,
5. statut “prêt / non prêt”.

Flux N2 — generateReKey() (génération de re-encryption key)¶

1. Le client appelle generateReKey() avec :
2. la clé publique d’Alice,
3. la clé publique de Bob,
4. les paramètres cryptographiques requis (ex : seuil/parts si applicable),
5. un identifiant de contexte contextId.
6. Le service valide les formats, versions, et paramètres.
7. Le service produit un artefact de type ReKey (ou set de KFrags selon le schéma retenu).
8. Le service retourne la ReKey et ses métadonnées (formatVersion, identifiants, contraintes).

Flux N3 — reEncrypt() (transformation proxy)¶

1. Le client appelle reEncrypt() avec :
2. un ciphertext (ou composant PRE nécessaire),
3. une capsule Umbral associée,
4. une ReKey (ou KFrag requis),
5. un identifiant de contexte contextId.
6. Le service valide la cohérence de l’ensemble.
7. Le service produit un artefact de type ReEncryptedData (ex : CFrag ou structure équivalente).
8. Le service retourne le résultat re-chiffré et métadonnées (formatVersion, contraintes).

Flux N4 — validate() (validation)¶

1. Le client soumet un artefact (clé publique, ReKey/KFrag, capsule, CFrag, etc.).
2. Le service exécute la validation selon des règles explicites, incluant la cohérence du contextId.
3. Le service retourne un résultat : VALID ou INVALID + code(s) d’erreur.

5bis. Diagrammes¶

Diagramme de séquence — Flux N2 + N3 : génération ReKey et re-encryption¶

Ce diagramme illustre le flux nominal complet de partage PRE entre Alice et Bob via le Proxy. Les validations (INV-3 formatVersion, INV-6 contextId, INV-7 limites de taille) sont appliquées à chaque appel. Le Proxy ne voit jamais le plaintext (INV-1).

sequenceDiagram
    participant Client as Client (Backend)
    participant PRE as Service PRE (Proxy)
    participant Umbral as Bibliothèque Umbral

    Note over Client,Umbral: Flux N2 — generateReKey()
    Client->>PRE: generateReKey(alicePK, bobPK, threshold, contextId)
    PRE->>PRE: Valider formatVersion (INV-3), contextId (INV-6), tailles (INV-7)
    PRE->>PRE: Valider clés publiques Alice & Bob (E2)
    PRE->>PRE: Valider paramètres threshold t/n (E3)
    PRE->>Umbral: generate_kfrags(alicePK, bobPK, t, n)
    Umbral-->>PRE: KFrag set [n fragments]
    PRE->>PRE: Audit log (contextId, keyIds, horodatage) — INV-8
    PRE-->>Client: ReKey {formatVersion, kfrags, threshold, contextId}

    Note over Client,Umbral: Flux N3 — reEncrypt()
    Client->>PRE: reEncrypt(ciphertext, capsule, reKey/KFrag, contextId)
    PRE->>PRE: Valider formatVersion (INV-3), contextId cohérent (INV-6), tailles (INV-7)
    PRE->>PRE: Valider capsule & ciphertext (E5)
    PRE->>PRE: Valider ReKey compatible (E4)
    PRE->>Umbral: re_encrypt(capsule, kfrag)
    Note right of Umbral: Pas d’accès au plaintext (INV-1)
    Umbral-->>PRE: CFrag
    PRE->>PRE: Audit log (contextId, keyIds, horodatage) — INV-8
    PRE-->>Client: ReEncryptedData {formatVersion, cfrag, contextId}

Diagramme de séquence — Flux N4 : validation d’artefact¶

Le flux validate() vérifie la conformité structurelle et cryptographique d’un artefact sans opération de transformation. Aucune clé privée n’est requise (INV-2).

sequenceDiagram
    participant Client as Client (Backend)
    participant PRE as Service PRE (Proxy)

    Client->>PRE: validate(artefact)
    PRE->>PRE: Vérifier formatVersion = "PRE-1.0" (INV-3)
    PRE->>PRE: Vérifier artefactType ∈ {ReKey, Capsule, CFrag}
    PRE->>PRE: Vérifier contextId présent et valide (INV-6)
    PRE->>PRE: Vérifier encodage clés publiques (33 octets secp256k1)
    PRE->>PRE: Vérifier tailles champs ≤ limites (INV-7)

    alt Artefact conforme
        PRE-->>Client: VALID
    else Non conforme
        PRE-->>Client: INVALID + code(s) d’erreur (table normative §6)
    end
    PRE->>PRE: Audit log (contextId, artefactType, résultat) — INV-8

Diagramme d’états — Cycle de vie d’un artefact PRE¶

Un artefact PRE traverse plusieurs états, depuis sa création jusqu’à son utilisation pour le déchiffrement par le destinataire. L’invariant fail-closed (INV-5) garantit qu’aucun artefact ne peut atteindre un état valide sans passer toutes les validations.

stateDiagram-v2
    [*] --> Soumis : Client soumet l’artefact

    Soumis --> ValidationFormat : Contrôle formatVersion/scheme (INV-3)
    ValidationFormat --> Rejeté : Format invalide (E1)

    ValidationFormat --> ValidationContexte : Format OK
    ValidationContexte --> Rejeté : contextId absent/divergent (INV-6, E9)

    ValidationContexte --> ValidationCrypto : Contexte cohérent
    ValidationCrypto --> Rejeté : Clé/capsule/ReKey invalide (E2-E5)

    ValidationCrypto --> ValidationTaille : Crypto OK
    ValidationTaille --> Rejeté : Dépassement limites (INV-7, E7)

    ValidationTaille --> Valide : Toutes validations passées
    Valide --> Utilisé : Consommé par reEncrypt() ou déchiffrement

    Rejeté --> [*] : Fail-closed, aucun résultat partiel (INV-5)
    Utilisé --> [*]

    note right of Rejeté
        Aucun résultat partiel retourné.
        Audit log émis (INV-8).
    end note

6. Cas d’erreur¶

E1. Format inconnu / version non supportée : formatVersion absent ou invalide. - Résultat : rejet.

E2. Clé publique invalide : taille/courbe/encodage non conforme. - Résultat : rejet.

E3. Paramètres cryptographiques invalides : seuil/parts incohérents, valeurs hors bornes. - Résultat : rejet.

E4. ReKey invalide ou incompatible : ReKey/KFrag ne correspond pas au couple Alice/Bob ou au contexte. - Résultat : rejet.

E5. Capsule/Ciphertext invalide : structure manquante ou non cohérente. - Résultat : rejet.

E6. Échec cryptographique : erreur interne Umbral lors des opérations. - Résultat : rejet avec code générique non sensible.

E7. Entrée trop volumineuse : dépassement limite. - Résultat : rejet PAYLOAD_TOO_LARGE sans résultat partiel.

E8. Service non prêt : Umbral indisponible, configuration incorrecte. - Résultat : rejet avec état “non prêt”.

E9. Contexte invalide : contextId manquant, divergent entre artefacts, ou multiple. - Résultat : rejet avec code INVALID_CONTEXT.

Table des codes d’erreur PRE (normative)¶

Statut : NORMATIF — opposable contractuellement. Les messages peuvent varier mais les codes NE DOIVENT PAS varier.

Mapping normatif des cas d’erreur¶

Note d’audit — Testabilité du fail-closed sur erreur cryptographique interne (Umbral)¶

• L’exigence E6 / CA11 impose un rejet fail-closed sans résultat partiel en cas d’erreur interne Umbral.
• Aucune condition contractuelle ne permet de provoquer de façon déterministe une erreur interne Umbral en test/audit black-box ; TC-ERR-06 reste non déterministe.
• La conformité est couverte indirectement par les rejets systématiques sur paramètres/artefacts/contexte/tailles invalides (fail-closed cohérent).
• Cette limite de testabilité est acceptée sans remise en cause de l’exigence (gravité mineure).

Note d’audit — Rejet « Non autorisé » (E8) et périmètre PRE¶

• Le service PRE est cryptographique et n’embarque aucun mécanisme d’authentification/autorisation.
• Le rejet « Non autorisé » relève d’une couche applicative ou d’infrastructure amont et est hors périmètre du contrat PRE.
• Aucun critère d’acceptation ni scénario de test PRE ne s’y applique ; l’éventuel code NON_AUTHORIZED serait produit hors service PRE.

7. Critères d’acceptation (testables)¶

Validation / formats¶

CA1. Toute requête dont formatVersion est inconnu est rejetée. CA2. Toute clé publique invalide est rejetée. CA3. Toute ReKey incompatible avec les clés publiques fournies est rejetée. CA4. Toute capsule/ciphertext invalide est rejetée.

Fonctions¶

CA5. generateReKey() retourne un artefact ReKey conforme au format contractuel. CA6. reEncrypt() retourne un artefact re-chiffré conforme au format contractuel. CA7. validate() retourne VALID/INVALID avec des codes d’erreur stables.

Sécurité¶

CA8. Les logs/audits n’incluent aucun champ interdit (plaintext, payload, capsule/cfrag/kfrag complets, clés privées, secrets dérivés) et n’incluent que les champs autorisés (contextId, identifiants de clés, formatVersion, artefactType, code d’erreur, horodatage) ; tout champ non autorisé est interdit par défaut. CA9. Le service refuse toute opération nécessitant une clé privée. CA10. Le service applique des limites de taille (champs, artefacts, requête, cardinalité) et refuse au-delà avec PAYLOAD_TOO_LARGE. CA13. Les artefacts fournis partagent un contextId identique et valide, toute incohérence étant rejetée avec INVALID_CONTEXT.

Robustesse¶

CA11. En cas d’erreur Umbral, la réponse est un échec explicite sans résultat partiel. CA12. Le service expose un statut de readiness exact (prêt/non prêt). CA14. Les codes d’erreur renvoyés respectent la table normative et sont stables pour un même type d’erreur.

8. Scénarios de test (Given / When / Then)¶

S1 — Génération de ReKey nominale¶

Given une clé publique Alice valide et une clé publique Bob valide When generateReKey() est appelée avec des paramètres valides Then une ReKey conforme est retournée.

S2 — Re-encryption nominale¶

Given une ReKey valide, une capsule valide et un ciphertext valide When reEncrypt() est appelée Then un artefact re-chiffré conforme est retourné.

S3 — Validation de formatVersion¶

Given une requête avec formatVersion inconnue When validate() est appelée Then le résultat est INVALID avec code “UNSUPPORTED_VERSION”.

S4 — Clé publique invalide¶

Given une clé publique mal encodée When generateReKey() est appelée Then l’appel échoue avec code “INVALID_PUBLIC_KEY”.

S5 — ReKey incompatible¶

Given une ReKey générée pour Alice→Bob When reEncrypt() est appelée avec la clé publique de Charlie (mauvais destinataire) Then l’appel échoue avec code “REKEY_MISMATCH”.

S6 — Entrée trop volumineuse¶

Given une entrée dépassant la limite maximale When reEncrypt() est appelée Then l’appel échoue avec code “PAYLOAD_TOO_LARGE” (quel que soit le niveau de dépassement : champ, artefact ou requête).

S9 — Contexte incohérent¶

Given des artefacts PRE (ReKey, Capsule, CFrag) portant des contextId différents, absents ou multiples When generateReKey(), reEncrypt() ou validate() est appelée Then l’appel échoue avec code “INVALID_CONTEXT”.

S7 — Non-divulgation¶

Given un appel nominal à reEncrypt() When on inspecte les logs Then aucun ciphertext/capsule/cfrag/rekey complet n’apparaît en clair et seuls les champs autorisés figurent (contextId, identifiants de clés, formatVersion, artefactType, code d’erreur, horodatage).

S8 — Service non prêt¶

Given Umbral indisponible When generateReKey() est appelée Then l’appel échoue avec code “SERVICE_NOT_READY”.

9. Hypothèses explicites¶

H1. Le schéma PRE retenu est Umbral (NuCypher). H2. Les primitives exposées attendues sont generateReKey() et reEncrypt(). H3. Le format contractuel des artefacts PRE (capsule/kfrag/cfrag) est celui défini en annexe 11 (v1). H4. Les règles d'authentification/autorisation d'accès au service ne sont pas précisées. H5. Le service PRE est appelé uniquement depuis le backend (module interne) et n'est jamais exposé directement aux clients externes. L'authentification, l'autorisation et le rate limiting relèvent de la couche applicative amont.

10. Points à clarifier¶

1. Langage/runtime du service (Node.js, Rust, Python) et bibliothèque Umbral exacte.
2. Modèle PRE exact attendu :
3. usage de KFrags/CFrags,
4. seuil (t) / nombre de fragments (n),
5. nécessité de preuves (si supportées).
6. Formats contractuels : encodage (base64/hex), structure JSON/binaire, versionnage — définis en annexe 11 (v1) ; clarifier les évolutions ou version(s) ultérieures le cas échéant.
7. Quels artefacts sont fournis par le client vs générés par le service (capsule ? ciphertext ?).
8. Intégration avec le modèle ProbatioVault : quel identifiant de document/dossier doit lier le contexte PRE.
9. Politique de non-réutilisation : rekeys par document, par session, par destinataire, durée de validité.
10. Besoin de révocation et mécanisme de révocation (rekey invalidation).
11. Exigences de performance (latence, débit, taille max ciphertext/capsule).
12. Stratégie d’audit : quels événements doivent être journalisés (sans secrets) et durée de rétention.
13. AuthN/AuthZ : quel système (Keycloak/OIDC) et quels droits requis.
14. Exigences de confidentialité en transit (TLS/mTLS).
15. Besoin d’une validation cryptographique renforcée (preuves de correction) si disponible dans Umbral.
16. Compatibilité interop : version Umbral côté client/destinataire et exigences de compatibilité.

11. Annexe — Formats contractuels des artefacts PRE (v1)¶

11.1 Règles communes¶

• Encodage : JSON UTF-8 strict, sans champs additionnels hors liste ci-dessous. Les champs binaires sont encodés en base64url sans padding.
• Version : formatVersion est obligatoire et vaut "PRE-1.0".
• Schéma : scheme vaut "umbral-v1".
• Typage : artefactType ∈ {"ReKey", "Capsule", "CFrag"}.
• Clés publiques : ownerPublicKey, recipientPublicKey sont des clés ECC compressées 33 octets (secp256k1) encodées base64url (longueur attendue 44 caractères).
• Contexte obligatoire : contextId est une chaîne ASCII opaque (base64url autorisé) longueur 16 à 128 caractères, identique sur tous les artefacts d’une même opération. Toute absence ou divergence entraîne un rejet INVALID_CONTEXT.
• Scope complémentaire : scope optionnel, ASCII, longueur ≤ 128 (ne remplace pas contextId).

11.2 Artefact ReKey (KFrag set)¶

Objet JSON :

{
  "formatVersion": "PRE-1.0",
  "artefactType": "ReKey",
  "scheme": "umbral-v1",
  "ownerPublicKey": "<base64url 44>",
  "recipientPublicKey": "<base64url 44>",
  "threshold": { "t": <int ≥1>, "n": <int ≥ t ≤ 10> },
  "contextId": "<string 16-128 ASCII>",
  "scope": "<string ≤128> (optionnel)",
  "kfrags": ["<base64url>"] // longueur du tableau = n ; chaque élément ≤ 1024 octets décodés
}

11.3 Artefact Capsule¶

Objet JSON :

{
  "formatVersion": "PRE-1.0",
  "artefactType": "Capsule",
  "scheme": "umbral-v1",
  "ownerPublicKey": "<base64url 44>",
  "contextId": "<string 16-128 ASCII>",
  "ciphertextDigest": "<base64url 32>",   // SHA-256 du ciphertext associé
  "capsule": "<base64url>",               // capsule Umbral brute ≤ 1024 octets décodés
  "scope": "<string ≤128> (optionnel)"
}

11.4 Artefact ReEncryptedData (CFrag)¶

Objet JSON :

{
  "formatVersion": "PRE-1.0",
  "artefactType": "CFrag",
  "scheme": "umbral-v1",
  "ownerPublicKey": "<base64url 44>",
  "recipientPublicKey": "<base64url 44>",
  "contextId": "<string 16-128 ASCII>",
  "capsuleDigest": "<base64url 32>",      // SHA-256 de la capsule source
  "threshold": { "t": <int ≥1>, "n": <int ≥ t ≤ 10> },
  "cfrag": "<base64url>",                 // fragment re-chiffré ≤ 1024 octets décodés
  "scope": "<string ≤128> (optionnel)"
}

11.5 Validation contractuelle associée¶

• Tout artefact dont formatVersion, scheme, artefactType ou longueur de clé publique ne respecte pas ces contraintes est rejeté (E1/E2).
• Toute ReKey avec threshold incohérent (t > n, n > 10, kfrags manquants ou en excès) est rejetée (E3/E4).
• Toute Capsule ou CFrag sans digest conforme (32 octets décodés) ou sans lien cohérent avec les clés fournies est rejetée (E4/E5).
• Tout artefact sans contextId valide (16-128 ASCII) ou présentant une divergence de contextId au sein d’une même opération est rejeté (E10).
• Les critères d’acceptation CA5 et CA6 s’entendent conformes à ces structures (champs présents, encodage/tailles respectés).

12. Annexe B — Seuils de taille conseillés (informatif)¶

Statut : INFORMATIF — non opposable contractuellement. Ces seuils de référence recommandés soutiennent l’Invariant 7 et visent un équilibre sécurité/performance/interop.

B.1 Seuils conseillés par champ¶

B.2 Seuils conseillés par artefact PRE¶

B.3 Seuils conseillés par requête¶

B.4 Encodage et mesure de taille¶

Les seuils s’appliquent après décodage effectif (ex. base64) et peuvent être contrôlés avant décodage pour prévenir l’inflation d’encodage.

B.5 Cardinalité des éléments¶

13. Annexe C — Politique de log/audit (normative)¶

• Champs interdits en log/audit (liste normative, interdiction stricte) : plaintext, payload, capsule complète, kfrag/cfrag complets, clés privées, secrets dérivés.
• Champs autorisés en log/audit (liste normative) : contextId, identifiants de clés (issuerKeyId, recipientKeyId), formatVersion, artefactType, operationType, code d’erreur, horodatage. Tout champ non explicitement autorisé est interdit par défaut.
• Granularité minimale d’audit attendue :
• chaque opération PRE (succès ou échec) produit une entrée d’audit ;
• aucune donnée sensible ne doit apparaître ;
• niveau de détail constant (pas de log debug conditionnel ou variable selon l’erreur).