hoeyi / extensions.configuration

Writable and encrypted providers for .NET configuration.

Extensions.Configuration

Extensions.Configuration extends the .NET Configuration API by adding custom providers for writing configurations to disk and encrypting values in-memory and at rest. The cryptography implementation uses symmetric data encryption with keys protected by RSA public/private keypairs private to the user. See Encrypting Data | Microsoft Docs and Key Storage and Retrieval | Microsoft Docs for details. Non-Windows platforms are not supported at this time.

• Building Project
• Code Examples
  • Reserved Keys
• Commit Message Guidelines

Building Project

By default, the project $(BuildNumber) property is set to zero. Uncomment the line Extensions.Configuration.csproj to allow auto-assignment of the build number. Once the build is complete, revert the change to the $(BuilderNumber) property assignment.

Code Examples

Use IConfigurationBuilder extension methods AddJsonWritable and AddSecureJsonWritable to configure custom providers.

Configure a JSON-writable source without encryption.

// Create example configuration and access the property 'InstallDate'.

// Build configuration.
IConfigurationRoot unprotectedConfig = new ConfigurationBuider()
        .AddJsonWritable(
            path: "appsettings.json",
            optional: true,
            reloadOnChange: false);

var installDate = unprotectedConfig["InstallDate"];

Console.WriteLine($"Install date: {installDate}");

Configure a JSON-writable source with encryption.

Values in protected configuration providers are kept as cipher text within the configuration data and when saved to a data store, if it applies. Values are only decrypted when accessed.

// Create example configuration using an RSA key container name and access 
// property 'ConnectionStrings.Production'.

// Create ILogger instance.
ILogger logger = LoggerFactory.Create(b => b).CreateLogger<Program>();

// Build configuration.
IConfigurationRoot protectedConfig = new ConfigurationBuider()
        .AddSecureJsonWritable(
            path: "appsettings.protected.json",
            optional: false,
            reloadOnChange: false,
            encryptionKeyContainer: "MyKeyContainer",
            logger: logger); 

var connString = protectedConfig["ConnectionsStrings:Production"];

Console.WriteLine($"Connection string (prod): {connString}");

Rotating the encryption key.

Providers implementing IRSAProtectedConfigurationProvider allow for rotating all encrypted values to a new key.

// Configurate with encrypted values and rotate the keys to a new key container.
IConfigurationRoot protectedConfig = new ConfigurationBuider()
        .AddSecureJsonWritable(
            path: "appsettings.protected.json",
            optional: false,
            reloadOnChange: true,
            encryptionKeyContainer: "MyKeyContainer",
            logger: logger); 

bool result = protectedConfig.RotateKey(keyContainerName: "MyNewKeyContainer");

Console.WriteLine($"Key rotated: {result}");

Saving values to a file.

Providers implementing IWritableConfigurationProvider allow for saving all values according in the manner prescribed by the provider.

// Configuration with encrypted values, set a value, then save the 
// configuration to 'appsettings.protected.json'.

// Build configuration.
IConfigurationRoot protectedConfig = new ConfigurationBuider()
        .AddSecureJsonWritable(
            path: "appsettings.protected.json",
            optional: false,
            reloadOnChange: true,
            encryptionKeyContainer: "MyKeyContainer",
            logger: logger);

// Set 'ConnectionStrings:Production'
protectedConfig["ConnectionStrings:Production"] = "DataSource=...";

// Save the update value to a JSON file.
protectedConfig.Commit();

Reserved Keys

The following keys are reserved by JsonSecureWritableConfigurationProvider for internal use.

• _file:AesKeyCipher
• _file:RsaKeyContainer

Commit Message Guidelines

Commit message guidelines are meant to mirror the style prescribed in Conventional Commits. Changes to the types and scope have been made.

Commit messages should follow the format:

<type>[optional scope]: <description>
[optional body]
[optional footer]

Type

Must be one of the following:

• build: Changes that affect the build system or external dependencies
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• revert: Reverts commit <hash>.
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• test: Adding missing tests or correcting existing tests

Scope

Scope refers to the domain of the code changed. Choose from the following:

• Cryptography: Cryptographic and key management methods.
• Extensions: Extension and helper methods for the .NET Configuration API.

Example:

feat(Cryptography): add support for Azure key vault

fix(Extensions): fix builder for writable XML source

Subject

The subject contains a succinct description of the change:

• Use the imperative, present tense
• Don't capitalize the first letter
• Don't include punctuation

Body

The body contains the detail of why the change was made:

• Use the imperative, present tense
• Include the motivation for the change with contrast to prior behavior

Footer

The footer contains information on breaking changes. Start with the phrase BREAKING CHANGE:. Also use this space to reference closing GitHub issues.

Example:

BREAKING CHANGE: Ends support for [NAME] API

Resolves #42 (where #42 is the GitHub issue no.)

extensions.configuration's Issues

NuGet package does not include CREDITS page

The NuGet package needs to include the CREDITS.md file in the same directory as LICENSE.md.

Crypographic implementation fails for sufficiently large data

The implementation for encrypting values does not properly consider larger chunks of data, specifically those that are larger than an RSA key pair can handle.

The solution is to use the RSA key pair to encrypt a symmetric key and IV, and use those elements to handle configuration encryption. See Encrypting data | Microsoft Docs for more information.

AESProvider Decrypt method does not check string length before substring method invoked

Summary

The Decrypt(string, string) method is responsible for extracting the cipher text and iv from the given text and decrypting the cipher text. This is done by taking a substring from the given text, which is not checked for length before attempting. This may be causing issues when a value is undefined.

Desired Solution

Evaluate method for better handling of cases where the input string is not long enough to have the expected cipher and iv components.

Extensions.Configuration/Extensions.Configuration/Cryptography/AESProvider.cs

Line 79 in e30031d

public static string Decrypt(string cipherTextWithIV, string aesKey)

Update target framework to latest LTS version

Description

.NET 5 is still the target version of the framework for this project. Update this to .NET 6.0 (LTS).

JsonSecureWritableConfigurationProvider should not have constructor with key container parameter

JsonSecureWritableConfigurationProvider has a public constructor with the parameter keyContainerName. This parameter is unnecessary because the public get/set methods for the provider handle updating the RSA key container field in the configuration. The public constructor should be removed to simplify intended use.

Example

var config = new ConfigurationBuilder()
    .AddSecureJsonWritable(
        path: "appsettings.protected.json",
        logger: logger,
        optional: false,
        reloadOnChange: true)
    .AddUserSecrets<Program>()
    .Build();

string rsaKeyAddress = "_file:RsaKeyContainer";
if (config[rsaKeyAddress] is null)
{
        config[rsaKeyAddress] = $"{KeyContainerName}";
        config.Commit();
}