Serilog.Sinks.File.Decrypt 6.0.0-preview.1

Serilog.Sinks.File.Decrypt

A library for decrypting log files encrypted with Serilog.Sinks.File.Encrypt.

Installation

dotnet add package Serilog.Sinks.File.Decrypt

For ad-hoc decryption from the command line, install the CLI tool:

dotnet tool install --global Serilog.Sinks.File.Encrypt.Cli

Quick Start

using Serilog.Sinks.File.Decrypt;
using Serilog.Sinks.File.Decrypt.Models;

// Load your RSA private key
string privateKey = File.ReadAllText("private_key.xml");

var options = new DecryptionOptions
{
    KeyProvider = new LocalKeyProvider("my-app-key-2026", privateKey)
};

// Decrypt a file
DecryptionResult result = await DecryptionUtils.DecryptLogFileAsync(
    "logs/app.log",
    "logs/app-decrypted.log",
    options
);

Key Rotation

When your application has rotated keys over time, supply all active private keys to LocalKeyProvider. The key ID embedded in each session header selects the correct key automatically.

using Serilog.Sinks.File.Decrypt;
using Serilog.Sinks.File.Decrypt.Models;

string oldPrivateKey = File.ReadAllText("./keys/private_key_2025.xml");
string newPrivateKey = File.ReadAllText("./keys/private_key_2026.xml");

var keyMap = new Dictionary<string, string>
{
    { "my-app-key-2025", oldPrivateKey },
    { "my-app-key-2026", newPrivateKey },
};

using LocalKeyProvider keyProvider = new LocalKeyProvider(keyMap);
var options = new DecryptionOptions { KeyProvider = keyProvider };

await DecryptionUtils.DecryptLogFileAsync("logs/app.log", "logs/app-decrypted.log", options);

Programmatic Decryption

using Serilog.Sinks.File.Decrypt;
using Serilog.Sinks.File.Decrypt.Models;

var keyMap = new Dictionary<string, string>
{
    { "my-app-key-2026", File.ReadAllText("private_key.xml") },
};
using LocalKeyProvider keyProvider = new LocalKeyProvider(keyMap);

var options = new DecryptionOptions { KeyProvider = keyProvider };

// File-to-file
await DecryptionUtils.DecryptLogFileAsync("logs/app.log", "logs/decrypted.log", options);

// Stream-to-stream (memory-efficient for large files)
using var input  = File.OpenRead("large-log.encrypted");
using var output = File.Create("large-log.decrypted");
await DecryptionUtils.DecryptLogFileAsync(input, output, options);

Error Handling

Choose how the decryption engine responds to corrupted or unreadable sections:

// Skip corrupted sections silently (DEFAULT — recommended for production)
var skipOptions = new DecryptionOptions
{
    KeyProvider = keyProvider,
    ErrorHandlingMode = ErrorHandlingMode.Skip
};

// With audit logging — pass any Serilog ILogger to capture error details
ILogger auditLogger = new LoggerConfiguration()
    .WriteTo.File("decryption-audit.log")
    .CreateLogger();
await DecryptionUtils.DecryptLogFileAsync(input, output, skipOptions, auditLogger);

// Throw on first error (strict validation)
var strictOptions = new DecryptionOptions
{
    KeyProvider = keyProvider,
    ErrorHandlingMode = ErrorHandlingMode.ThrowException
};

try
{
    await DecryptionUtils.DecryptLogFileAsync(input, output, strictOptions);
}
catch (CryptographicException ex)
{
    Console.WriteLine($"Decryption failed: {ex.Message}");
}

Verifying completeness (seal status)

Logs written in the v2 format (v6.0.0+) end each cleanly closed session with an authenticated seal record carrying the final frame count. After decryption, inspect the per-session results:

DecryptionResult result = await DecryptionUtils.DecryptLogFileAsync(input, output, options);

foreach (SessionResult session in result.Sessions)
{
    switch (session.SealStatus)
    {
        case SealStatus.Sealed:
            // Verified complete: cleanly closed, no trailing frames removed.
            break;
        case SealStatus.Unsealed:
            // The writer crashed OR the tail was truncated — indistinguishable by design.
            // The decrypted messages themselves are authentic.
            break;
        case SealStatus.SealCountMismatch:
            // The seal is authentic but declares more frames than were decrypted:
            // the tail of a cleanly closed log was truncated.
            Console.WriteLine(
                $"Session {session.Index}: expected {session.DeclaredFrameCount}, got {session.DecryptedMessages}");
            break;
        case SealStatus.SealInvalid:
            // Tampering or corruption at the end of the session.
            break;
        case SealStatus.NotApplicable:
            // v1-format session (pre-v6 writer): no seal support.
            break;
    }
}

// Convenience aggregates
bool trustworthy = result.AllSessionsSealed;   // every session Sealed or v1
int suspect      = result.UnsealedSessions;    // Unsealed + SealCountMismatch + SealInvalid

For a strict audit posture, set RequireSealed — combined with ErrorHandlingMode.ThrowException, any session that is not cryptographically verified as sealed (including all v1 sessions) throws:

