Documentation

Two Encryption Modes

Manual — attribute or fluent

// Attribute style:
public class Customer
{
    [CryptoEncrypted]
    public string AadhaarNumber { get; set; }

    [CryptoEncrypted(CryptoStorageFormat.Binary)]
    public string PanNumber { get; set; }
}

// Fluent style (inside OnModelCreating):
modelBuilder.Entity<Customer>()
    .Property(c => c.MobileNumber)
    .IsEncrypted();

// Activation — LAST line of OnModelCreating:
modelBuilder.UseEncryption(monitor.Instrument(Provider));

Auto mode — secure by default

modelBuilder.UseAutoEncryption(monitor.Instrument(Provider));

// Opt extra kinds in deliberately:
options.AutoEncrypt.Kinds.Add(PiiKind.PersonName);
options.AutoEncrypt.MinNameConfidence = 0.8;

Per-field opt-out

// Plaintext with a logged reason:
[DoNotEncrypt(Reason = "search screen filters on this column")]
public string LastName { get; set; }

// Plaintext AND silenced in scans:
[DoNotEncrypt, ScanExempt("Search requirement; DLP monitored",
    ApprovedBy = "CISO, 2026-07-01")]
public string City { get; set; }

What the scanner detects

The scanner walks your DbContext model and samples live data. Detectors include:

Explicit declaration

public class Employee
{
    [CryptoEncrypted, SensitiveData(PiiKind.BankAccount)]
    public string SalaryAccountNumber { get; set; }  // declared AND protected ✅

    [SensitiveData(PiiKind.MonetaryAmount)]
    public string MonthlyCtc { get; set; }           // declared but unencrypted ⇒ Critical
}

Custom detection rules

options.Detection.NameTokens["employeecode"] = new(PiiKind.FreeTextPii, 0.9);

options.Detection.ValueRules.Add(new CustomValueRule
{
    Name         = "EmployeeId",
    Kind         = PiiKind.FreeTextPii,
    Pattern      = @"^EMP-\d{6}$",
    Confidence   = 0.95,
    Deterministic = true,
});

Scan exemptions

// Documented risk acceptance (recommended):
[ScanExempt("Reconciliation export; DLP monitored",
    ApprovedBy = "CISO, 2026-07-01")]
public string PayerName { get; set; }

// Silent skip (for test tables / framework columns):
options.Scan.ExcludedEntities.Add("ImportStagingRow");
options.Scan.ExcludedProperties.Add("Order.TrackingRef");

How Crypto Sentinel works

Sentinel streams decrypt/materialization telemetry into ML.NET SSA spike detection. A service normally decrypting 40 rows/s suddenly doing 5,000/s raises an alert in seconds — without a single rule to write.

// Wire Sentinel into EF:
builder.Services.AddDbContext<AppDbContext>((sp, o) => o
    .UseSqlServer(connectionString)
    .UseCryptoSentinel(sp));

// Tune thresholds:
options.Sentinel.MinEventsForAlert   = 100;  // warm-up count before SSA fires
options.Sentinel.HardRateLimitPerInterval = 500; // absolute guard, works from interval 1
options.Sentinel.TrainingWindow      = 120;  // ≈ 2 min at 1s sampling

Why blind indexes?

AES-GCM uses a random nonce per value — identical plaintexts produce different ciphertexts. Great for security, but WHERE Email = @x can never match server-side. Blind indexes restore equality lookups with a keyed HMAC-SHA256 stored in an auto-indexed shadow column.

// 1. One dedicated key (NOT the encryption key):
var hasher = new BlindIndexHasher(blindIndexKey);

// 2. Configure the property:
modelBuilder.Entity<User>()
    .Property(u => u.Email)
    .IsEncrypted()
    .HasBlindIndex();  // caseInsensitive: true by default

// 3. Register the sync interceptor:
optionsBuilder.AddInterceptors(new BlindIndexInterceptor(hasher));

// 4. Query — index seek, not a scan:
var user = await context.Users
    .WhereBlindEquals(nameof(User.Email), email, hasher)
    .FirstOrDefaultAsync();

After configuring, add a migration and backfill hashes for existing rows:

Queryable ciphertext, without a shadow column

Deterministic mode makes the same plaintext produce the same ciphertext, so ordinary LINQ equality translates straight to SQL — an index seek on the encrypted column itself. It's the alternative to a blind index when you'd rather not add a second column and a second key.

// Randomized (default) — strongest, not queryable:
var provider = new AesGcmCryptoProvider(key);

