Davasorus.Utility.DotNet.Encryption 2026.2.1.6

Davasorus.Utility.DotNet.Encryption

⚠️ Security Notice

V1 and V2 are retained for backward compatibility with existing ciphertext. Both use unauthenticated AES-CBC with fixed key-derivation parameters and should be considered obfuscation, not encryption, for new code. Use V3 for any new encryption needs.

V3 uses AES-256-GCM with a random IV per message, an authenticated envelope, and caller-supplied key material — no hardcoded secrets, no network dependencies.

Overview

Davasorus.Utility.DotNet.Encryption provides encryption and decryption utilities for .NET applications. The package ships three generations side by side:

• V1 — legacy sync API, AES-CBC, PBKDF2-HMAC-SHA1 ([Obsolete], retained for backward compatibility).
• V2 — async API, AES-CBC, PBKDF2-HMAC-SHA512 ([Obsolete], retained for backward compatibility).
• V3 — AES-256-GCM, authenticated envelope, random IV per message, caller-supplied keys, string/byte[]/Stream overloads. This is the recommended API for new code.

Features

• V3: AES-256-GCM authenticated encryption, random IV per message, embedded key-name for rotation
• V3: string, byte[] / ReadOnlyMemory<byte>, and Stream overloads
• V3: DecryptionResult for expected-failure outcomes; throws only on programmer errors
• V3: zero-on-dispose Client buffers (best-effort in-memory exposure mitigation)
• V1/V2: legacy AES-CBC with PBKDF2, retained for wire compatibility
• .NET 8 compatible
• OpenTelemetry traces + metrics for all three generations

V3 Quickstart

using Microsoft.Extensions.DependencyInjection;
using Tyler.Utility.DotNet.Encryption.V3.Configuration;
using Tyler.Utility.DotNet.Encryption.V3.Service;

// At startup:
var key = Convert.FromBase64String(builder.Configuration["Encryption:Keys:Primary"]!); // 32 bytes
builder.Services.AddEncryptionServicesV3(opts => opts.AddKey("primary", key));

// In a scoped handler:
public class Handler(IEncryptionServiceV3 enc, IDecryptionServiceV3 dec)
{
    public async Task<string> WrapAsync(string secret, CancellationToken ct)
        => await enc.EncryptAsync(secret, "primary", ct);

    public async Task<string?> UnwrapAsync(string cipher, CancellationToken ct)
    {
        var result = await dec.DecryptAsync(cipher, ct);
        return result.Success ? result.Value : null;
    }
}

Lifecycles are fixed (not configurable): IEncryptionServiceV3/IDecryptionServiceV3 are Scoped, IEncryptionClientV3/IDecryptionClientV3 are Transient. The Service resolves a fresh Client per call and disposes it immediately — the Client zeros its key/plaintext buffers on dispose as a best-effort in-memory exposure mitigation.

V3 Envelope Format

Each V3 ciphertext is a base64url-encoded envelope:

The key name is embedded so that decrypt can look up the right key from the registered map. This enables key rotation: register the new key under a new name, start writing with it, and old data continues to decrypt as long as the old key is still registered.

V3 Key Rotation

builder.Services.AddEncryptionServicesV3(opts =>
{
    opts.AddKey("2026-Q1", oldKeyBytes);  // still decrypts old data
    opts.AddKey("2026-Q2", newKeyBytes);  // new data is encrypted under this
});

// App code chooses "2026-Q2" for new writes:
var cipher = await enc.EncryptAsync(value, "2026-Q2");

// Decrypt picks the right key based on the envelope:
var result = await dec.DecryptAsync(cipher);  // works for both 2026-Q1 and 2026-Q2 ciphertext

When you're confident no 2026-Q1 ciphertext remains in the wild, remove it from the registration.

V3 Error Model

• Throws ArgumentNullException, EncryptionKeyNotFoundException, ObjectDisposedException, OperationCanceledException — for programmer errors and cancellation.
• Returns DecryptionResult with Success = false and a DecryptionError for expected-failure decrypt outcomes: InvalidEnvelope, CiphertextTooShort, UnsupportedVersion, UnknownKey, AuthenticationFailed.

Encrypt returns a plain string or byte[] on success (no result-wrapper — encrypt has no expected-failure mode once inputs validate).

Known Limitations

• V3 Stream overloads are buffered, not streaming. AES-GCM's auth tag is computed over the whole message, so the Stream overloads read the full input into memory before encrypting. For payloads larger than tens of megabytes, split or encrypt at the record level.
• Zero-on-dispose is best-effort. V3 Clients zero their local key/plaintext buffers when disposed, but GC compaction may have copied the buffer in managed memory before we zero it. True secret-in-memory safety requires OS-level locked memory, which this package does not provide.
• No forward secrecy. AES-GCM is symmetric — compromise of a key compromises all ciphertext ever produced under that key.
• No replay protection. Ciphertext is a value; same plaintext re-encrypted produces different ciphertext, but the original ciphertext can be replayed. Applications requiring replay protection must handle it at the application layer (timestamps, nonces).
• Offline only. V3 does not integrate with KMS, Key Vault, or any remote key provider. Keys must be supplied locally at DI registration.

