Kapela.Security.Encryption.Net4 4.0.3

🔐 Kapela.Security.Encryption.Net4

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

⚠️ Ce package cible .NET Framework 4.8 / 4.8.1. Pour les applications .NET, préférez Kapela.Security.Encryption.

📦 Installation

Install-Package Kapela.Security.Encryption.Net4

🗝️ Clé de chiffrement

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

1. Au démarrage via SetEncryptionKey :

// À appeler au démarrage de l'application, avant tout chiffrement ou déchiffrement
EncryptionHelper.SetEncryptionKey("MaCléPersonnalisée");

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.

⚠️ 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.Net4;

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 d'un objet, puis appelez ParseObject — tout est déchiffré en une seule passe, y compris les objets imbriqués.

Déclaration du modèle

public class AppSettings
{
    public string ApiUrl { get; set; }

    [Encrypted]
    public string ApiKey { get; set; }

    [Encrypted]
    public SmtpSettings Smtp { get; set; }
}

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

    [Encrypted]
    public string Password { get; set; }
}

Déchiffrement

var settings = /* récupération depuis la configuration */;
EncryptionHelper.ParseObject(settings);
// ✅ settings.ApiKey et settings.Smtp.Password sont en clair
// ⚠️ Smtp doit être décoré avec [Encrypted] pour que la récursion s'applique

Comportement en cas d'échec

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

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

Profondeur de récursion

ParseObject descend jusqu'à 5 niveaux d'imbrication par défaut. Ce seuil est configurable :

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].

📂 Lecture depuis web.config / app.config

Dans une application .NET Framework classique, les valeurs chiffrées peuvent être stockées dans la section <appSettings> et exposées via un POCO de configuration dont les getters déchiffrent à la volée.

Configuration

<configuration>
  <appSettings>
    <add key="ApiUrl" value="https://api.example.com" />
    <add key="ApiKey" value="<valeur chiffrée>" />
    <add key="SmtpPassword" value="<valeur chiffrée>" />
  </appSettings>
</configuration>

Classe d'accès

using System.Configuration;
using Kapela.Security.Encryption.Net4;

public class AppConfig
{
    public string ApiUrl => ConfigurationManager.AppSettings["ApiUrl"];

    public string ApiKey => EncryptionHelper.Decrypt(ConfigurationManager.AppSettings["ApiKey"]);

    public string SmtpPassword => EncryptionHelper.Decrypt(ConfigurationManager.AppSettings["SmtpPassword"]);
}

Utilisation

var config = new AppConfig();
var client = new HttpClient { BaseAddress = new Uri(config.ApiUrl) };
client.DefaultRequestHeaders.Add("X-Api-Key", config.ApiKey);

💡 Pour des valeurs lues très fréquemment, envisagez un cache local pour éviter de déchiffrer à chaque accès.

🔄 Migration vers .NET

Les valeurs chiffrées avec ce package ne sont pas directement compatibles avec Kapela.Security.Encryption. Deux options pour migrer :

Option 1 — Outil CLI (recommandé)

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

Kapela-Encryption migrate -p MonApplication -k MaCléPersonnalisée -v "<valeur chiffrée Net4>"
 >>> <nouvelle valeur à placer dans appsettings.json>

Option 2 — Lecture transitoire dans le code

Dans l'application .NET cible, utilisez IsNet4 = true pour déchiffrer temporairement les anciennes valeurs le temps de les remplacer :

// Dans Kapela.Security.Encryption (.NET)
[Encrypted(IsNet4 = true)]
public string AncienMotDePasse { get; set; } = string.Empty;

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

Utilisez l'outil CLI avec l'option --net4 :

Kapela-Encryption encrypt --net4 -p MonApplication -k MaCléPersonnalisée -v "MonMotDePasse"
 >>> <valeur à placer dans la configuration>