Easy and secure configuration management. JSON based - AES encrypted secrets - HMAC validation - env var export
npm install @tsmx/secure-config
!npm (scoped)
!node-current (scoped)
> Easy and secure configuration management.
Manage JSON based configurations with AES encrypted secrets for multiple environments/stages.
Optional features:
- HMAC validation of configurations to ensure data integrity
- Setting of environment variables out of configuration items
Works with CommonJS and ESM/ECMAScript. Ships with a SBOM to meet regulatory requirements.
If you are upgrading from an older version prior to 2.x please read this important note.
1. Encrypt sensitive data in your JSON configuration file. Easiest way to do this is using the secure-config-tool.
For more details please see generating an encrypted configuration and naming conventions.
``json`
{
"database": {
"host": "127.0.0.1",
"user": "ENCRYPTED|50ceed2f97223100fbdf842ecbd4541f|df9ed9002bfc956eb14b1d2f8d960a11",
"pass": "ENCRYPTED|8fbf6ded36bcb15bd4734b3dc78f2890|7463b2ea8ed2c8d71272ac2e41761a35"
}
}
2. Use your configuration in the code.
`js
// CommonJS
const conf = require('@tsmx/secure-config')();
// ESM
import secureConfig from '@tsmx/secure-config';
const conf = secureConfig();
function MyFunc() {
let dbHost = conf.database.host; // = '127.0.0.1'
let dbUser = conf.database.user; // = 'MySecretDbUser'
let dbPass = conf.database.pass; // = 'MySecretDbPass'
//...
}
`
For further customization and advanced features like HMAC validation and the setting of env vars you can pass an options object - please refer to the options section.
3. Run your app. See below for different options on how to pass the key.
`bash`
$ export CONFIG_ENCRYPTION_KEY=...
$ node app.js
A fully working example project is also available on GitHub.
To get all information please also check out the full documentation.
You can have multiple configuration files for different environments or stages. They are distinguished by the environment variable NODE_ENV. The basic configuration file name is config.json if this variable is not present. If it is present, a configuration file with the name config-[NODE_ENV].json
is used. An exception will be thrown if no configuration file is found.
To change the default configuration file name or loading multiple configuration files you can pass the prefix option.
By default, all configuration files are expected be located in a conf/ directory of the current running app, meaning a direct subdirectory of the current working directory (CWD/conf/). To overwrite this behaviour, you can pass the directory option.
| Stage | Value of NODE_ENV | Filename |
|-------------|-------------------|-----------------------------|
| Development | not set | conf/config.json |
| Production | production | conf/config-production.json | test
| Test | | conf/config-test.json |
Resulting folders/files setup:
`
path-to-your-app/
├── conf/
│ ├── config.json
│ ├── config-production.json
│ └── config-test.json
├── app.js
└── package.json
To retrieve a configuration using all default values and without advanced features, you simply invoke a function after the require/import statement without any argument (set of parenthesis after require or simple method call after import).
`js
// CommonJS
const conf = require('@tsmx/secure-config')();
// ESM
import secureConfig from '@tsmx/secure-config';
const conf = secureConfig();
`
To make use of the more advanced features and customize default values, you can pass an options object to this function call.
`js
const confOptions = {
keyVariable: 'CUSTOM_CONFIG_KEY',
hmacValidation: true,
hmacProperty: '_signature',
directory: '/path/to/config',
prefix: 'myconf',
envVarExports: [
{ key: 'database.user', envVar: 'DB_USER' },
{ key: 'database.password', envVar: 'DB_PASSWORD' }
]
}
// CommonJS
const conf = require('@tsmx/secure-config')(confOptions);
// ESM
import secureConfig from '@tsmx/secure-config';
const conf = secureConfig(confOptions);
`
The following options are available.
Type: String
Default:
The name of the environment variable containing the key for decrypting configuration values and validating the HMAC. See also options on how to pass the key.
Type: Boolean
Default:
Specifies if the loaded configuration should be validated against a given HMAC. If set to true, secure-config will validate the HMAC of the decrypted configuration content against a given HMAC using the current key. If the validation fails, an exception will be thrown. If it succeeds, the decrypted configuration will be returned.
The given HMAC is retrieved from a configuration file property with the name of hmacProperty, e.g.:
`json`
{
"database": {
"host": "127.0.0.1",
"user": "ENCRYPTED|50ceed2f97223100fbdf842ecbd4541f|df9ed9002bfc956eb14b1d2f8d960a11",
"pass": "ENCRYPTED|8fbf6ded36bcb15bd4734b3dc78f2890|7463b2ea8ed2c8d71272ac2e41761a35"
},
"__hmac": "3023eb8cf76894c0d5c7f893819916d876f98f781f8944b77e87257ef77c1adf"
}
Enabling this option is recommended for production environments as it adds more security to your configuration management ensuring the loaded configuration is safe against tampering. Unwanted modifications of any - even unencrypted - entries in your configuration would cause the HMAC validation to fail and throw the error HMAC validation failed.
Please ensure that your stored configuration files have an appropriate HMAC property before enabling this option. Otherwise loading the configuration would always fail. secure-config-tool adds the HMAC by default when creating secured configuration files.
To get more information on how the HMAC creation & validation works under the hood, please refer to the package object-hmac which is used for that. The HMAC value is created out of the entire configuration object before optional encryption is applied.
Type: String
Default:
The name of the HMAC property in a configuration file to be validated against. Only used when hmacValidation is set tor true.
Example configuration file using a custom HMAC property name:
`json`
{
"database": {
"host": "127.0.0.1",
"user": "ENCRYPTED|50ceed2f97223100fbdf842ecbd4541f|df9ed9002bfc956eb14b1d2f8d960a11",
"pass": "ENCRYPTED|8fbf6ded36bcb15bd4734b3dc78f2890|7463b2ea8ed2c8d71272ac2e41761a35"
},
"_signature": "3023eb8cf76894c0d5c7f893819916d876f98f781f8944b77e87257ef77c1adf"
}
Loading the configuration with HMAC validation enabled:
`js`
const confOptions = {
hmacValidation: true,
hmacProperty: '_signature'
}
const conf = require('@tsmx/secure-config')(confOptions);
Type: String
Default:
Use this parameter to change the directory where the configuration files should be loaded from.
E.g. if the files are located under /var/myapp/configurations:
`js`
const confOptions = {
directory: '/var/myapp/configurations'
}
const conf = require('@tsmx/secure-config')(confOptions);
This option can be combined with the prefix option to control the configuration filenames within the directory. Naming conventions according to NODE_ENV are applied as normal.
Hint: Setting a relative path within the current running app or an unit-test can easily be achieved by using path.join with process.cwd. E.g. if the files are located in ./test/configurations.
`js`
const confOptions = {
directory: path.join(process.cwd(), 'test/configurations')
}
Type: String
Default:
Use this parameter to change the default file name pattern from config-[NODE_ENV].json to [prefix]-[NODE_ENV].json for loading files with deviating names or additional ones. The value of NODE_ENV will be evaluated as described in the naming conventions.
To load multiple configurations, use the following pattern in your code.
`js`
const secureConf = require('@tsmx/secure-config');
const config = secureConf();
const myconf = secureConf({ prefix: 'myconf', keyVariable: 'MYCONF_KEY' });
This example will load the default config.json using the the key from environment variable CONFIG_ENCRYPTION_KEY as well as the additional myconf.json using the key from MYCONF_KEY. Note that different configurations should use different encryption keys.
Depending on the value of NODE_ENV the following configuration files will be loaded in this example.
| Value of NODE_ENV | variable | Filename |
|-------------------|----------------------|------------------------------------------------------------|
| not set | config | conf/config.jsonproduction
conf/myconf.json |
| | config | conf/config-production.jsontest
conf/myconf-production.json |
| | config | conf/config-test.json
conf/myconfig-test.json |
Type: Array
Default:
With the envVarExports option (or alternatively the __envVarExports configuration key) you can set environment variables out of configuration items by passing an array of objects each having a key and envVar property where:key
- is the name of a configuration item, if the configuration item is not at the top level of the configuration JSON, simply pass the full path to it using dotted notation (see example below)envVar
- is the name of the environment variable to be set with the value of the configuration item
- both properties must be of type string
Suppose you have the following configuation...
`json`
{
"database": {
"host": "127.0.0.1",
"user": "ENCRYPTED|50ceed2f97223100fbdf842ecbd4541f|df9ed9002bfc956eb14b1d2f8d960a11",
"pass": "ENCRYPTED|8fbf6ded36bcb15bd4734b3dc78f2890|7463b2ea8ed2c8d71272ac2e41761a35"
}
}
...and need to set the database user and password as environment variables DB_USER and DB_PASSWORD. Then simply pass the following envVarExports array either programmatically or directly in the configuration via the __envVarExports key.
Programmatic passing:
`js`
const envVarExports = [
{ key: 'database.user', envVar: 'DB_USER' },
{ key: 'database.pass', envVar: 'DB_PASSWORD' }
];
const conf = require('@tsmx/secure-config')({ envVarExports });
Passing via configuration:
`JSON`
{
"database": {
"host": "127.0.0.1",
"user": "ENCRYPTED|50ceed2f97223100fbdf842ecbd4541f|df9ed9002bfc956eb14b1d2f8d960a11",
"pass": "ENCRYPTED|8fbf6ded36bcb15bd4734b3dc78f2890|7463b2ea8ed2c8d71272ac2e41761a35"
},
"__envVarExports": [
{
"key": "database.user",
"envVar": "DB_USER"
},
{
"key": "database.pass",
"envVar": "DB_PASSWORD"
}
]
}
Both approaches will automatically set the env vars DB_USER and DB_PASSWORD with the decrypted configuration item values.
Notes:
- If the envVarExports array contains multiple entries having the exact same key, only the first entry will be considered.envVarExports
- If contains entries that cannot be found in the configuration, no env var will be set and no error will be thrown.envVarExports
- If the option AND the __envVarExports configuration key both are present, the programmatic passed array will take precedence.
The key for decrypting the encrypted values is derived from an environment variable. The default name of this variable is CONFIG_ENCRYPTION_KEY, but you can also pass any other name via options. You can set the environment variable whatever way is most suitable, e.g.
- set/export in the command line or in your bash pofile
`
export CONFIG_ENCRYPTION_KEY=0123456789qwertzuiopasdfghjklyxc
- using an env block in your VS-Code launch configuration
json`
"env": {
"CONFIG_ENCRYPTION_KEY": "0123456789qwertzuiopasdfghjklyxc"
}
- using an env block in your deployment descriptor, e.g. app.yaml for Google App Engine
yaml`
env_variables:
CONFIG_ENCRYPTION_KEY: "0123456789qwertzuiopasdfghjklyxc"
- for testing with Jest I recommend to create a test key and set it globally for all tests in the , e.g.`
javascript
process.env['CONFIG_ENCRYPTION_KEY'] = '0123456789qwertzuiopasdfghjklyxc';
module.exports = {
testEnvironment: 'node'
};
`
- etc.
More examples are available in the full documentation.
The key length must be 32 bytes! The value set in CONFIG_ENCRYPTION_KEY has to be:
- a string of 32 characters length, or
- a hexadecimal value of 64 characters length (= 32 bytes)
Otherwise an error will be thrown.
Examples of valid key strings:
- 32 byte string: MySecretConfigurationKey-123$%&/
- 32 byte hex value:
Different keys for each configuration environment are strongly recommended.
For better convenience I provided a very basic secure-config-tool to easily generate encrypted configuration files with an optional HMAC.
You can also simply use crypto functions from NodeJS with the following snippet to create the encrypted entries in a configuration file on your own:
`js
const crypto = require('crypto');
const algorithm = 'aes-256-cbc';
function encrypt(value) {
let iv = crypto.randomBytes(16);
let key = Buffer.from('YOUR_KEY_HERE');
let cipher = crypto.createCipheriv(algorithm, key, iv);
let encrypted = cipher.update(value);
encrypted = Buffer.concat([encrypted, cipher.final()]);
return 'ENCRYPTED|' + iv.toString('hex') + '|' + encrypted.toString('hex');
}
`
The generated encrypted entry must always have the form: ENCRYPTED | IV | DATA.
| Part | Description |
|-------------|-------------|
| ENCRYPTED | The prefix ENCRYPTED used to identify configuration values that must be decrypted. |IV
| | The ciphers initialization vector (IV) that was used for encryption. Hexadecimal value. |DATA
| | The AES-256-CBC encrypted value. Hexadecimal value. |
In versions before 2.x, secure-config directly exported the configuration object when requiring in the module. To add more flexibility and being able to provide new features, this was changed in the 2.x versions. The module now exports a function which can receive additional options.
Since there's a full backward compatibility, all you have to do in your existing code using version 1.x so far is to invoke the function by adding a set of parenthesis.
`js
// version 1.x - requiring in without any function call
const conf = require('@tsmx/secure-config');
// version 2.x - change to that for retaining full backward compatibility
const conf = require('@tsmx/secure-config')();
// use conf as you did before...
`
This package ships with a CycloneDX software bill of materials (SBOM) v1.6 in JSON format as required by some regulatory like the BSI TR-03183. The file is located under the sbom folder.