...

Many features use encrypted data files to protect credentials. 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 encryptionKeyfor details.

Troubleshooting Decrypt Failures

The encryption and decryption features include a data integrity check. This ensures that the data is correct when its decrypted. If the integrity check fails, this message will be thrown by the decrypter:

Unsupported state or unable to authenticate data.

This can mean either:

• The data is corrupt

• Trying to decrypt the wrong data – i.e. wrong file path given, etc.

• The data was encrypted with a different encryption key than the one being used for decrypt

• Attempting to decrypt credentials files created by an older version of Profound.js. Version 7 and later cannot read credentials files produced by earlier versions. These files need to be regenerated. See Migrating to Profound.js 7 From Earlier Versions

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)