EntityFrameworkCore.Crypto.DataEncryption
10.6.6
See the version list below for details.
dotnet add package EntityFrameworkCore.Crypto.DataEncryption --version 10.6.6
NuGet\Install-Package EntityFrameworkCore.Crypto.DataEncryption -Version 10.6.6
<PackageReference Include="EntityFrameworkCore.Crypto.DataEncryption" Version="10.6.6" />
<PackageVersion Include="EntityFrameworkCore.Crypto.DataEncryption" Version="10.6.6" />
<PackageReference Include="EntityFrameworkCore.Crypto.DataEncryption" />
paket add EntityFrameworkCore.Crypto.DataEncryption --version 10.6.6
#r "nuget: EntityFrameworkCore.Crypto.DataEncryption, 10.6.6"
#:package EntityFrameworkCore.Crypto.DataEncryption@10.6.6
#addin nuget:?package=EntityFrameworkCore.Crypto.DataEncryption&version=10.6.6
#tool nuget:?package=EntityFrameworkCore.Crypto.DataEncryption&version=10.6.6
EntityFrameworkCore.Crypto.DataEncryption
Transparent field-level encryption for Entity Framework Core 10 on .NET 10. Data is encrypted in your application process before it reaches the database, so the database, its administrators and its backups only ever see ciphertext. Keys never leave your process.
Website & licensing • Complete guide • Roadmap • Security
Install
dotnet add package EntityFrameworkCore.Crypto.DataEncryption
Quick start
Mark the properties to encrypt, then turn encryption on in OnModelCreating:
public class Customer
{
public int Id { get; set; }
[CryptoEncrypted]
public string Ssn { get; set; } = string.Empty;
[CryptoEncrypted]
public string Email { get; set; } = string.Empty;
[CryptoEncrypted]
[Column(TypeName = "TEXT")]
public decimal AnnualSalary { get; set; }
}
public class AppDbContext : DbContext
{
private readonly IEncryptionCryptoProvider _provider = new AesGcmCryptoProvider(LoadKeyFromSecureStore()); // 32-byte key
public DbSet<Customer> Customers => Set<Customer>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
=> modelBuilder.UseEncryption(_provider); // call last
}
EF Core encrypts on SaveChanges and decrypts when rows are read. Supported types: string, byte[], long, decimal, double, Dictionary<string, string>, JSON classes and owned entity types.
What you get
| Capability | Notes |
|---|---|
| AES-256-GCM authenticated encryption | Random nonce per value, tamper detection, key IDs and key rings for rotation. |
| Cloud KMS | Azure Key Vault, AWS KMS, HashiCorp Vault. |
| Searchable columns | Blind index for equality lookups (HasBlindIndex, WhereBlindEquals). |
| Substring search and sorting | Exact Contains / StartsWith / EndsWith and in-application sorting, plus WhereBlindIn for IN lists and per-column normalization (WithNormalization). Optional accent-insensitive matching (HasSearchIndex(true, accentInsensitive: true): jose finds José). The key is never sent to the database. |
| Fuzzy (typo-tolerant) search | WhereSimilar(c => c.Name, "Jhon Smith", maxEdits: 1) finds "John Smith". Exact (no match missed, none added) and uses the same search index. |
| Tolerant decryption | Opt-in: with new EncryptionOptions { OnDecryptionFailure = DecryptionFailurePolicy.ReturnNull }, a string, byte[] or JSON column whose value cannot be decrypted reads as null and is logged, and the query carries on. Numeric columns still throw. |
| Query guard | Queries that cannot work on ciphertext throw instead of silently returning wrong results. |
| Safe under load | One provider instance can be shared by every thread. 10.6.6 fixes a defect in earlier versions that made AES-GCM fail under concurrent load on Linux: details. |
| Batch re-encryption | Verified, resumable AES-CBC to AES-GCM migration and key rotation (EncryptionRotator). |
| Legacy migration bridge | MigrationCryptoProvider reads old AES-CBC data and writes AES-GCM. |
| Auto-encryption | UseAutoEncryption encrypts sensitive columns by naming convention. |
| Observability | Health checks, OpenTelemetry metrics. |
| Enterprise | PII scanner with ML classifier, Crypto Sentinel anomaly detection, email/webhook alerts, decryption audit trail, DPDP / GDPR compliance reports. |
Searching encrypted columns
// Equality: a keyed hash in an indexed shadow column
modelBuilder.Entity<Customer>().Property(c => c.Email).HasBlindIndex();
var customer = await context.Customers.WhereBlindEquals(nameof(Customer.Email), email, hasher).FirstOrDefaultAsync();
var customers = await context.Customers.WhereBlindIn(context, nameof(Customer.Email), emails, hasher).ToListAsync(); // IN list
// Substring search and sorting
modelBuilder.Entity<Customer>().Property(c => c.Ssn).HasSearchIndex();
var rows = await context.Customers.AsEncrypted(context, hasher)
.WhereContains(c => c.Ssn, "123")
.OrderBy(c => c.Ssn)
.ToListAsync(maxRows: 5_000);
Results are exact: the index narrows candidates in SQL and each one is confirmed against the decrypted value. Sorting runs in the application and needs a maxRows cap, so it throws instead of truncating. Contains needs a term of at least 3 characters. Existing rows become searchable after a one-time SearchIndexBackfill.
Measured on 300,000 rows (single runs, default Docker containers on one desktop, no tuning, no PostgreSQL trigram index):
| PostgreSQL 16 | SQL Server 2022 | MySQL 8.4 | |
|---|---|---|---|
Contains("marnia") → 69 rows |
77 ms | 111 ms | 358 ms |
StartsWith("MARIA") → 1,169 rows |
53 ms | 158 ms | 305 ms |
| SQL filter + sort, 30,000 rows | 168 ms | 468 ms | 495 ms |
Tested on SQLite and on all three databases, with EF Core 10: results match the plaintext answer exactly (including %, _, accents and mixed case), sort order with nulls, upgrade of legacy CBC data, CBC to GCM and key rotation, and no plaintext or keys in the PostgreSQL and MySQL server logs. Not measured: concurrent load and tables over 300,000 rows.
Setup, limits and method: search and re-encryption guide. Everything else, including KMS, scanning, alerts and compliance: full reference.
Licensing
Free for evaluation, open source and projects under $2,000/yr revenue (Community). Above that, every paid plan unlocks the full platform, priced per organization with no per-seat counting:
| Plan | Price | Support |
|---|---|---|
| Community | Free, under $2,000 annual revenue | Community |
| Enterprise Annual | $2,999 / year, unlimited developers and projects | Priority, under 1 business day |
| Enterprise 3-Year | $5,999 prepaid, one payment | Priority, 1-hour response |
| Enterprise 5-Year | $6,999 prepaid, one payment | Priority, 1-hour response |
Field encryption, key rotation, cloud KMS, blind indexing, search and auto-encryption are in Community. The ML classifier, Crypto Sentinel, alerts, audit trail and compliance reports need an Enterprise key. Plans and contact form: efcore-encryption.com/#plans.
Local development is never blocked or nagged. On a developer machine every feature works with or without a key, and no license message or error is shown. The license is checked only if you call AddDataEncryptionML(...); modelBuilder.UseEncryption(...), search and re-encryption on their own never check it. When you deploy with AddDataEncryptionML and no valid key, the host throws LicenseValidationException at startup in Kubernetes, managed cloud, a container (unless the environment is Development), or when the environment is Production or Staging. Set options.Enforcement.Mode = LicenseEnforcementMode.WarnOnly (or the environment variable EFCRYPTOML_LICENSE_ENFORCEMENT=WarnOnly) to log a warning instead of failing; paid features then stay off until a key is added.
Support
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- MailKit (>= 4.18.2)
- Microsoft.EntityFrameworkCore (>= 10.0.14)
- Microsoft.Extensions.Caching.Memory (>= 10.0.14)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Http (>= 10.0.14)
- Microsoft.Extensions.Options.DataAnnotations (>= 10.0.14)
- Microsoft.ML (>= 5.0.1)
- Microsoft.ML.TimeSeries (>= 5.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated | |
|---|---|---|---|
| 11.0.0 | 53 | 11/16/2026 | |
| 10.7.0 | 84 | 11/12/2026 | |
| 10.6.6 | 88 | 11/11/2026 | |
| 10.6.5 | 184 | 10/5/2026 | |
| 10.6.0 | 261 | 9/10/2026 | |
| 10.5.0 | 149 | 9/8/2026 | |
| 10.4.0 | 87 | 11/5/2026 | |
| 10.3.0 | 90 | 11/5/2026 | |
| 10.2.0 | 92 | 11/5/2026 | |
| 10.1.0 | 87 | 11/5/2026 | |
| 10.0.1 | 5,008 | 11/12/2025 | |
| 10.0.0 | 5,104 | 11/12/2025 | |
| 9.0.0 | 1,204 | 6/23/2025 | |
| 8.0.3 | 69,488 | 5/29/2024 | |
| 8.0.2 | 458 | 5/27/2024 | |
| 8.0.1 | 433 | 5/27/2024 | |
| 8.0.0 | 454 | 5/24/2024 |
Version 10.6.6
IN SHORT
- For .NET 10 and EF Core 10 only. Unlike 10.6.5, this version has no .NET 8 or .NET 9 build; see BREAKING CHANGES.
- Fixes a thread-safety defect in AES-GCM on Linux. If you run on Linux or in a container, upgrade. See IMPORTANT FIX.
- Faster: search indexing, query tokens, blind-index hashing and fuzzy matching take about half the time and allocate up to 16 times less memory; reading legacy AES-CBC data is about 12 times faster.
- New: accent-insensitive search, AnyAsync and FirstOrDefaultAsync on encrypted queries, SearchIndexBackfill.RebuildAsync, and a wider query guard.
- Includes everything from 10.1.0 to 10.4.0 (search, sorting, query guard, rotation, tolerant decryption) and fuzzy search, none of which was in 10.6.5.
IMPORTANT FIX: AES-GCM UNDER CONCURRENT LOAD ON LINUX
- What was wrong: AesGcmCryptoProvider kept one platform AES-GCM object per key and used it from every thread. That object is not safe to share. On Windows this did not show. On Linux (OpenSSL), when several threads encrypted or decrypted at the same moment on one provider, operations failed and, more rarely, a decryption returned the wrong bytes without an error.
- How it was measured: 12 threads sharing one provider, 2.4 million encrypt and decrypt round trips of a 35-byte value, in a Linux container. Before: about 1.95 million round trips failed with an exception and about 40,000 returned a wrong value. After: 0 failed and 0 wrong, and throughput rose from about 470,000 to about 1,380,000 round trips per second. On Windows the same test had no failures before or after.
- Who is affected: every earlier version that has AesGcmCryptoProvider, used on Linux by more than one thread at a time, which is how a web application uses it. KmsCryptoProvider and MigrationCryptoProvider use it internally and were affected the same way.
- What to do: upgrade. No setting or code change is needed. Stored data needs no conversion. A value that was written while the defect was active and cannot be decrypted now was damaged when it was written; this release cannot repair it. Tolerant decryption (OnDecryptionFailure = ReturnNull) with its failure callback will list such rows.
- The fix: each provider now holds several AES-GCM objects, one per processor up to 32, each used by one thread at a time. A thread takes a free one and does not wait for other threads unless all are busy. The blind-index hasher and the legacy AES-CBC provider use the same design.
PERFORMANCE (measured, one 12-core Windows desktop, .NET 10, single runs, before and after this release)
- Search index build for a 23-character value: 9,317 ns to 4,178 ns; memory per value 7,712 bytes to 480 bytes.
- Search query tokens: 2,098 ns to 1,053 ns. Fuzzy query tokens: 9,459 ns to 4,215 ns.
- Blind-index hash: 320 ns to 209 ns; memory 224 bytes to 88 bytes.
- Fuzzy match check (edit distance, 23 characters, 2 edits): 888 ns to 333 ns.
- Legacy AES-CBC: encrypt 911 ns to 339 ns, decrypt 4,385 ns to 356 ns, memory about 1,300 bytes to 200 bytes per value.
- One AES-GCM provider shared by 12 threads: 3.4 million to 5.5 million round trips per second. A single AES-GCM encrypt (about 310 ns) or decrypt (about 150 ns) is unchanged.
- SaveChanges with a blind or search index: the list of indexed properties is now worked out once per entity type and read without a lock, and the change tracker is walked once per save, not once per indexed property.
- SearchIndexBackfill reads rows after the last key it processed, so each batch costs the same however many rows are already done. Before, each batch skipped past all earlier rows.
- These are micro-measurements of the library's own code. They are not database timings, and other machines will give different numbers.
NEW FEATURES
- Accent-insensitive search: HasSearchIndex(caseInsensitive: true, accentInsensitive: true). A search for "jose" finds "José" and "nguyen" finds "Nguyễn", for Contains, StartsWith, EndsWith and WhereSimilar. Only accents are ignored: letters such as ø, ß, æ and ł, and the vowel signs of Indic, Arabic and Hebrew scripts, are left as they are. The stored encrypted value is not changed. Switching the option on for existing data needs SearchIndexBackfill.RebuildAsync.
- AnyAsync(maxRows) and FirstOrDefaultAsync(maxRows) on AsEncrypted(...) queries. They read candidates one at a time and stop at the first confirmed match, so they do not load or decrypt every matching row.
- SearchIndexBackfill.RebuildAsync: recomputes the search index of every row, for a new index key or a changed case or accent option. Rows that already hold the right index are not written.
- Fuzzy (typo-tolerant) search: AsEncrypted(...).WhereSimilar(c => c.Name, "Jhon Smith", maxEdits: 1) finds "John Smith". The result is exact: no matching row is missed and none is wrongly included. It uses the existing search index.
- Query guard now also rejects, on a randomized column: Equals in all its forms, GroupBy, Join and GroupJoin keys, Distinct and Contains over a projection of the column, and Min, Max, OrderBy over such a projection. It also rejects an encrypted column passed as the argument of a string method. On a deterministic column the equality-based ones stay allowed.
OTHER FIXES
- Query guard: when the check "is this provider deterministic" failed (for example a key service was unreachable for a moment), the guard remembered the provider as deterministic and stopped checking equality on it until restart. It now asks again next time.
- MigrationCryptoProvider: a value with the AES-GCM envelope that fails authentication and is not legacy data either now reports that, in place of the legacy decryptor's unrelated "padding is invalid".
- EncryptionRotator: a failed rollback (usually a lost connection) can no longer hide the error that caused it.
- ToListAsync(int.MaxValue) no longer overflows.
- The blind-index hasher no longer keeps a second copy of its key, and wipes the buffers that held plaintext before returning them to the pool.
WHAT ELSE CHANGED SINCE 10.6.5 (first published in 10.1.0 to 10.4.0)
- Exact Contains / StartsWith / EndsWith search on encrypted columns through a keyed search index (HasSearchIndex, AsEncrypted). The key is never sent to the database. Includes SearchIndexBackfill for existing rows.
- In-application sorting of encrypted columns with a chosen culture and null placement, under a required maxRows cap that throws instead of truncating.
- WhereBlindIn for IN-list lookups on a blind-indexed column, and per-column normalization (WithNormalization, NormalizeForQuery).
- Query guard (UseEncryptedQueryGuard): queries that cannot work on ciphertext throw EncryptedQueryNotSupportedException instead of silently returning nothing.
- Tolerant decryption (opt-in, EncryptionOptions.OnDecryptionFailure = ReturnNull): an unreadable string, byte[] or JSON value reads as null, is logged without any data, and no longer fails the whole query.
- EncryptionRotator: verified, resumable batch re-encryption for CBC to GCM migration and key rotation.
- Fixed: MigrationCryptoProvider could fail to read about 1 in 256 legacy AES-CBC values whose first bytes looked like a GCM envelope with an unregistered key ID.
- Licensing: on a local development machine nothing is checked or logged and every feature works with no key. A deployment with no valid key still fails at startup. See LICENSE BEHAVIOR.
BREAKING CHANGES
- .NET 8 and .NET 9 are not supported by this version. 10.6.5 had net8.0 and net9.0 builds; 10.6.6 has net10.0 only. A project on .NET 8 or .NET 9 that asks for 10.6.6, or for a floating range such as 10.6.*, fails to restore with NU1202. Stay on 10.6.5 there, or use a later release that includes a build for your framework.
- No public API was removed or changed incompatibly against 10.6.5 for .NET 10 (checked by the pack-time API validation).
- The query guard is stricter (see NEW FEATURES). A query it now rejects was returning wrong results before, such as every row in its own group. If you rely on one of them on purpose, load the rows and do that step in memory.
- The net10.0 package requires Microsoft.EntityFrameworkCore 10.0.14 or later (10.6.5 required 10.0.11).
- With licensing, a deployment that calls AddDataEncryptionML without a valid key fails at startup in production-like environments (unchanged from 10.6.5). A local development machine works silently.
NEW AND REMOVED APIS (compared with 10.6.5)
- Added in 10.6.6: HasSearchIndex(caseInsensitive, accentInsensitive); EncryptedQuery.AnyAsync and FirstOrDefaultAsync; SearchIndexBackfill.RebuildAsync; WhereSimilar.
- Added in 10.1.0 to 10.4.0: HasSearchIndex, AsEncrypted, WhereContains, WhereStartsWith, WhereEndsWith, OrderBy, ThenBy, EncryptedSortOptions, SearchIndexBackfill; WhereBlindIn; UseEncryptedQueryGuard, EncryptedQueryNotSupportedException, EncryptedQueryLimitExceededException; WithNormalization, NormalizeForQuery; EncryptionRotator, RotationOptions, checkpoint stores; DecryptionFailurePolicy, DecryptionFailure, EncryptionOptions, the UseEncryption(provider, options) overload and AutoEncryptionOptions.Encryption; LicenseEnforcer.Outcome.AllowedInDevelopment and LicenseGate.IsDevelopmentMode.
- Removed: none.
DEPENDENCIES
- net10.0: Microsoft.EntityFrameworkCore and Microsoft.Extensions.* 10.0.14.
- MailKit 4.18.2. Microsoft.ML and Microsoft.ML.TimeSeries 5.0.1.
- Security: MailKit 4.18.2 brings in System.Security.Cryptography.Pkcs 10.0.13, which fixes advisories GHSA-846f-f764-76mx (high severity) and GHSA-2fmv-rv2c-59x7 (moderate) that affected the Pkcs version used by 10.6.5 and earlier.
STORED DATA FORMAT
- Unchanged. Values written by earlier versions, AES-GCM or legacy AES-CBC, read exactly as before. Nothing needs re-encrypting to upgrade.
- The blind-index and search-index columns are unchanged too. The faster code was compared with the build released as 10.4.0 on 6,030 inputs (ASCII, accented, Asian scripts, emoji, invalid UTF-16) and produced identical output for every one, so existing indexes keep working without a rebuild.
- HasSearchIndex adds an optional nullable column named after the property plus SearchIndex. It needs a database migration and a one-time SearchIndexBackfill for existing rows. An accent-insensitive index stores different tokens for accented text, so turning that option on or off for existing rows needs RebuildAsync.
TESTING
- 420 unit tests pass on .NET 10 on Windows. The same source also passes them in a Linux container, where the thread-safety fix was measured.
- 41 real-database tests pass on EF Core 10 against PostgreSQL 16, MySQL 8.4 and SQL Server 2022.
- The real-database tests include accent-insensitive search, AnyAsync, FirstOrDefaultAsync, RebuildAsync and the new guard rules.
LICENSE BEHAVIOR
- The license is checked only when AddDataEncryptionML is called. UseEncryption, blind index, search, fuzzy search, sorting, tolerant decryption and EncryptionRotator never check it.
- Community needs no key: field encryption, key rotation, cloud KMS, blind indexing, search and auto-encryption. Enterprise needs a key: ML classifier, Crypto Sentinel, email and webhook alerts, custom alert channels, decryption audit trail, compliance reports.
- Local development (default mode Auto): everything works with or without a key, every feature is available, and no license warning or error is shown.
- Deployed (Auto): without a valid key it throws LicenseValidationException at startup in Kubernetes, managed cloud, a container (unless the environment is Development), or when the environment is Production or Staging.
- To log a warning instead of failing, set Enforcement.Mode to WarnOnly in the options, or set the environment variable EFCRYPTOML_LICENSE_ENFORCEMENT to WarnOnly. Paid features then stay off until a key is added. Strict mode fails everywhere, including a developer machine.
- Plans: Community (free, under $2,000 annual revenue), Enterprise Annual ($2,999/yr), Enterprise 3-Year ($5,999 prepaid), Enterprise 5-Year ($6,999 prepaid), all Enterprise plans with unlimited developers and projects. See https://efcore-encryption.com/#plans
KNOWN LIMITS
- No independent security review has been done, of the encryption or of the search index. See SECURITY.md and docs/SEARCH_INDEX_SECURITY_REVIEW_BRIEF.md.
- AES-GCM uses a random 96-bit nonce per value. Rotate a key before it has encrypted about 4 billion values (2 to the power 32), the usual limit for random nonces.
- An encrypted value is not tied to its row or column. Someone who can write to the database can copy a valid encrypted value from one row to another and it will decrypt there. Changing a value is detected; moving one is not.
- Legacy AES-CBC values have no tamper detection. Migrate them with EncryptionRotator.
- The query guard is a safety net for common mistakes. It does not follow a value through every possible subquery shape.
- Accent-insensitive search needs Unicode normalization from the runtime. With InvariantGlobalization or a container image without ICU it throws PlatformNotSupportedException when the model is built. It makes an accented and an unaccented spelling share index tokens, which is the point, and also means the index no longer tells them apart.
- Fuzzy search compares the whole value. It does not match inside a longer value; use WhereContains for that. A term that is too short for the allowed edits is refused: roughly 3 characters for 1 edit, 7 for 2 edits, 11 for 3 edits. Its end-to-end timing against a database has not been benchmarked.
- Range search on encrypted columns is not provided. It would need order-preserving encryption, which reveals the order of values.
- Tolerant decryption applies to reference-type columns only (string, byte[], dictionaries, JSON classes). Numeric columns always throw. EncryptionRotator refuses to run over a tolerant column.
- Sorting an encrypted column runs in the application and needs a maxRows cap. If more rows match, it throws and never truncates.
- Contains search needs a term of at least 3 characters. StartsWith and EndsWith accept shorter terms.
- The search index reveals which rows share short fragments of text, not the text itself. Use a dedicated blind-index key.
- Existing rows are not searchable until SearchIndexBackfill has run. On PostgreSQL a trigram GIN index on the search column is recommended; the published timings were measured without one.
- EncryptionRotator, BackfillAsync and RebuildAsync need a single-column primary key. EncryptionRotator also needs a concurrency token (or AllowWithoutConcurrencyToken) and stops on a row that cannot be decrypted.
- Not tested: tables over 300,000 rows, MariaDB, managed cloud databases, and sustained concurrent load against a real database (the concurrency tests exercise the providers and hashers directly).
Roadmap: https://github.com/efcore-encryption/EntityFrameworkCore.Crypto.DataEncryption/blob/main/ROADMAP.md