Kapela.Security.Encryption.Files 10.1.0

🔐 Kapela.Security.Encryption.Files

Extension fichiers de Kapela.Security.Encryption : chiffrez et stockez des fichiers dans un coffre sur disque, organisés en arborescence dérivée d'un GUID, puis rechargez-les en clair.

📦 Installation

dotnet add package Kapela.Security.Encryption.Files

Le package dépend de Kapela.Security.Encryption (chiffrement AES-GCM authentifié).

🚀 Utilisation

Le coffre (SaveVaultFile / LoadVaultFile — stockage auto-géré avec arborescence dérivée d'un Guid) s'utilise via le service injecté KapelaFilesVault, enregistré avec AddKapelaFilesVault. Pour un stockage à chemin libre, voir SaveFile / LoadFile, disponibles sur la façade statique EncryptionHelper ou sur tout EncryptionContext.

Enregistrer le coffre depuis la configuration (recommandé)

Liez les options à une section de configuration (par défaut FileVaultOptions) :

// appsettings.json
{
  "FileVaultOptions": {
    "RootFolderPath": "C:\\coffre",
    "Key": "ma-clé",              // optionnel — voir « Clé de chiffrement »
    "RequireDedicatedKey": true   // optionnel — interdit le repli sur la clé de l'application
  }
}

builder.Services.AddKapelaFilesVault(builder.Configuration);
// …ou avec un nom de section personnalisé :
builder.Services.AddKapelaFilesVault(builder.Configuration, "MonCoffre");

La propriété Key est marquée [Encrypted] : vous pouvez donc stocker la Key chiffrée (avec la clé par défaut de l'application) — dans appsettings.json comme via l'action de configuration. Elle est déchiffrée à l'enregistrement ; une valeur en clair est conservée telle quelle.

…ou depuis le Program.cs

Préconfigurez le dossier racine (et, optionnellement, la clé) une seule fois :

using Kapela.Security.Encryption.Files;

builder.Services.AddKapelaFilesVault(o =>
{
    o.RootFolderPath = @"C:\coffre";
    o.Key = "ma-clé"; // optionnel
});

Le coffre est enregistré en singleton. Seul RootFolderPath est obligatoire : AddKapelaFilesVault lève une ArgumentException s'il est null ou vide.

Enregistrer / recharger un fichier

Injectez KapelaFilesVault puis appelez SaveVaultFile / LoadVaultFile sans répéter le dossier racine :

public class MonService(KapelaFilesVault vault)
{
    public Guid Enregistrer(byte[] contenu) => vault.SaveVaultFile(contenu);
    public byte[] Recharger(Guid id)        => vault.LoadVaultFile(id);
}

SaveVaultFile chiffre le contenu, génère un Guid, écrit le fichier chiffré et retourne l'identifiant à conserver pour le relire.

La clé employée dépend du niveau de gestion retenu, décrit dans la section suivante.

🗝️ Clé de chiffrement

Le coffre résout sa clé à chaque appel, en descendant trois niveaux jusqu'à en trouver une. Vous choisissez le niveau en fonction du périmètre que doit couvrir une même clé :

Précédence : paramètre > options > clé par défaut de l'application. Une valeur null ou vide passe simplement au niveau suivant — les trois niveaux se combinent donc librement : un coffre avec une Key configurée accepte très bien des clés par appel pour les quelques fichiers qui le méritent. Le dernier repli, celui sur la clé de l'application, peut être interdit via RequireDedicatedKey (voir niveau 2).

Niveau 1 — clé par défaut de l'application

Sans clé nulle part, le coffre s'appuie sur la clé par défaut de l'application.

builder.Services.AddKapelaFilesVault(o => o.RootFolderPath = @"C:\coffre");

// …puis, par appel :
Guid id = vault.SaveVaultFile(contenu);
byte[] clair = vault.LoadVaultFile(id);

Niveau 2 — clé dédiée au coffre

Renseignez FileVaultOptions.Key à l'enregistrement du coffre : tous les fichiers sont alors chiffrés avec cette clé, distincte de celle de l'application.

builder.Services.AddKapelaFilesVault(o =>
{
    o.RootFolderPath = @"C:\coffre";
    o.Key = "clé-du-coffre";
});

Rappel : Key étant marquée [Encrypted], cette valeur peut être stockée chiffrée aussi bien ici que dans appsettings.json.

Le repli du niveau 1 a une contrepartie : une Key mal orthographiée, ou une section de configuration absente, passe silencieusement sur la clé applicative. Les nouveaux fichiers s'écrivent alors avec la mauvaise clé, et l'erreur ne se manifeste qu'à la relecture des anciens, sous forme de SecurityException. Pour les coffres dont la clé n'est pas négociable, activez le garde-fou :

builder.Services.AddKapelaFilesVault(o =>
{
    o.RootFolderPath = @"C:\coffre";
    o.Key = builder.Configuration["Coffre:Cle"];
    o.RequireDedicatedKey = true; // interdit le repli sur la clé de l'application
});

Avec RequireDedicatedKey = true, tout appel qui n'obtient de clé ni en paramètre ni dans les options lève une InvalidOperationException au lieu de se replier. Le contrôle a lieu à l'appel et non à l'enregistrement : la combinaison RequireDedicatedKey = true sans Key reste valide pour un coffre piloté exclusivement en niveau 3.

Niveau 3 — une clé par fichier

Passez la clé en paramètre : elle prime sur tout le reste, pour cet appel uniquement.

// Une clé dérivée du locataire : un fichier n'est relisible qu'avec la clé de son tenant.
Guid id = vault.SaveVaultFile(contenu, $"tenant-{tenantId}");
byte[] clair = vault.LoadVaultFile(id, $"tenant-{tenantId}");

Deux points à garder en tête :

• La clé n'est pas stockée avec le fichier. C'est à l'appelant de savoir la reproduire à la relecture (la dériver d'un identifiant métier, la conserver dans un coffre à secrets…). Une clé perdue = un fichier définitivement illisible : le chiffrement est authentifié, il n'y a pas de récupération partielle.
• Une mauvaise clé lève une SecurityException, elle ne rend jamais un contenu corrompu — la signature est vérifiée avant tout déchiffrement.

📁 Chemin libre (SaveFile / LoadFile)

Si vous voulez maîtriser entièrement l'emplacement et le nom du fichier (sans arborescence GUID), utilisez SaveFile / LoadFile. Le fichier est chiffré et écrit exactement au chemin fourni (les dossiers parents manquants sont créés) :

using var context = EncryptionHelper.CreateContext("ma-clé");

context.SaveFile(contenu, @"C:\coffre\contrats\2026\contrat-42.bin");
byte[] clair = context.LoadFile(@"C:\coffre\contrats\2026\contrat-42.bin");

// …également disponibles sur la façade statique
EncryptionHelper.SaveFile(contenu, @"C:\coffre\contrats\2026\contrat-42.bin");
byte[] clairBis = EncryptionHelper.LoadFile(@"C:\coffre\contrats\2026\contrat-42.bin");

Les trois niveaux de clé s'y retrouvent à l'identique, portés cette fois par le contexte de chiffrement : appeler SaveFile / LoadFile sur la façade statique EncryptionHelper correspond au niveau 1, sur un EncryptionContext créé une fois pour toutes au niveau 2, et sur un contexte créé par fichier au niveau 3.

🗂️ Arborescence de stockage

Pour répartir les fichiers et éviter les dossiers surchargés, le Guid (format "D") est découpé sur -. Chaque groupe sauf le dernier devient un niveau de dossier ; il y a donc autant de niveaux que de groupes moins un. Pour l'identifiant 89a1f524-c4ca-4078-b448-e61417052e70 :

C:\coffre\
└── 89a1f524\
    └── c4ca\
        └── 4078\
            └── b448\
                └── 89a1f524-c4ca-4078-b448-e61417052e70   ← fichier chiffré

• Niveaux de dossiers : les groupes du GUID, sauf le dernier (soit 4 niveaux pour un GUID standard).
• Nom du fichier : le GUID complet (format "D"), sans extension.

Les dossiers manquants sont créés automatiquement à l'enregistrement.

Pour obtenir le chemin complet d'un fichier sans accès disque (le fichier peut ne pas exister), utilisez vault.ResolveVaultPath(id).

⚠️ Gestion des erreurs

📄 Licence

MIT — Copyright (c) Kapela 2026