JasperReports Server 7.5 introduces a change in the use of encryption to improve the management of secured values in the JasperReports Server repository, web application, APIs and import/export processes.
TL;DR
Here are the 7.5 encryption changes and what you MUST do to have successful deployment and use of the Server. More advanced use cases are covered later in this document.
Keystore files
There are keystore files created during installation and upgrade that now need to be managed carefully. The JasperReports Server will not start and the command line tools will not work if the keystore files are missing or invalid for a given repository.
What you have to do:
Backup and restore your keystore files at the same time as your repository
Make sure the keystore files are accessible by the web app and command line
Export/Import
Repository exports from one JasperReports Server deployment/repository contain encrypted values that will not automatically import into a different deployment/repository.
If the keystore files related to an export are not acceptable for the deployment being imported into, the import will fail
Exports from versions of JasperReports Server 7.2 and below will import into 7.5+ deployments
What you have to do:
If you want to have export and import work easily across all the JasperReports Server 7.5+ deployments you control:
Save the set of keystore files from the first environment you install
Configure the keystore files to be used before the install/upgrade process is executed in a new environment
This will work across export/import in the JasperReports Server user interface, REST API and command line
Note that, using this approach, secured values from one environment, ie. production, can be successfully imported into other environments. This exposes secured values in a way that may not be acceptable according to your security requirements.
If you want to have an export that is import-able by anyone, including outside your organization:
You must use the JasperReports Server command line tools
Export from command line:
js-export --<what to export> --output-zip export_what_to_export.zip --keyalias deprecatedImportExportEncSecret
Import from command line:
./js-import.sh --input-zip export_what_to_export.zip --keyalias deprecatedImportExportEncSecret
Keystore files
The encryption process is based on “keystore related files” on the operating system where the JasperReports Server processes are running:
.jrsks - Java keystore file
.jrsksp - keystore properties
Java properties file
Base64 encoded
Managed through provided tools - cannot edit directly
Decode to see with `cat ~/.jrsksp | openssl base64 -d`
By default, these are created in the user home directory of the operating system user running install/upgrade.
These files MUST be available to the JasperReports Server and related command line tools in order to encrypt and decrypt values.
The key related files created or present at the installation or upgrade time for a given repository database MUST be used going forward.
Without those keystore files, secure values in a repository cannot be accessed.
The keystore files need to be backed up along with the repository.
A JasperReports Server instance must be given the keystore files for the repository instance it is connecting to.
Keystore files for the JasperReports Server web application
Keystore file locations are defined - in precedence order:
“ks” and “ksp” environment variables
WEB-INF/classes/keystore.init.properties: ks, ksp properties
This properties file and the keystore files are deployed automatically to the JRS web application via the command line tools.
If you are not using the command line tools to deploy and update the JasperReports Server web application, you will need to manage the deployment of these files and environment variables yourself.
By default during installation and upgrade, the keystore files go into the user home directory. This can cause problems if the web app runs as a different user that the user used to install, ie.:
Installed/upgraded JasperReports Server as root user
By default, keystore files were generated into /root
.jrsksp property ksPath = /root/.jrsks
The web app is run as tomcat
Tomcat fails to start, as the tomcat user does not have access to /root.
If the JasperReports Server cannot find the keystore files - maybe because of permissions as noted above, you will get an exception on server start like:
Failed to instantiate [com.jaspersoft.jasperserver.crypto.KeystoreManager]: Please make sure that `create-keystore` was executed; nested exception is java.lang.RuntimeException: KeystoreManager was never initialized or there are errors while instantiating the instance.
To fix this, you need to move the keystore files into a directory that is accessible by the user running the web app process. See Updating keystore files below.
If the keystore files are accessible, but there is a problem with the keystore file location in .jrsksp, you will see exceptions in command line output and JRS log file:
java.lang.Exception: Keystore may have been tempered with.
Keystore files for the command line tools
The keystore files are created and maintained through the command line tools.
The directories where the key related files are stored for the command line tools is defined in the following locations, inspected in order:
“ks” and “ksp” environment variables
buildomatic/keystore.init.properties: ks, ksp properties
Created when first command is run, based on environment variables or default_master.properties
Delete this if you want to update the location in the environment or default_master.properties or revert to default
buildomatic/default_master.properties: ks, ksp properties
Coded default: $USER_HOME as per the operating system
ks, ksp variables need to be encoded for the operating system, for example:
Windows: ks=C:\Users\swood
Linux: ks=/home/swood
Mac: ks=/Users/swood
Updating Keystore files
The .jrsksp file includes a full path to the .jrsks file. The encryption logic in 7.5 requires copied .jrsks files need to be in exactly the same directory path as when the related key files were created, and they are accessible by the user running the JRS command line or web app. ie.
If you want to deploy the keystore files into a given directory ie. /path/to/files
Base64 decode the .jrsksp file
Update the ksPath property in the decoded file to the full path where you want to deploy ie. ksPath = /path/to/files/.jrsks
Base64 encode the updated .jrsksp file
Put the updated .jrsksp and .jrsks in /path/to/files
Update the keystore.init.properties to point to the /path/to/files/.jrsks and .jrsksp
Additional Use Cases
Installation and Upgrade
The first system you install or upgrade to 7.5 will create the new keystore and key related files (.jrsks, .jrsksp, and keystore.init.properties). During installation, buildomatic has a create-keystore target and a create-ks task that creates the keystore files.
If the installation or upgrade process detects an existing keystore, you will be prompted to use or overwrite it with a new one. Proceed only if you are certain the old keystore is no longer in use. Overwriting the keystore of an existing server with data will make the server unavailable (impossible to login and possible shut down with errors) and its data impossible to access (user accounts will need to be recreated manually with new passwords).
Key related file locations are defined - in precedence order:
“ks” and “ksp” environment variables
WEB-INF/classes/keystore.init.properties: ks, ksp properties
This properties file and the key related files are deployed automatically to the JRS web application via the command line tools. If you are not using the command line tools to deploy and update the JasperReports Server web application, you will need to manage the deployment of these files and environment variables yourself.
Note: During an upgrade, the same-db upgrade process to 7.5 does not re-encrypt secure values in the repository. Rather, the pre-existing hard coded keys are used. To fully upgrade to 7.5 with encryption by a new and random key, you will need to export from the pre-7.5 repository and import into a target 7.5 repository.
Installing across Multiple Servers
You might want the same keystore to be used across dev/test/production environments. In a cluster, all machines need the same keystore. After installation or upgrade of one server, the easiest way to share data (reports and export catalogs) between servers is to copy the keystore files to the other servers before installing or upgrading them. Use the following procedure:
After installing or upgrading the first server, locate the keystore files in the home directory of the user who installed the server.
Copy the .jrsks and .jrsksp files and move them to the next server to be installed, in the home directory of the user who will install JasperReports Server.
If the username and home directory path is the same on both servers, JasperReports Server is ready to be installed. If the path to the files is different, you must edit the properties file per: Updating Keystore files
Install or upgrade this server using this keystore.
Importing and Exporting
As in the case above, in order to share server contents by exporting and importing, both servers must have the same keys. If the import does not have the correct key from the export, the import will fail, even if there are no encrypted values (user passwords) in the export catalog.
There are 2 possible scenarios:
For one-time catalog exchanges, you can use the one-time randomly-generated key for the export (command-line only), and then specify that key during the import (UI or command-line).
For repeated sharing of exports, it’s better practice to securely share keys between servers, either by sharing keystore files as described above, or by exporting and importing the import-export key from one server to the other beforehand. Once the keys are shared, export catalogs can be freely imported.
Warning: Sharing keys means that sensitive data from one environment can be decrypted in another environment. For example, passwords in an export catalog from the production server could be decrypted and viewed on the development server.
Keystores and Backups
Without the keystore files, your instance of the server cannot function and all information it contains becomes inaccessible. This is why having backups of the keystore files must be a part of your larger backup and recovery plans for your data.
Use the following guidelines when creating and implementing your keystore backup policies:
Copy both the .jrsks and .jrsksp files together, keeping the .jrsksp file encoded as it is.
The keystore files should be copied only by the system user who installed the server.
Restrict access to the backup keystore filesKeystore relating to Export and Import Utilities as you would the originals on production servers. This includes digital access security for online backups and physical security for offline backups. The files are literally the keys to the application and should be guarded as such.
If you need to restore from the backups, the system user who installed the server should copy the files to their home directory. This is the location where the server expects to find them at runtime.
Related Articles
- Exception "Could not initialize class com.jaspersoft.jasperserver.crypto.KeystoreManager"
- Encryption Configuration Files
- Moving encryption keystore files to a shared Linux folder
- Keystore and Export and Import Utilities
- Keystore Management and Repair
Please add comments below to ask related questions or use the Answers forum.
Recommended Comments
Create an account or sign in to comment
You need to be a member in order to leave a comment
Create an account
Sign up for a new account in our community. It's easy!
Register a new accountSign in
Already have an account? Sign in here.
Sign In Now