EfCore.ColumnEncryption
1.0.2
dotnet add package EfCore.ColumnEncryption --version 1.0.2
NuGet\Install-Package EfCore.ColumnEncryption -Version 1.0.2
<PackageReference Include="EfCore.ColumnEncryption" Version="1.0.2" />
paket add EfCore.ColumnEncryption --version 1.0.2
#r "nuget: EfCore.ColumnEncryption, 1.0.2"
// Install EfCore.ColumnEncryption as a Cake Addin #addin nuget:?package=EfCore.ColumnEncryption&version=1.0.2 // Install EfCore.ColumnEncryption as a Cake Tool #tool nuget:?package=EfCore.ColumnEncryption&version=1.0.2
EfCore.ColumnEncryption
A secure column encryption library for Entity Framework Core using AES-GCM.
Table of Contents
- Introduction
- Features
- Prerequisites
- Installation
- Getting Started
- Example
- Limitations
- Security Considerations
- License
- Contact
- FAQ
- Feedback
- Notes
- Additional Resources
Introduction
EfCore.ColumnEncryption
is a lightweight and secure library that provides column-level encryption for Entity Framework Core applications using the AES-GCM encryption algorithm. It allows you to protect sensitive data such as personal information, passwords, and financial data within your database columns without significant changes to your existing codebase.
Features
- Transparent Encryption and Decryption: Automatically encrypts data before saving to the database and decrypts data when reading from the database.
- AES-GCM Encryption: Utilizes AES-GCM, a robust encryption algorithm that provides both confidentiality and integrity.
- Easy Integration: Minimal configuration required to start encrypting your data.
- Support for Nullable Strings: Handles
null
and empty strings gracefully. - Database-Agnostic: Works with any database provider supported by Entity Framework Core.
Prerequisites
- .NET 8.0 or higher
- Entity Framework Core 8.0.8 or higher
Installation
You can install the EfCore.ColumnEncryption
package via NuGet Package Manager, .NET CLI, or by editing your project file.
Package Manager
Install-Package EfCore.ColumnEncryption
.NET CLI
dotnet add package EfCore.ColumnEncryption
Package Reference
Add the following line to the .csproj file of your project
<PackageReference Include="EfCore.ColumnEncryption" Version="1.0.2" />
Getting Started
Setup
To start using EfCore.ColumnEncryption, you need to configure your Entity Framework Core DbContext to use the library and provide an encryption key.
- Create an Encryption Provider
using EfCore.ColumnEncryption.Encryption;
// Your encryption key must be 16, 24, or 32 bytes for AES
byte[] encryptionKey = Convert.FromBase64String("Base64EncodedKeyHere");
var encryptionProvider = new AesGcmColumnEncryptionProvider(encryptionKey);
Note: Ensure that you securely manage your encryption key. Do not hard-code it in your source code or expose it in version control systems.
- Configure Your DbContext
using EfCore.ColumnEncryption.Extensions;
using EfCore.ColumnEncryption.Interfaces;
public class ApplicationDbContext : DbContext
{
private readonly IColumnEncryptionProvider _encryptionProvider;
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options, IColumnEncryptionProvider encryptionProvider)
: base(options)
{
_encryptionProvider = encryptionProvider;
}
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
base.OnModelCreating(modelBuilder);
// Apply encryption to properties marked with [Encrypted]
modelBuilder.UseColumnEncryption(_encryptionProvider);
}
public DbSet<Customer> Customers { get; set; }
}
- Update Dependency Injection Configuration
services.AddSingleton<IColumnEncryptionProvider>(provider =>
{
byte[] encryptionKey = Convert.FromBase64String("YourBase64EncodedKeyHere");
return new AesGcmColumnEncryptionProvider(encryptionKey);
});
services.AddDbContext<ApplicationDbContext>((serviceProvider, options) =>
{
options.UseSqlServer("Your DbConnection credentials");
});
Usage
- Annotate Your Model Properties
Use the [Encrypted]
attribute on any properties that you wish to encrypt.
using EfCore.ColumnEncryption.Attributes;
public class Customer
{
public int Id { get; set; }
[Encrypted]
public string? CreditCardNumber { get; set; }
[Encrypted]
public string SocialSecurityNumber { get; set; }
public string Name { get; set; }
}
- Perform Data Operations as Usual
You can perform CRUD operations without any additional code. The library handles encryption and decryption automatically.
var customer = new Customer
{
Name = "John Doe",
CreditCardNumber = "4111111111111111",
SocialSecurityNumber = "123-45-6789"
};
_context.Customers.Add(customer);
await _context.SaveChangesAsync(); // Encrypts columns marked with the [Encrypted] attribute before saving them to the database
var storedCustomer = await _context.Customers.FindAsync(customer.Id);
Console.WriteLine(storedCustomer.CreditCardNumber); // Decrypted value
Example
Here's a complete example demonstrating how to set up and use EfCore.ColumnEncryption in an ASP.NET Core application.
Program.cs
using EfCore.ColumnEncryption.Encryption;
using EfCore.ColumnEncryption.Interfaces;
var builder = WebApplication.CreateBuilder(args);
// Register the encryption provider
builder.Services.AddSingleton<IColumnEncryptionProvider>(
new AesGcmColumnEncryptionProvider(Encoding.UTF8.GetBytes("yourEncryptionKeyInHere")));
// Register the DbContext
builder.Services.AddDbContext<ApplicationDbContext>(options =>
{
options.UseSqlServer("connection string");
});
// ...
var app = builder.Build();
// ...
app.Run();
ApplicationDbContext.cs
using EfCore.ColumnEncryption.Extensions;
using EfCore.ColumnEncryption.Interfaces;
public class ApplicationDbContext : DbContext
{
private readonly IColumnEncryptionProvider _encryptionProvider;
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options, IColumnEncryptionProvider encryptionProvider)
: base(options)
{
_encryptionProvider = encryptionProvider;
}
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
base.OnModelCreating(modelBuilder);
modelBuilder.UseColumnEncryption(_encryptionProvider);
}
public DbSet<Customer> Customers { get; set; }
}
Customer.cs
using EfCore.ColumnEncryption.Attributes;
public class Customer
{
public int Id { get; set; }
[Encrypted]
public string? CreditCardNumber { get; set; }
[Encrypted]
public string? SocialSecurityNumber { get; set; }
public string? Name { get; set; }
}
Usage in a Controller
public class CustomersController : Controller
{
private readonly ApplicationDbContext _context;
public CustomersController(ApplicationDbContext context)
{
_context = context;
}
public async Task<IActionResult> Create()
{
var customer = new Customer
{
Name = "Jane Doe",
CreditCardNumber = "5555555555554444",
SocialSecurityNumber = "987-65-4321"
};
_context.Customers.Add(customer);
await _context.SaveChangesAsync();
return View();
}
public async Task<IActionResult> Details(int id)
{
var customer = await _context.Customers.FindAsync(id);
return View(customer);
}
}
Limitations
- Data Length: Encrypted data will be longer than the original plaintext. Ensure that your database columns are sized appropriately to store the encrypted data.
- Performance Overhead: Encryption and decryption introduce computational overhead. Performance impact is minimal for small amounts of data but consider benchmarking for large-scale applications.
- Data Migrations: When adding encryption to existing data, you'll need to migrate and encrypt existing plaintext data.
Security Considerations
- Key Security: Protect your encryption key using secure key management practices.
- Key Rotation: Plan for key rotation and re-encryption strategies.
Contributing
Contributions are welcome!
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contact
- Author: Efe Yener
- Email: efeyener6132@gmail.com
- GitHub: efeynr
FAQ
Can I use this library with databases other than SQL Server? Yes, EfCore.ColumnEncryption is database-agnostic and should work with any database provider supported by Entity Framework Core.
Does this library support encryption of data types other than strings? Currently, the library focuses on encrypting string properties. Support for other data types may be added in future releases.
How secure is the encryption provided by this library? The library uses AES-GCM, which is a widely accepted and secure encryption algorithm. However, security also depends on how you manage your encryption keys and the overall security practices of your application.
Feedback
If you encounter any issues, have questions, or want to suggest new features, please open an issue on the GitHub repository.
Notes
- Secure Key Management: Do not commit your encryption keys or any sensitive information to version control.
- Dependencies: Regularly update your dependencies to include the latest security patches.
Additional Resources
Thank you for using EfCore.ColumnEncryption!
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Microsoft.EntityFrameworkCore (>= 8.0.8)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Initial release with support for AES-GCM column encryption.