// Deterministic — equality works server-side:
var provider = new AesGcmCryptoProvider(key, deterministic: true);

How it stays safe

The nonce is derived from the value itself — a synthetic IV, the construction AES-GCM-SIV uses — keyed with a value derived from your encryption key. Fixing one nonce across different plaintexts would leak the authentication subkey and allow forgery; deriving it per value means two different values never share a nonce, and the auth tag still verifies.

Choosing between the three

What the report contains

• Encrypted-property inventory with coverage %
• All scan findings and their severity
• Full alert history
• Accepted risks / [ScanExempt] sign-offs with approver & date
• Key management narrative you provide

Output formats: JSON (machine-readable) + self-contained HTML (print-to-PDF ready). Designed as evidence for DPDP Act 2023 / GDPR Art. 32 audits.

ScanReport scan = await scanner.ScanAsync(dbContext);

ComplianceReport report = generator.Generate(
    dbContext,
    "AES-256-GCM, random 96-bit nonce per value, key ring rotation",
    scan);

File.WriteAllText("compliance.html", generator.ToHtml(report));
File.WriteAllText("compliance.json", generator.ToJson(report));

The report generates and emails itself

Set a cadence and the evidence pack arrives on its own, with both formats attached. Recipients default to a separate list from your alerts — the report names every unprotected column in your schema, so it belongs with compliance rather than the on-call rota.

{
  "EfCryptoML": {
    "Report": {
      "Enabled":     true,
      "Cadence":     "Weekly",       // Daily | Weekly | Monthly | Custom
      "DayOfWeek":   "Monday",       // Weekly
      "DayOfMonth":  1,              // Monthly (1–28)
      "TimeOfDay":   "09:00:00",
      "TimeZoneId":  "Asia/Kolkata", // omit for UTC, or "Local"
      "Recipients":  [ "dpo@acme.example", "audit@acme.example" ]
    }
  }
}

Unconfigured, it runs monthly on the 1st at 06:00 UTC. Custom uses a plain interval — 30 days by default.

Operational guarantees

• A missed window isn't lost. Each run is recorded in a ledger; a window missed while the process was down is sent late rather than skipped.
• One report, not one per replica. Instances sharing a volume claim the run atomically, so three pods send one report between them.
• A failed send releases the claim, so it retries instead of consuming the month.
• Recipients fall back to Email.To when Report.Recipients is empty; with neither set, configuration validation fails at startup.

Or generate one on demand

ScanReport scan = await scanner.ScanAsync(context);

ComplianceReport report = generator.Generate(
    context,
    "AES-GCM 256-bit, keys in Azure Key Vault, rotated 2026-06-01",
    scan,
    recentAlerts);

await File.WriteAllTextAsync("compliance.html", generator.ToHtml(report));
await File.WriteAllTextAsync("compliance.json", generator.ToJson(report));

Offline validation

A licence key is a signed token — RLML1.<payload>.<sig> — verified with ECDSA P-256 against a public key embedded in the package. There is no activation server, no machine fingerprinting and no telemetry, so an air-gapped deployment behaves identically to a connected one.

builder.Services.AddDataEncryptionML(options =>
{
    options.LicenseKey = builder.Configuration["EfCryptoML:LicenseKey"];

    // Auto (default) | Strict | WarnOnly
    options.License.EnforcementMode = LicenseEnforcementMode.Auto;
});

What each mode does where

Environment detection reads environment variables and container markers only — KUBERNETES_SERVICE_HOST, the k8s service-account token, DOTNET_RUNNING_IN_CONTAINER, /.dockerenv, container cgroups, and the Azure / AWS / GCP / Heroku variables. No metadata endpoint is contacted. Override it with options.License.TreatAsProduction.

Your SMTP, your credentials

The package never routes mail through vendor infrastructure. You supply SMTP settings; alerts go out under your identity.

Delivery guarantees

• Retried on failure: 1 s → 5 s → 30 s
• Dead-lettered and logged after all retries — never loses the alert silently
• Critical alerts bypass the digest window and send immediately
• Digest batching: configurable via options.Alerts.DigestWindow

options.Email = new SmtpEmailOptions
{
    Host          = "smtp.office365.com",
    Port          = 587,
    Username      = configuration["Smtp:User"],
    Password      = configuration["Smtp:Pass"],
    From          = "security@yourapp.example",
    To            = { "dpo@yourapp.example" },
    SubjectPrefix = "[yourapp/prod]",
};

Honest performance numbers

Encryption happens in-process inside EF value converters — the database never sees plaintext or keys.

Run benchmarks on your own hardware: