Encrypt sensitive data

Granit provides two encryption layers — field-level encryption via IStringEncryptionService and Vault Transit encryption via ITransitEncryptionService — so sensitive data (national ID numbers, health records, API keys) is never stored in plaintext.

Prerequisites

• A .NET 10 project with Granit.Core
• Granit.Encryption for AES-256 field-level encryption
• Granit.Vault for vault abstractions (ITransitEncryptionService, IDatabaseCredentialProvider)
• Granit.Vault.HashiCorp for HashiCorp Vault Transit encryption (production)
• Granit.Vault.Azure for Azure Key Vault encryption (production, Azure environments)
• A running HashiCorp Vault or Azure Key Vault instance (production only)

Step 1 — Install the packages

AES-256 (local key)

dotnet add package Granit.Encryption

Vault Transit (production)

dotnet add package Granit.Vault.HashiCorp

Granit.Vault.HashiCorp depends on Granit.Vault and Granit.Encryption — all are installed automatically.

Azure Key Vault (production)

dotnet add package Granit.Vault.Azure

Granit.Vault.Azure depends on Granit.Vault and Granit.Encryption — all are installed automatically. Uses DefaultAzureCredential (Managed Identity in production, az login locally).

Step 2 — Configure encryption

AES-256 provider (development / non-Vault environments)

Add the module dependency and configure the passphrase:

[DependsOn(typeof(GranitEncryptionModule))]
public sealed class AppModule : GranitModule { }

{
  "Encryption": {
    "PassPhrase": "<derived-from-vault-or-secure-store>",
    "ProviderName": "Aes"
  }
}

Warning

Never store PassPhrase in plaintext in appsettings.json. Use environment variables, Vault configuration provider, or a secrets manager. ISO 27001 requires encryption keys to be rotated and stored securely.

Vault Transit provider (production)

[DependsOn(typeof(GranitVaultHashiCorpModule))]
public sealed class AppModule : GranitModule { }

{
  "Vault": {
    "Address": "https://vault.internal:8200",
    "AuthMethod": "Kubernetes",
    "KubernetesRole": "my-backend",
    "TransitMountPoint": "transit"
  },
  "Encryption": {
    "ProviderName": "Vault"
  }
}

The ProviderName setting selects the active provider:

Provider	ProviderName	Latency	When to use
AesStringEncryptionProvider	"Aes"	< 1 ms	Settings, cache, high-frequency operations
VaultStringEncryptionProvider	"Vault"	10—20 ms	High-security operations, HashiCorp Vault
AzureKeyVaultStringEncryptionProvider	"AzureKeyVault"	10—30 ms	High-security operations, Azure environments

Step 3 — Encrypt fields before persistence

Inject IStringEncryptionService to encrypt and decrypt individual fields:

using Granit.Encryption;

namespace MyApp.Services;

public sealed class PatientService(
    AppDbContext db,
    IStringEncryptionService encryption)
{
    public async Task<Guid> CreateAsync(
        string firstName,
        string lastName,
        string nirNumber,
        CancellationToken cancellationToken)
    {
        var patient = new Patient
        {
            FirstName = firstName,
            LastName = lastName,
            NirNumberEncrypted = encryption.Encrypt(nirNumber)
        };

        db.Patients.Add(patient);
        await db.SaveChangesAsync(cancellationToken);

        return patient.Id;
    }

    public string? DecryptNir(string cipherText) =>
        encryption.Decrypt(cipherText);
}

The AES-256-CBC provider generates a random IV for every encryption call (RandomNumberGenerator.GetBytes(16)). The ciphertext format is Base64(IV[16] || CipherText[N]) — the IV is extracted automatically during decryption.

Step 4 — Use Vault Transit for high-security operations

For data that requires centralized key management (encryption keys never leave Vault), use ITransitEncryptionService:

using Granit.Vault;

namespace MyApp.Services;

public sealed class HealthRecordService(ITransitEncryptionService transit)
{
    public async Task<string> EncryptDiagnosisAsync(
        string diagnosis,
        CancellationToken cancellationToken)
    {
        // Key name corresponds to a Transit key in Vault
        var encrypted = await transit.EncryptAsync(
            "health-records", diagnosis, cancellationToken);
        // Returns "vault:v1:..." -- version-tagged ciphertext
        return encrypted;
    }

    public async Task<string> DecryptDiagnosisAsync(
        string cipherText,
        CancellationToken cancellationToken) =>
        await transit.DecryptAsync(
            "health-records", cipherText, cancellationToken);
}

Pro tip

Vault Transit supports transparent key rotation. When you rotate the key in Vault, old ciphertexts remain readable (the key version is embedded in the ciphertext prefix vault:v1:..., vault:v2:...). No re-encryption of existing data is needed.

Step 5 — Encrypt cached values

For data stored in Redis or another distributed cache, use the [CacheEncrypted] attribute to enable transparent AES-256 encryption of cached values:

using Granit.Caching;

namespace MyApp.Caching;

[CacheEncrypted]
public sealed class PatientCacheItem
{
    public Guid Id { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
}

The ICacheService<PatientCacheItem> automatically encrypts before writing to Redis and decrypts after reading. Even if the cache backend is compromised, the data is unreadable.

public sealed class PatientCacheService(
    ICacheService<PatientCacheItem> cache,
    AppDbContext db)
{
    public async Task<PatientCacheItem?> GetAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var cacheKey = $"patient:{id}";

        var cached = await cache.GetAsync(cacheKey, cancellationToken);
        if (cached is not null)
        {
            return cached;
        }

        var patient = await db.Patients.FindAsync([id], cancellationToken);
        if (patient is null)
        {
            return null;
        }

        var item = new PatientCacheItem
        {
            Id = patient.Id,
            FirstName = patient.FirstName,
            LastName = patient.LastName
        };

        await cache.SetAsync(cacheKey, item, cancellationToken);
        return item;
    }
}

Step 6 — Encrypt settings automatically

Settings declared with IsEncrypted = true are encrypted at rest in the database. The cache stores plaintext to avoid double encryption (Redis is already protected by AesCacheValueEncryptor):

public sealed class AppSettingDefinitionProvider : ISettingDefinitionProvider
{
    public void Define(ISettingDefinitionContext context)
    {
        context.Add(new SettingDefinition("Integrations.ExternalApiKey")
        {
            IsEncrypted = true,
            IsVisibleToClients = false,
            Providers = { GlobalSettingValueProvider.ProviderName }
        });
    }
}

Encryption architecture summary

Layer	Mechanism	Scope	Key management
Field-level (AES)	IStringEncryptionService	Individual entity properties	Passphrase via PBKDF2
Field-level (Vault Transit)	ITransitEncryptionService	Individual entity properties	Vault-managed, auto-rotation
Field-level (Azure Key Vault)	IStringEncryptionService	Individual entity properties	Azure Key Vault RSA-OAEP-256
Cache	[CacheEncrypted]	Entire cached object	Local AES-256 key
Settings	IsEncrypted = true	Setting values in database	IStringEncryptionService

Next steps

• Manage application settings — encrypted settings with cascading resolution
• Vault and Encryption reference — full API and configuration reference
• Observability reference — monitor encryption operations with OpenTelemetry