EntityFrameworkCore.Crypto.DataEncryption 10.6.6

There is a newer version of this package available.
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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="EntityFrameworkCore.Crypto.DataEncryption" Version="10.6.6" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="EntityFrameworkCore.Crypto.DataEncryption" Version="10.6.6" />
                    
Directory.Packages.props
<PackageReference Include="EntityFrameworkCore.Crypto.DataEncryption" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add EntityFrameworkCore.Crypto.DataEncryption --version 10.6.6
                    
#r "nuget: EntityFrameworkCore.Crypto.DataEncryption, 10.6.6"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package EntityFrameworkCore.Crypto.DataEncryption@10.6.6
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=EntityFrameworkCore.Crypto.DataEncryption&version=10.6.6
                    
Install as a Cake Addin
#tool nuget:?package=EntityFrameworkCore.Crypto.DataEncryption&version=10.6.6
                    
Install as a Cake Tool

EntityFrameworkCore.Crypto.DataEncryption

.NET NuGet Downloads License: Commercial / Community Cryptography: AES-256-GCM AEAD In-Process EF Core GDPR Art. 32 DPDP 2023 §8 PCI-DSS

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

Website • Documentation • Security policy • Issues

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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 10.0.0 is deprecated because it has critical bugs.
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.2 is deprecated because it is no longer maintained and has critical bugs.
8.0.1 433 5/27/2024 8.0.1 is deprecated because it is no longer maintained and has critical bugs.
8.0.0 454 5/24/2024 8.0.0 is deprecated because it is no longer maintained.

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