Woof.Config 6.0.2

Woof.Config

.NET extension created by CodeDog

Distributed under MIT License. (c)2021 by CodeDog, All rights reserved.

About

A JSON configuration file support for DI free applications.

This is an extension for Microsoft.Extensions.Configuration.IConfiguration that reads, writes and encrypts JSON configuration files.

IConfiguration interface does not allow writing changes. Here it's possible, however it's not super fast, because in order to write the configuration file, the JSON file must be reparsed and rebuilt.

If you really need "real-time" state storage for the Windows application use the registry instead.

Also, the configuration files can be protected with the DataProtection module, both for Linux and Windows. Protected files are encrypted with either local machine keys, or the current user keys.

The keys are built in Windows DPAPI, on Linux they are created in appropriate directories on first use.

The encrypted data cannot be read on different machines or by other users, if the current user protection scope was use to encrypt them.

For Linux they should be placed in the same directory as the entry assembly.

For Windows the configuration files should be placed in the user's local application data subfolder.

The Windows installer should use a folder for configuration files as follows:

[LocalAppDataFolder]\[Manufacturer]\[ProductName].

This is absolutely required if the data protection is used for Windows. It ensures that the each user will have a separate configuration. Per-user installation is also required for the data protection.

The configuration can be read using IConfiguration interface methods, or bound to an object property via Microsoft.Extensions.Configuration.ConfigurationBinder.Bind method.

It can also read some sensitive configuration data from Azure Key Vault.

The default name for the configuration file is the main assembly name with ".json" extenstion.

The access to the configuration file can be restricted with data protection. When DataProtectionScope is provided in the constructor, the configuration will be encrypted on first read, the plain text file will be deleted.

On linux, the application key will be created in:

• /etc/dotnet/dpapi directory for DataProtectionScope.LocalMachine,
• ~/.net/dpapi directory for DataProtectionScope.CurrentUser.

The correct directories will be used even when run with sudo. The access to the protection keys will be restricted to owner user and group.

Use DPAPI.RestrictAccess(user, group) to make keys accessible exclusively to the specified user and group.

Configuration is writeable (use Write() method). Also values can be set with IConfiguration.SetValue() method.

The configuration files can be protected with DataProtection module. On Linux, if the key directory is not set explicitly, it will be set with DPAPI.AutoConfigure() method.

On Windows specifying DataProtectionScope in constructors will make the configuration protected, that is encrypted in the specified protection scope.

Important

ReloadOnChange option of the configuration files has been disabled, since it uses FileSystemWatcher in a way, that leads to resources leak and that causes fatal errors on Linux.

To use the disk file change tracking - use FileSystemWatcher directly with triple-checking that each instance of it MUST BE PROPERLY DISPOSED before the program exits! The resources used by it ARE NOT RETURNED on application exit otherwise!

Usage

Create JSON configuration file in main project directory, set its CopyToOutputDirectory like

<None Update="Config.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>

Optionally, for a different configuration for the DEBUG mode, create another file like

<None Update="Config.dev.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>

Create the IConfiguration instance like

var config = new JsonConfig("Config");

Optionally bind the config instance to configuration object instance with Bind method, see included test project for further details.

To use AKV access, create similar Access.json file in main project directory:

{
    "VaultUri": "[paste your vault URI here]",
    "DirectoryId": "[paste your directory ID here]",
    "ApplicationId": "[paste your application ID here]",
    "ClientSecret": "[paste your client secret here]"
}

Create instance of the AccessData data with:

var accessData = new AccessData("Access", DataProtectionScope.LocalMachine);

Now you can read configured secrets for the application, also, encrypt and decrypt sensitive data using keys defined as secrets in AKV. See the XML documentation of the AccessData class for details.

IMPORTANT: Since the configuration file contains client secret - it is sensitive and when put on a server the access to the file must be restricted! Such configuration should be created with DataProtectionScope.LocalMachine to encrypt it. Also use DPAPI.RestrictAccess() to make the protection keys readable only to the authorized user and group. This will make the protected data accessible only for authorized users.

When revoking client access is needed, it can be done from the AKV level, without touching the application.

Using credentials encryption provided in this module allows to achieve a kind of DPAPI equivalent on Linux servers. All credentials in application database are encrypted and the keys are stored on AKV. Important thing is when the AKV key is lost - the encrypted credentials will not be readable anymore, so on production environments the encryption keys must be backed up.

Compatibility

The package is compatible with .NET 5.0 or newer. The applications using the module can run both on Windows and Linux. For different systems different protection mechanisms are used. For plain configurations this class works identical on both systems.

This package was thoroughly tested on Windows 11 and Ubuntu 20.

Disclaimer

Please report any issues on GitHub.

Woof Toolkit is a work in progress in constant development, however it's carefully maintained with production code quality.