EntityCrypt.EFCore 2.0.2

🔐 EntityCrypt.EFCore - دليل الاستخدام

📦 التثبيت

# إضافة المشروع كمرجع
dotnet add reference path/to/EntityCrypt.EFCore.csproj

🚀 البدء السريع

1. تعريف الكيانات مع سمات التشفير

using EntityCrypt.EFCore.Attributes;

// تشفير على مستوى الجدول
[EncryptedTable(DefaultLevel = EncryptionLevel.Classical)]
public class Customer
{
    public int Id { get; set; }
    
    [Encrypted]  // تشفير هذا الحقل
    public string Name { get; set; }
    
    [Encrypted(Level = EncryptionLevel.Hybrid)]  // تشفير هجين
    public string Email { get; set; }
    
    [Encrypted(Searchable = true)]  // قابل للبحث
    public string Phone { get; set; }
    
    [NoEncrypt]  // استثناء من التشفير
    public DateTime CreatedAt { get; set; }
}

// تشفير حقول محددة فقط
public class Order
{
    public int Id { get; set; }
    public int CustomerId { get; set; }
    
    [Encrypted]
    public string ShippingAddress { get; set; }
    
    [Encrypted(Level = EncryptionLevel.Classical)]
    public string PaymentInfo { get; set; }
    
    public decimal Total { get; set; }  // بدون تشفير
}

2. إعداد DbContext

using EntityCrypt.EFCore.Extensions;
using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public DbSet<Customer> Customers => Set<Customer>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseSqlite("Data Source=app.db")
               .UseEntityCrypt(encryption => encryption
                   .WithMasterKey("your-secret-master-key-here")
                   .WithDefaultLevel(EncryptionLevel.Classical)
                   .PreserveRelationships()
                   .EncryptTableNames(false)  // لا تشفر أسماء الجداول
                   .EncryptFieldNames(false)  // لا تشفر أسماء الحقول
               );
    }
}

3. الاستخدام العادي (شفاف تماماً)

// لا حاجة لأي كود إضافي!
// التشفير/فك التشفير يحدث تلقائياً

using var db = new AppDbContext();

// الإضافة - يتم التشفير تلقائياً
var customer = new Customer
{
    Name = "أحمد محمد",           // سيُشفر تلقائياً
    Email = "ahmed@example.com",  // سيُشفر بـ Hybrid
    Phone = "+966501234567",      // سيُشفر (قابل للبحث)
    CreatedAt = DateTime.Now      // لن يُشفر (NoEncrypt)
};

db.Customers.Add(customer);
await db.SaveChangesAsync();

// القراءة - يتم فك التشفير تلقائياً
var loadedCustomer = await db.Customers.FindAsync(customer.Id);
Console.WriteLine(loadedCustomer.Name);  // "أحمد محمد" (مفكوك)

📊 مستويات التشفير

🎯 سيناريوهات الاستخدام

السيناريو 1: تشفير قاعدة البيانات بالكامل

[EncryptedDatabase(DefaultLevel = EncryptionLevel.Classical)]
public class SecureDbContext : DbContext
{
    // جميع الكيانات ستُشفر تلقائياً
}

السيناريو 2: تشفير جداول محددة

[EncryptedTable]  // هذا الجدول مشفر
public class SensitiveData { ... }

public class PublicData { ... }  // هذا الجدول غير مشفر

السيناريو 3: تشفير حقول محددة

public class User
{
    public int Id { get; set; }
    public string Username { get; set; }  // غير مشفر
    
    [Encrypted]
    public string Password { get; set; }  // مشفر
    
    [Encrypted(Level = EncryptionLevel.Hybrid)]
    public string SSN { get; set; }  // مشفر بـ Hybrid
}

السيناريو 4: مفاتيح مخصصة لكل كيان

options.UseEntityCrypt(encryption => encryption
    .WithMasterKey("default-key")
    .WithEntityKey<Customer>("customer-special-key")
    .WithEntityKey<Order>("order-special-key")
);

السيناريو 5: استثناء كيانات

options.UseEntityCrypt(encryption => encryption
    .WithMasterKey("master-key")
    .ExcludeEntity<AuditLog>()  // لا تشفر AuditLog
    .ExcludeProperty<User>("Username")  // لا تشفر Username
);

🔗 التعامل مع العلاقات (PK/FK)

// افتراضياً: أسماء أعمدة PK/FK مُشفَّرة دائماً لمنع تسريب بنية المخطط
// PreserveRelationships يتحكم فقط بتشفير القيم — لضمان عمل JOINs
options.UseEntityCrypt(encryption => encryption
    .PreserveRelationships()  // الافتراضي: true (القيم نصية، الأسماء مشفَّرة)
);

// إذا أردت تشفير المفاتيح الأساسية (غير موصى به)
options.UseEntityCrypt(encryption => encryption
    .EncryptPrimaryKeys(true)  // تحذير: قد يكسر العلاقات!
);

🔒 أمان المخطط: أسماء أعمدة PK/FK (مثل Id, UserId) تُشفَّر إلى mc_xxxx حتى مع PreserveRelationships(true). هذا يمنع المهاجم من الاستدلال على بنية الهوية من أسماء الأعمدة. EF Core يعمل بشكل طبيعي لأنه يستخدم metadata النموذج.

