PD-243 — Specification canonique contractuelle¶

1. References¶

• Story: PD-243
• JIRA: PD-243
• Epic: PD-189 — CRYPTO
• Composant cible: derivation de cles applicative (ProbatioVault-app)
• Documents relies:
• Architecture cryptographique v4.1 (doc 42)
• Anomalie PD-34 (labels HKDF)
• Learnings: PD-34, PD-97, PD-242, PD-33

2. Objectif¶

Aligner contractuellement la derivation de K_auth avec la hierarchie de cles issue de K_master, et corriger l'anomalie de label HKDF Kdoc -> K_doc, sans regression sur les derivations existantes.

3. Description fonctionnelle¶

3.1 Exigences fonctionnelles normatives¶

3.2 Points a clarifier¶

4. Perimetre¶

4.1 Inclus¶

• Derivation contractuelle de K_auth depuis K_master via HKDF-SHA3-256
• Normalisation/correction des labels HKDF (Kdoc → K_doc) — breaking change
• Migration des documents existants vers le nouveau label K_doc (decision PO Gate 3 v1)
• Verification de non-regression des derivations existantes (hors K_doc qui change)
• Verification de determinisme, isolation cryptographique, et usage strict des constantes
• Centralisation des labels HKDF dans constants.ts

4.2 Exclu (hors perimetre)¶

• Modification du protocole SRP-6a backend
• Implementation backend complete de la derivation K_auth (story separee)
• Toute regle de gestion de rotation de cles non specifiee dans le besoin
• Zeroization totale en memoire des strings JavaScript (best-effort uniquement, cf. PD-97)

5. Parametres cryptographiques normatifs¶

6. Diagrammes¶

6.1 Sequence de derivation HKDF multi-plateforme¶

Ce diagramme illustre le flux de derivation des cles depuis K_master et la verification d'interoperabilite iOS/backend (INV-243-06, REQ-243-09).

sequenceDiagram
    participant App as ProbatioVault-app (iOS)
    participant Constants as constants.ts
    participant HKDF as HKDF-SHA3-256
    participant Backend as ProbatioVault-backend

    Note over App,Backend: Derivation K_auth (REQ-243-01..05, INV-243-01)

    App->>Constants: get HKDF_CONTEXT_AUTH
    Constants-->>App: "ProbatioVault::K_auth::v1" (INV-243-02)
    App->>HKDF: derive(K_master, salt=∅, info="ProbatioVault::K_auth::v1", len=32)
    HKDF-->>App: K_auth (32 bytes)

    Note over App,Backend: Derivation K_doc corrigee (REQ-243-06, INV-243-07)

    App->>Constants: get HKDF_CONTEXT_DOC
    Constants-->>App: "ProbatioVault::K_doc::v1" (correction Kdoc)
    App->>HKDF: derive(K_master, salt=∅, info="ProbatioVault::K_doc::v1", len=32)
    HKDF-->>App: K_doc (32 bytes)

    Note over App,Backend: Verification interop (INV-243-06, PROP-243-04)

    Backend->>HKDF: derive(K_master_test, salt=∅, info="ProbatioVault::K_auth::v1", len=32)
    HKDF-->>Backend: K_auth_backend (32 bytes)
    App->>HKDF: derive(K_master_test, salt=∅, info="ProbatioVault::K_auth::v1", len=32)
    HKDF-->>App: K_auth_ios (32 bytes)
    App-->>Backend: assert K_auth_ios == K_auth_backend (byte-a-byte)

6.2 Hierarchie de derivation des cles¶

Ce diagramme montre l'isolation cryptographique entre cles derivees d'un meme K_master (INV-243-03, PROP-243-02).

flowchart TD
    KM["K_master (32 bytes)<br/>IKM unique"]

    KM -->|"HKDF-SHA3-256<br/>info=ProbatioVault::K_auth::v1<br/>(REQ-243-05)"| KA["K_auth (32 bytes)"]
    KM -->|"HKDF-SHA3-256<br/>info=ProbatioVault::K_encryption::v1"| KE["K_encryption (32 bytes)"]
    KM -->|"HKDF-SHA3-256<br/>info=ProbatioVault::K_doc::v1<br/>(INV-243-07, correction PD-34)"| KD["K_doc (32 bytes)"]
    KM -->|"HKDF-SHA3-256<br/>info=ProbatioVault::K_share::v1"| KS["K_share (32 bytes)"]

    style KA fill:#4CAF50,color:#fff
    style KD fill:#FF9800,color:#fff
    style KE fill:#2196F3,color:#fff
    style KS fill:#9C27B0,color:#fff

    KA -.-|"INV-243-03: ≠"| KE
    KA -.-|"INV-243-03: ≠"| KD
    KE -.-|"INV-243-03: ≠"| KD

6.3 Migration du label K_doc (breaking change)¶

Ce diagramme illustre le processus de migration des documents existants suite a la correction du label Kdoc vers K_doc (REQ-243-11, INV-243-07).

sequenceDiagram
    participant Migration as Migration Service
    participant Constants as constants.ts
    participant HKDF as HKDF-SHA3-256
    participant DB as Documents existants

    Note over Migration,DB: Breaking change : Kdoc → K_doc (REQ-243-11)

    Migration->>DB: lister documents chiffres avec ancien label
    DB-->>Migration: documents[...]

    loop Pour chaque document
        Migration->>HKDF: derive(K_master, salt=∅, info="Kdoc", len=32)
        HKDF-->>Migration: K_doc_ancien
        Migration->>Migration: dechiffrer(document, K_doc_ancien)
        Migration->>Constants: get HKDF_CONTEXT_DOC
        Constants-->>Migration: "ProbatioVault::K_doc::v1"
        Migration->>HKDF: derive(K_master, salt=∅, info="ProbatioVault::K_doc::v1", len=32)
        HKDF-->>Migration: K_doc_nouveau
        Migration->>Migration: rechiffrer(document, K_doc_nouveau)
        Migration->>DB: update document
    end

    Migration->>Migration: nettoyage best-effort cles temporaires (INV-243-04)

7. Proprietes attendues¶

7.1 Securite¶

• PROP-243-01 (determinisme): meme IKM + memes parametres => meme sortie
• PROP-243-02 (domain separation): labels differents => sorties distinctes pour un meme IKM
• PROP-243-03 (coherence hierarchie): K_auth derive de K_master, pas du mot de passe

7.2 Interoperabilite¶

• PROP-243-04: iOS et backend doivent obtenir les memes sorties sur vecteurs communs

7.3 Hygiene memoire¶

• PROP-243-05: les donnees sensibles temporaires doivent etre effacees en best-effort en fin d'usage (y compris en erreur)

8. Contraintes¶

9. Hypotheses¶

10. Invariants de securite¶

11. Tests d'acceptation¶

12. Livrables¶

• Module deriveAuthKey() dans src/services/hkdf.ts
• Mise a jour de src/crypto/constants.ts avec HKDF_CONTEXT_AUTH
• Correction label KDOC → K_DOC dans hkdf.ts
• Re-export dans src/crypto/keys.ts
• Tests unitaires avec vecteurs HKDF
• Tests de non-regression K_encryption, K_doc, K_share
• Documentation mise a jour

13. Definition of Done¶

La story PD-243 est DONE si et seulement si:

• Tous les invariants INV-243-01 a INV-243-07 sont satisfaits
• Tous les tests TA-243-01 a TA-243-10 sont passes
• Les anomalies de labels HKDF (Kdoc -> K_doc) sont corrigees sans regression
• L'usage de constantes centralisees est verifie
• Pipeline CI/CD vert
• Code review approuvee

Matrice de tracabilite¶