File Encryption

Starting in Profound.js / Profound API Version 7, the encryptionKey configuration setting is required to use file encryption features. Prior releases used an encryption key built into the product. Encrypted files generated by prior versions will need to be regenerated to work with version 7.

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 encryptionKey for 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:

Features that Require an Encryption Key

The following features require the encryption key to be configured.

Configuration settings

Command-line utilities

Profound.js Framework APIs

Profound API Data Files

  • API Dashboard user file

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