🔍 البحث في البيانات المشفرة

// للحقول القابلة للبحث (Searchable = true)
[Encrypted(Searchable = true)]
public string Phone { get; set; }

// البحث يعمل عبر hash comparison
var customer = await db.Customers
    .Where(c => c.Phone == "+966501234567")  // يعمل!
    .FirstOrDefaultAsync();

📈 الأداء

بدون PQC (Classical فقط)

Encrypt: ~1.3 µs/field
Decrypt: ~3.3 µs/field
Throughput: ~750,000 ops/sec

مع PQC (Hybrid)

Encrypt: ~30 µs/field
Decrypt: ~76 µs/field
Throughput: ~13,000 ops/sec

🛠️ التكامل مع WasmMvcRuntime.Data

// في Program.cs أو Startup.cs
services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite(config.DatabasePath)
           .UseEntityCrypt(encryption => encryption
               .WithMasterKey(config.EncryptionKey)
               .WithDefaultLevel(EncryptionLevel.Classical)
           ));

// في SQLiteDataProvider
public class SecureSQLiteDataProvider : SQLiteDataProvider
{
    // يعمل تلقائياً - لا حاجة لتغيير الكود!
}

🔐 أفضل الممارسات

1. إدارة المفاتيح

// ❌ لا تفعل هذا
.WithMasterKey("hardcoded-key")

// ✅ افعل هذا
.WithMasterKey(Environment.GetEnvironmentVariable("ENCRYPTION_KEY"))

// ✅ أو استخدم Azure Key Vault
.WithKeyProvider(new AzureKeyVaultProvider(vaultUri))

2. اختيار مستوى التشفير

// بيانات عادية
[Encrypted(Level = EncryptionLevel.Classical)]
public string Address { get; set; }

// بيانات حساسة جداً
[Encrypted(Level = EncryptionLevel.Hybrid)]
public string CreditCardNumber { get; set; }

3. الأداء

// للأداء العالي: استثنِ الحقول غير الحساسة
[NoEncrypt]
public DateTime CreatedAt { get; set; }

[NoEncrypt]
public int ViewCount { get; set; }

📊 ما يحدث في قاعدة البيانات

الكيان الأصلي

{
  "Id": 1,
  "Name": "أحمد محمد",
  "Email": "ahmed@example.com",
  "Phone": "+966501234567"
}

كما يُخزن في قاعدة البيانات

{
  "mc_a1b2c3": 1,                           // Id — الاسم مشفَّر، القيمة محفوظة للعلاقات
  "mc_d4e5f6": "3Kf8Lm2Pq9Rt5Vw7Xy0Z...",  // Name — مشفر بالكامل
  "mc_g7h8i9": "MLKEM768:ABC123...DEF456:7Hj9Kl...",  // Email — مشفر Hybrid
  "mc_j0k1l2": "2Bn4Dp6Fr8Hs0Jt..."        // Phone — مشفر + searchable hash
}

كما يراه التطبيق

{
  "Id": 1,
  "Name": "أحمد محمد",  // مفكوك تلقائياً
  "Email": "ahmed@example.com",  // مفكوك تلقائياً
  "Phone": "+966501234567"  // مفكوك تلقائياً
}

✅ الخلاصة

// الحد الأدنى من الكود:

// 1. أضف السمات
[EncryptedTable]
public class MyEntity { ... }

// 2. فعّل التشفير
options.UseSqlite("...")
       .UseEntityCryptClassical("my-key");

// 3. استخدم كالمعتاد!
db.MyEntities.Add(entity);
await db.SaveChangesAsync();

هذا كل شيء! 🎉

🛡️ التحقق من الحزمة والأمان

فحص الثغرات في مشروعك

بعد إضافة الحزمة، يمكنك فحص الثغرات الأمنية المعروفة في التبعيات:

# فحص الثغرات في كافة التبعيات
dotnet list package --vulnerable --include-transitive

# فحص بتنسيق JSON للتحليل الآلي
dotnet list package --vulnerable --include-transitive --format json

التحقق من سلامة الحزمة (SHA-256)

كل إصدار يتضمن ملف SHA256SUMS.txt في صفحة الإصدارات. تحقق من تطابق hash الحزمة المُنزّلة:

# PowerShell
Get-FileHash EntityCrypt.EFCore.*.nupkg -Algorithm SHA256

# Linux/macOS
sha256sum EntityCrypt.EFCore.*.nupkg

قارن الناتج مع القيم في SHA256SUMS.txt المنشور مع الإصدار.

قائمة المواد البرمجية (SBOM)

يتم إنشاء ملف CycloneDX SBOM تلقائياً مع كل إصدار ويُرفق في صفحة الإصدارات. يمكنك استخدامه للتدقيق في سلسلة التوريد البرمجية.

ضمانات الأمان في CI/CD

<div align="center">

🔐 EntityCrypt.EFCore

Transparent Encryption for Entity Framework Core

.NET 10 | ML-KEM | FIPS 203

</div>