var auditOptions = new DecryptionOptions
{
    KeyProvider = keyProvider,
    ErrorHandlingMode = ErrorHandlingMode.ThrowException,
    RequireSealed = true,
};

Custom Key Provider

Implement IKeyProvider to integrate with external key management systems (Azure Key Vault, AWS KMS, etc.):

using Serilog.Sinks.File.Decrypt.Interfaces;

public class AzureKeyVaultProvider : IKeyProvider
{
    public async Task<byte[]> DecryptAsync(
        string keyId,
        ReadOnlyMemory<byte> cipherText,
        CancellationToken cancellationToken = default)
    {
        // Use Azure SDK to decrypt with the key identified by keyId
        // ...
    }

    public async Task<int> GetKeySizeAsync(
        string keyId,
        CancellationToken cancellationToken = default)
    {
        // Return the RSA key size in bits for the given keyId
        // ...
    }
}

API Reference

DecryptionUtils

// Stream-to-stream async decryption
Task<DecryptionResult> DecryptionUtils.DecryptLogFileAsync(
    Stream inputStream,
    Stream outputStream,
    DecryptionOptions options,
    ILogger? logger = null,
    CancellationToken cancellationToken = default)

// File-to-file async decryption
Task<DecryptionResult> DecryptionUtils.DecryptLogFileAsync(
    string encryptedFilePath,
    string outputFilePath,
    DecryptionOptions options,
    ILogger? logger = null,
    CancellationToken cancellationToken = default)

IKeyProvider

public interface IKeyProvider
{
    // Decrypts the AES-GCM session key using the RSA private key for the given keyId.
    Task<byte[]> DecryptAsync(
        string keyId,
        ReadOnlyMemory<byte> cipherText,
        CancellationToken cancellationToken = default);

    // Returns the RSA key size in bits for the given keyId.
    // Used to determine how many bytes to read from the session header.
    Task<int> GetKeySizeAsync(string keyId, CancellationToken cancellationToken = default);
}

DecryptionOptions

public sealed record DecryptionOptions
{
    public required IKeyProvider KeyProvider { get; init; }
    public ErrorHandlingMode ErrorHandlingMode { get; init; } = ErrorHandlingMode.Skip;

    // Treat sessions without a verified seal (crashed, truncated, or v1-format) as errors.
    // Only fatal together with ErrorHandlingMode.ThrowException.
    public bool RequireSealed { get; init; } = false;
}

ErrorHandlingMode

public enum ErrorHandlingMode
{
    Skip           = 0,  // Skip corrupted sections silently (DEFAULT)
    ThrowException = 1   // Throw CryptographicException on first error
}

DecryptionResult

public sealed class DecryptionResult
{
    public int DecryptedSessions { get; init; }
    public int DecryptedMessages { get; init; }
    public int FailedHeaders     { get; init; }
    public int FailedMessages    { get; init; }
    public int ResyncAttempts    { get; init; }

    // Per-session detail, in the order sessions appear in the file
    public IReadOnlyList<SessionResult> Sessions { get; init; }
    public int UnsealedSessions  { get; }   // Unsealed + SealCountMismatch + SealInvalid
    public bool AllSessionsSealed { get; }  // every session Sealed or NotApplicable (v1)
}

SessionResult

public sealed record SessionResult
{
    public required int Index { get; init; }            // order encountered in the file
    public required byte FormatVersion { get; init; }   // 1 or 2
    public string KeyId { get; init; }
    public required SealStatus SealStatus { get; init; }
    public ulong? DeclaredFrameCount { get; init; }     // from an authenticated seal
    public int DecryptedMessages { get; init; }
    public int FailedMessages { get; init; }
}

SealStatus

public enum SealStatus
{
    NotApplicable     = 0,  // v1 session — format has no seal
    Sealed            = 1,  // seal verified, frame count matches: complete
    Unsealed          = 2,  // no seal: crash OR truncation (indistinguishable)
    SealCountMismatch = 3,  // seal authentic, frames missing: tail truncated
    SealInvalid       = 4,  // seal failed verification: tampering/corruption
}

Security Considerations

• Keep private keys secure; never include them in application deployment artifacts
• Store private keys in secure key management systems in production (Azure Key Vault, AWS Secrets Manager, etc.)
• Restrict filesystem access to encrypted log files and private keys
• Use 2048-bit RSA keys minimum (4096-bit for enhanced security)

Versioning

All packages in this repository (Serilog.Sinks.File.Encrypt, Serilog.Sinks.File.Decrypt, Serilog.Sinks.File.Encrypt.Cli, Serilog.Sinks.File.Encrypt.Core) are released in lockstep. Every package is versioned and published together on every release, even when a change only affects one of them. Always use the same version across all packages you reference.

Requirements

• .NET 8.0 (LTS) or .NET 10.0 (LTS), or a compatible higher runtime — see the support policy
• Log files created with Serilog.Sinks.File.Encrypt v3.0.0 or later

Related Packages