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:
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:
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
databaseConnections (credentialsFile property)
sslOptions (when specified as a file path)
workWithSessions (credentials property)
Command-line utilities
Profound.js Framework APIs
Profound API Data Files
API Dashboard user file
API User file (if not using Security Store DB)