TwJackysu.CipherLib 1.0.0

CipherLib

A quick way to encrypt specific fields in appsettings.json for .NET services running on-premises.

If your service is hosted on a cloud platform, use a managed secret store instead (e.g. Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) — they provide stronger security guarantees and centralised rotation without requiring this library.

CipherLib is designed for on-prem jobs that run without internet access — scenarios where reaching a managed secret store is not an option. It encrypts sensitive fields at rest inside appsettings.json using AES-256-CBC with PBKDF2-SHA256 key derivation (600,000 iterations per NIST SP 800-132), so plaintext secrets are never committed to source control.

Installation

dotnet add package TwJackysu.CipherLib

Getting Started

Assuming your appsettings.json is:

{
    "SomeApi": {
        "EndPoint": "https://fakeapi.com/resource",
        "Secret": "yourSecret"
    },
    "SomeOtherSetting": "Some text that doesn't need to be encrypted",
    "DBConnection": "Server=YourSQLServer;Database=YourDB;Persist Security Info=True;User ID=YourUser;Password=YourPassword;"
}

Replace AddJsonFile with AddProtectedJsonFile and provide a password plus regex patterns for the fields to encrypt:

using CipherLib.Extensions;

// Obtain the password from a safe source — never hard-code it.
var password = Environment.GetEnvironmentVariable("CONFIG_PASSWORD")!;

var configuration = new ConfigurationBuilder()
    .AddProtectedJsonFile(
        password,
        "appsettings.json",
        optional: false,
        reloadOnChange: true,
        new Regex("SomeApi:Secret"),
        new Regex("DBConnection"))
    .Build();

On the first run the matched fields are encrypted in-place inside appsettings.json on disk. Subsequent runs detect the !ENCRYPTv2! prefix and skip re-encryption. Values are transparently decrypted when read through IConfiguration.

Committing encrypted config to Git

The library writes the encrypted values into the output directory copy of appsettings.json (e.g. bin/Debug/net10.0/appsettings.json), not the source file. To persist the result back to your repository:

1. Run the application once so the output-directory file gets encrypted.
2. Copy the encrypted file back over your source appsettings.json:

   # example — adjust the path to match your project and target framework
   cp bin/Debug/net10.0/appsettings.json appsettings.json
   

3. Commit the updated appsettings.json. The plaintext secrets are gone; only the ciphertext is in the file.

The next developer (or CI) who checks out the repo just needs the correct password to run the app — no re-encryption will occur because the values are already marked as encrypted.

See the TestExample project for a runnable example.

Supported Frameworks

• .NET 8
• .NET 9
• .NET 10

Migrating from v1.x (⚠ Breaking Change)

v2.0.0 upgrades the encryption algorithm (AES-128/SHA-1/1,000 iterations → AES-256/SHA-256/600,000 iterations) and changes the encrypted-value prefix from !ENCRYPT! to !ENCRYPTv2!.

Old encrypted values are not compatible with v2. Before upgrading:

1. Restore the original plaintext values in your appsettings.json.
2. Upgrade the package.
3. Run the application once — the library will re-encrypt with the new parameters automatically.

Security Notes

A symmetric password is used for encryption. Use a safe delivery mechanism such as an environment variable, a secrets file outside the repo, or a local key-management solution. The security of the encrypted config is only as strong as how well the password itself is protected.

Which articles were referenced is noted in the source code comments.