Kapela.Security.Encryption.Net4 4.0.2

🔐 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

La clé peut être initialisée au démarrage, sinon elle est générée automatiquement :

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

⚠️ Les valeurs chiffrées avec une clé ne peuvent être déchiffrées qu'avec cette même clé.

✏️ Chiffrement et déchiffrement

Opérations de base sur une valeur :

using Kapela.Security.Encryption.Net4;

string chiffré = EncryptionHelper.Encrypt("MonMotDePasse");
string clair   = EncryptionHelper.Decrypt(chiffré);

Versions sans exception, pratiques dans les initialisations :

if (EncryptionHelper.TryEncrypt("MonMotDePasse", out string chiffré)) { }
if (EncryptionHelper.TryDecrypt(chiffré, out string clair)) { }

🏷️ Déchiffrement automatique avec [Encrypted]

Décorez les propriétés sensibles de votre objet de configuration, 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 DatabaseSettings Database { get; set; }
}

public class DatabaseSettings
{
    [Encrypted]
    public string ConnectionString { get; set; }
}

Déchiffrement

var settings = /* récupération depuis la configuration */;
EncryptionHelper.ParseObject(settings);
// ✅ settings.ApiKey et settings.Database.ConnectionString sont en clair
// ⚠️ Database 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].

🔄 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 NomDeMonApplication -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 NomDeMonApplication -v "MonMotDePasse"
 >>> <valeur à placer dans la configuration>