Kapela.Security.Encryption 10.0.3

🔐 Kapela.Security.Encryption

Protégez les données sensibles de votre application .NET — mots de passe, chaînes de connexion, clés d'API — en les chiffrant directement dans votre configuration.

📦 Installation

dotnet add package Kapela.Security.Encryption

🗝️ Clé de chiffrement

Deux moyens de fournir la clé de chiffrement de votre application :

1. Au démarrage via SetEncryptionKey :

// Program.cs — à appeler avant AddKapelaEncryption
EncryptionHelper.SetEncryptionKey("MaCléPersonnalisée");

builder.Services.AddKapelaEncryption(builder.Configuration.Get<AppSettings>() ?? new());

2. Via la variable d'environnement KAPELA_ENCRYPTION_KEY, lue automatiquement au démarrage si SetEncryptionKey n'est pas appelé. Recommandé en production lorsque la clé est gérée par un secret manager ou une variable de pipeline :

export KAPELA_ENCRYPTION_KEY="MaCléPersonnalisée"

⚠️ La même clé doit être utilisée pour chiffrer et déchiffrer une valeur. Conservez-la précieusement (variable d'environnement, secret manager).

✏️ Chiffrement et déchiffrement

Opérations de base sur une valeur :

using Kapela.Security.Encryption;

string encrypted = EncryptionHelper.Encrypt("MonMotDePasse");
string plain     = EncryptionHelper.Decrypt(encrypted);

Versions sans exception, pratiques dans les initialisations :

if (EncryptionHelper.TryEncrypt("MonMotDePasse", out string encrypted)) { }
if (EncryptionHelper.TryDecrypt(encrypted, out string plain)) { }

🏷️ Déchiffrement automatique avec [Encrypted]

Décorez les propriétés sensibles de votre objet de configuration. AddKapelaEncryption les déchiffre automatiquement et enregistre l'objet comme singleton — en une seule ligne.

1. Déclarer le modèle

public class AppSettings
{
    public string ApiUrl { get; set; } = string.Empty;

    [Encrypted]
    public string ApiKey { get; set; } = string.Empty;

    [Encrypted]
    public SmtpSettings Smtp { get; set; } = new();
}

public class SmtpSettings
{
    public string Host { get; set; } = string.Empty;
    public int Port { get; set; }
    public string Username { get; set; } = string.Empty;

    [Encrypted]
    public string Password { get; set; } = string.Empty;
}

2. Enregistrer via l'injection de dépendances

// Program.cs
EncryptionHelper.SetEncryptionKey("MaCléPersonnalisée");

builder.Services.AddKapelaEncryption(builder.Configuration.Get<AppSettings>() ?? new());
// ✅ Les propriétés ApiKey et Smtp.Password sont déchiffrées
//    et AppSettings est enregistré comme singleton
// ⚠️ Smtp doit être décoré avec [Encrypted] pour que la récursion s'applique

3. Consommer dans un service

public class MonService(AppSettings settings)
{
    // ✅ settings.ApiKey est déjà déchiffré
}

Comportement en cas d'échec de déchiffrement

[Encrypted(EncryptedAttributeModes.KeepValue)]
public string ApiKey { get; set; } = string.Empty;

[Encrypted(EncryptedAttributeModes.ReplaceByEmpty)]
public string Secret { get; set; } = string.Empty;

Profondeur de récursion

AddKapelaEncryption descend jusqu'à 5 niveaux d'imbrication par défaut. Ce seuil est configurable via ParseObject si vous gérez le déchiffrement manuellement :

EncryptionHelper.ParseObject(settings, maxLevel: 10);

💡 La récursion ne s'applique qu'aux propriétés explicitement décorées avec [Encrypted]. Un objet imbriqué non décoré est ignoré, même s'il contient lui-même des propriétés [Encrypted].

🔀 Contexte de chiffrement indépendant

CreateContext crée un EncryptionContext isolé, avec sa propre clé, sans affecter le contexte global. Utile quand une application gère plusieurs clés simultanément (ex. migration, multi-tenant).

using Kapela.Security.Encryption;

using var ctx = EncryptionHelper.CreateContext("AutreCléPersonnalisée");

string encrypted = ctx.Encrypt("MonSecret");
string plain     = ctx.Decrypt(encrypted);

// Toutes les méthodes du contexte principal sont disponibles
ctx.ParseObject(settings);
string cs = ctx.GetConnectionString(configuration, "Default");

EncryptionContext est IDisposable — utilisez-le dans un bloc using.

🔌 Chaînes de connexion

// appsettings.json → "ConnectionStrings": { "Default": "<valeur chiffrée>" }

string cs = EncryptionHelper.GetConnectionString(builder.Configuration, "Default");
// Retourne la valeur déchiffrée, ou la valeur brute si le déchiffrement échoue

📂 Sections de configuration

Déchiffre toutes les valeurs directes d'une section :

IConfiguration smtp = EncryptionHelper.GetSection(builder.Configuration, "Smtp");

🔄 Compatibilité avec les valeurs .NET Framework

Si vous migrez depuis Kapela.Security.Encryption.Net4, utilisez IsNet4 = true pour déchiffrer les anciennes valeurs côte à côte avec les nouvelles :

[Encrypted(IsNet4 = true)]
public string AncienMotDePasse { get; set; } = string.Empty;

Pour migrer définitivement ces valeurs, utilisez l'outil CLI 👇

🛠️ Générer des valeurs chiffrées

Installez l'outil CLI Kapela.Security.Encryption.Tools pour produire vos valeurs chiffrées à placer dans appsettings.json :

dotnet tool install --global Kapela.Security.Encryption.Tools

Kapela-Encryption encrypt -p NomDeMonApplication -v "MonMotDePasse"
 >>> SGVsbG8gV29ybGQ...