OpenTelemetry Integration

This package includes comprehensive OpenTelemetry instrumentation for distributed tracing, metrics, and observability across all encryption and decryption operations (V1, V2, and V3).

Telemetry Data Emitted

Activities (Spans):

• Encryption.EncryptValue - Service-level encryption operations (V2)
• Encryption.Encrypt - Client-level encryption operations (V2)
• Encryption.V1.Encrypt - Legacy encryption operations (V1)
• Decryption.DecryptValue - Service-level decryption operations (V2)
• Decryption.Decrypt - Client-level decryption operations (V2)
• Decryption.V1.Decrypt - Legacy decryption operations (V1)

Tags (Attributes):

• encryption.operation / decryption.operation - Operation type (encrypt/decrypt)
• encryption.input_length / decryption.input_length - Input data length in characters
• encryption.output_length / decryption.output_length - Output data length in characters
• encryption.valid_usage / decryption.valid_usage - Whether the usage type is valid
• encryption.success / decryption.success - Whether the operation succeeded
• encryption.version / decryption.version - API version (v1 for legacy APIs)
• crypto.algorithm - Encryption algorithm used (AES)
• crypto.key_derivation - Key derivation function (PBKDF2-HMAC-SHA512 for V2, PBKDF2-HMAC-SHA1 for V1)
• crypto.iterations - PBKDF2 iteration count (10,000)

Note: The encryption.usage / decryption.usage tags were removed. Because the Usage enum values (Static, Dynamic, api, web, desktop) are effectively the passwords used for V1/V2 PBKDF2 derivation, emitting them as trace tags would broadcast the secret. V3 has no such concern — keys are supplied at DI registration, and only the key name is exposed in traces.

Metrics

Three instruments are emitted (via the shared Telemetry package's MeterHelper):

Events:

• encoding.completed - Unicode encoding phase completed (encryption) with bytes_length
• decoding.completed - Base64 decoding phase completed (decryption) with bytes_length
• crypto.started - Cryptographic operation started
• crypto.completed - Cryptographic operation completed
• exception - Exception occurred with full exception details (type, message, stacktrace)

Configuring Telemetry

The package uses Tyler.Utility.Encryption as the ActivitySource name. To enable telemetry collection, configure OpenTelemetry in your application startup:

using OpenTelemetry.Trace;

// In Program.cs or Startup.cs
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("Tyler.Utility.Encryption") // Enable encryption telemetry
        .AddAspNetCoreInstrumentation()        // Optional: ASP.NET Core tracing
        .AddHttpClientInstrumentation()        // Optional: HTTP client tracing
        .AddConsoleExporter()                  // For development
        // OR for production:
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("http://your-otel-collector:4317");
        })
    );

Trace Context Integration

All encryption and decryption operations automatically include trace context (TraceId, SpanId, ParentSpanId) in structured log messages. This enables seamless correlation between:

• Distributed traces across microservices
• Application logs
• Performance metrics
• Error tracking

Example log output with trace context:

{
  "timestamp": "2025-01-15T10:30:45.123Z",
  "level": "Information",
  "message": "Encryption complete",
  "TraceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "SpanId": "00f067aa0ba902b7",
  "ParentSpanId": "b7ad6b7169203331",
  "InputLength": 256
}

Performance Analysis

The granular events enable detailed performance analysis:

1. Encoding Phase - Time spent converting data to bytes

   • Encryption: Unicode encoding (encoding.completed event)
   • Decryption: Base64 decoding (decoding.completed event)

2. Cryptographic Phase - Time spent in AES operations

   • Between crypto.started and crypto.completed events
   • Includes key derivation (PBKDF2) and encryption/decryption

Use these events in your APM tool to identify bottlenecks and optimize performance.

Security Considerations

No sensitive data is exposed in telemetry:

• ✅ Only metadata is logged (lengths, usage types, algorithms)
• ❌ Plaintext values are never included in traces
• ❌ Encrypted values are never included in traces
• ❌ Encryption keys are never included in traces
• ❌ Salts are never included in traces

Exception messages are captured for debugging, but they do not contain sensitive cryptographic material.

Example: Full Trace

Span: Encryption.EncryptValue [Service]
├─ Tags: encryption.operation=encrypt, encryption.input_length=256
├─ Child Span: Encryption.Encrypt [Client]
│  ├─ Tags: crypto.algorithm=AES, crypto.key_derivation=PBKDF2-HMAC-SHA512, crypto.iterations=10000
│  ├─ Event: encoding.completed (bytes_length=512)
│  ├─ Event: crypto.started
│  ├─ Event: crypto.completed
│  └─ Tags: encryption.output_length=344, encryption.success=true
└─ Status: Ok

