Many features use encrypted data files to protect credentials. Starting in version 7, all built-in encryption features require a user-defined encryption key to be specified via the encryptionKey configuration setting. If the encryption key is not specified, an error message like this will display when attempting to use encryption features:

This feature requires an encryption key.

If this error occurs while validating the configuration file at server start up time, the server will fail to start, and the message above will appear in the server’s stderr (standard error) output.

To enable encryption features and resolve this error, it’s necessary to generate an encryption key and populate it in the encryptionKey configuration setting.

Generating An Encryption Key

All built-in encryption features use the AES-256-GCM algorithm. The encryption key is a sequence of 32-bytes. Each byte should be an unpredictable random value.

A command-line utility named gen_key.js is provided in the product installation library to generate encryption keys. gen_key.js uses the Node.js crypto.randomBytes() API to generate cryptographically strong random bytes.

This command will generate a key and write it to a file named ekey in the product installation library:

node gen_key.js

A command like this can be used to output to a different file:

node gen_key.js --out-file my_key

Other output options are available for advanced usage. This command will show all available options:

node gen_key.js --help

Encryption Key Storage / Handling

Anyone with access to the encryption key can retrieve data from files encrypted with it. Make sure to protect the key by storing it in a secure location, setting file system permissions appropriately, etc.

Specifying the Encryption Key in the Configuration File

See encryptionKey for details.

Features that Require an Encryption Key

The following features require the encryption key to be configured.

Configuration settings

• basicAuthCredentials

• connectorCredentials

• databaseConnections (credentialsFile property)

• sslOptions (when specified as a file path)

• workWithSessions (credentials property)

Command-line utilities

• store_credentials.js

• store_options.js

Profound.js Framework APIs

• pjs.encrypt()

• pjs.decrypt()

Profound API Data Files

• API Dashboard user file

• API User file (if not using Security Store DB)