Encryption in JasperReports Server 7.5+

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.


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


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:

  1. 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.

  1. 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:

  1. “ks” and “ksp” environment variables

  2. 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:

  1. “ks” and “ksp” environment variables

  2. buildomatic/keystore.init.properties: ks, ksp properties

    1. Created when first command is run, based on environment variables or default_master.properties

    2. Delete this if you want to update the location in the environment or default_master.properties or revert to default

  3. buildomatic/default_master.properties: ks, ksp properties

  4. 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

  1. Base64 decode the .jrsksp file

  2. Update the ksPath property in the decoded file to the full path where you want to deploy ie. ksPath = /path/to/files/.jrsks

  3. Base64 encode the updated .jrsksp file

  4. Put the updated .jrsksp and .jrsks in /path/to/files

  5. 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:

  1. “ks” and “ksp” environment variables

  2. 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:

  1. After installing or upgrading the first server, locate the keystore files in the home directory of the user who installed the server.

  2. 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.

  3. 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

  4. 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.

Please add comments below to ask related questions or use the Answers forum.


Because it sure seems like it.

Ideally, I don't want to play with SSL on a purely internal site, but... if this is how it has to be, then a "handy dandy" guide built for mere mortals showing simply... this is how you do it (using actual non-self-signed certificates).

And by that I mean from a fresh install... of everything (Java, Tomcat, JasperServer and anything I might have missed).

Hey andrew_50, perhaps you should create a new community post with your question since this wiki article is unrelated to HTTPS vs HTTP requests.   This wiki is about encyption of particular repository data (sensitive content such as database passwords in the configuration and user passwords in the database and export catalogs)) and implications around moving/managing repo data between instances.   The encryption process related to this wiki doesn't relate to SSL in any way.

I've installed the libtcnative-1 package, and that's reduced the error quantity markedly.

Letting people know that this is now (pretty much a requirement) for JasperServer installs would be a good thing.

That and I still have little idea (possibly Postgresql, but why I don't know) I'm getting swathes of other errors about not being able to create beans.

Oh, and it still complains about a KeyStore not existing.

Is this "Updating Keystore files" really necessary?

There is no ksPath key in  .jrsksp. Only this:

ksp = ${sys:user.home}
ks = ${ksp}

I updated from 7.2 to 7.8 using the upgrade manual. The upgrade worked, but the server couldn't start because user root created the keystore and user tomcat couldn't read it. So I just moved the keystore to another folder and changed WEB-INF/classes/keystore.init.properties.

No need to change the .jrsksp itself.

I gave read permission to user tomcat on the files

Hi gustavofarias

I had the same problem and thanks to your tipp I solved it. Thank you.