Getting Started

1. Reference the library in your .NET project.
2. Register the services and clients with your DI container (see below).
3. Only interact with the service interfaces (IEncryptionService, IDecryptionService) in your application code. The service manages all communication with the client internally.

Note: Do not use the client classes directly in your application code. The service layer encapsulates all client logic, error handling, and logging.

Usage Example

V1 (Synchronous, legacy):

var encrypt = new Encrypt(logger);
var encrypted = encrypt.EncryptValue(model);
var decrypt = new Decrypt(logger);
var decrypted = decrypt.DecryptValue(model);

V2 (Asynchronous, recommended):

// Register services and clients in DI (see below) 

// In your consuming code, inject IEncryptionService and IDecryptionService
public class MyClass
{
    private readonly IEncryptionService _encryptionService;
    private readonly IDecryptionService _decryptionService;

    public MyClass(IEncryptionService encryptionService, IDecryptionService decryptionService)
    {
        _encryptionService = encryptionService;
        _decryptionService = decryptionService;
    }

    public async Task<string> EncryptAndDecrypt(UtilitySettingsModel model)
    {
        var encrypted = await _encryptionService.EncryptValue(model);
        var decrypted = await _decryptionService.DecryptValue(model);
        return decrypted;
    }
}

API Overview

• V1

  • EncryptValue(UtilitySettingsModel model): string
    Synchronously encrypts the provided UtilitySettingsModel and returns the encrypted string. This method is part of the legacy V1 API and is intended for use in synchronous workflows.

  • DecryptValue(UtilitySettingsModel model): string
    Synchronously decrypts the provided UtilitySettingsModel and returns the decrypted string. Use this method when asynchronous processing is not required.

  • Usage enum:

    • api
      For API-based scenarios where encryption/decryption is performed in service endpoints.
    • web
      For web application scenarios, such as encrypting data in web forms or cookies.
    • desktop
      For desktop application scenarios, such as encrypting configuration files or user data.
• V2

  • EncryptValueAsync(UtilitySettingsModel model): Task<string>
    Asynchronously encrypts the provided UtilitySettingsModel. This method is internal to the service and not intended for direct use.

  • DecryptValueAsync(UtilitySettingsModel model): Task<string>
    Asynchronously decrypts the provided UtilitySettingsModel. This method is internal to the service and not intended for direct use.

  • Service API:

    • EncryptValue(UtilitySettingsModel model): Task<string>
      Public asynchronous method to encrypt a UtilitySettingsModel via the service interface.
    • DecryptValue(UtilitySettingsModel model): Task<string>
      Public asynchronous method to decrypt a UtilitySettingsModel via the service interface.

  • Usage enum:

    • Static
      For scenarios where encryption parameters remain constant.
    • Dynamic
      For scenarios where encryption parameters may change per operation.

Service/Client Pattern

• Do not use IEncryptionClient or IDecryptionClient directly.
• Always use IEncryptionService and IDecryptionService in your application code.
• The service handles all error handling, logging, and client interaction.

Key Differences: V1 vs V2

Summary of Improvements in V2

• Fully async/await support for better scalability
• Stronger key derivation (SHA512, named salt)
• Usage enum is more generic (Static/Dynamic)
• Improved error handling and logging
• Interface-based design for easier testing and extension
• Consistent base64 encoding/decoding (replaces '/' with '_' for URLs)
• Strict service/client separation for DI

Dependency Injection (DI) Usage

V2 is designed for modern .NET dependency injection. Use the built-in extension methods from Tyler.Utility.DotNet.Encryption.Configuration:

Recommended: Extension methods (registers both encryption and decryption)

using Tyler.Utility.DotNet.Encryption.Configuration;

// Default (Scoped lifetime)
services.AddEncryptionServices();

// With custom lifetime
services.AddEncryptionServices(config => config.UseTransientLifetime());
services.AddEncryptionServices(config => config.UseSingletonLifetime());

Register only encryption or decryption:

services.AddEncryptionOnly();
services.AddDecryptionOnly();

Manual registration (alternative):

services.AddScoped<IEncryptionService, EncryptionService>();
services.AddScoped<IEncryptionClient, EncryptionClient>();
services.AddScoped<IDecryptionService, DecryptionService>();
services.AddScoped<IDecryptionClient, DecryptionClient>();

Note: Only inject and use IEncryptionService and IDecryptionService in your application code. The service manages all client interactions.

Example Test Cases

• Encrypt and decrypt with all supported usage types
• Handles invalid usage gracefully (returns empty string)
• Logs errors on exceptions
• Async tests for V2

Dependencies

• Davasorus.Utility.Dotnet.Contracts.Collections
• Davasorus.Utility.DotNet.Contracts.Types
• Davasorus.Utility.DotNet.Telemetry
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging.Abstractions

License

MIT License

Contributing

Contributions are welcome! Please submit issues or pull requests for improvements.