Managing Keys for Import and Export
As of JasperReports Server 7.5, the management of the encryption keys used during import and export has been automated. These encryption keys are used by the server to encrypt user passwords so they are not revealed in export catalogs.
In previous versions of the server, the import-export key had to be configured manually outside the server. Beginning with version 7.5, the server creates and manages its import-export key internally, and also includes UI and REST options for specifying keys during import and export operations. However, there are still cases when you may need to manage keys on the server and specify keys during import-export operations.
The following table summarizes the use of keys when importing catalogs into the current version of the server:
| Origin of Export Catalog | Guidelines for Importing into 9.0.0 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Before version 7.5 With default key |
The current version of the server handles previous export catalogs created with legacy keys, and even older catalogs that did not use encryption. When importing through the UI, specify the Legacy key, and when importing through the command line, specify the deprecatedImportExportEncSecret. | |||||||||
| Before version 7.5 With custom import-export keys |
The custom keys are not known to your server, so to import these catalogs, you will need to share the custom key with the importing server. There are two ways to specify custom keys:
|
|||||||||
| Version 7.5 and later From the same server |
When you import a catalog back into the same server, the server uses the same key for export, and import and thus can read its own export catalog. When importing through the UI, specify the Server key, and when importing through the command line, the key is detected automatically. This is also true after upgrading the server, as long as the catalog was exported from version 7.5 or later and the server's keystore was preserved during the upgrade. For more information about the keystore and catalogs during upgrade, see the JasperReports Server Upgrade Guide. | |||||||||
| Version 7.5 and later From a different server |
Because each server has unique randomly generate keys, the keys of the export server are not known to your server. However, unlike the custom key scenario above, you do not have direct access to the server's keys. Before you can move export catalogs between servers, such as test and production servers, you need to generate and share a key between the servers:
If you also import the key back into the originating server, both servers share the same key. Then if you specify this custom key during import and export, catalogs can be exported from either server and imported into the other one. |
This guide documents the following operations to set up and manipulate keys:
| • | Specifying custom keys during import and export operations. |
| • | Importing keys used by other servers. |
| • | Exporting keys for use in other servers. |
| • | Sharing custom keys between multiple servers. |
For the default import and export operations, including specifying import-export keys through the UI, see the JasperReports Server Administrator Guide:
| • | Importing catalogs from older servers with legacy or custom keys. |
| • | Exporting catalogs with a specific key. |
The following sections describe the three ways to import a catalog that is encrypted with a custom key:
| • | Use the import UI, and enter the key’s hexadecimal bytes in the Key Value field. This method is simple, but the key will not be stored in the server for multiple imports. |
| • | Store the custom key as a secure file resource in the repository, so it can be reused. Then use the import UI with the Stored Key field. |
| • | Use the import command line to import the key into the keystore so that it is available for any import operation in the future. |
Entering a Key Value in the Import UI
The simplest way to import a catalog with a custom key is to use the Settings UI for import and enter the key value. The key value is its representation in hexadecimal, for example:
0x1c 0x40 0xb9 0xf6 0xe2 0xd3 0xf9 0xd0 0x5a 0xab 0x84 0xe6 0xd4 0xe8 0x5f 0xed
| 1. | Log in as |
| 2. | Select Manage > Server Settings, then click Import in the left-hand panel. |
| 3. | In the right-hand panel, browse the file system to enter the catalog file you want to import. |
|
|
| 4. | Choose the Key Value radio button and paste the entire key value in the designated field. The characters of the key value are hidden to keep them secret. |
| 5. | Select your import options and click Import. |
If the key does not decrypt the catalog file, you get an error message, otherwise the import proceeds.
Using a Stored Key in the Repository
If you have multiple files to import, you can store the custom key in a secure file resource in the repository. The contents of secure file resources are considered sensitive and protected internally in the same way as user passwords, that is, they are encrypted with a key in the internal database.
| 1. | Start by saving your custom key value as a hexadecimal number in a plain text file, for example: |
0x1c 0x40 0xb9 0xf6 0xe2 0xd3 0xf9 0xd0 0x5a 0xab 0x84 0xe6 0xd4 0xe8 0x5f 0xed
| 2. | Log in as |
| 3. | Select View > Repository, then browse the repository tree to find an appropriate folder. |
| 4. | Right-click the folder and select Add Resource > File > Secure File. |
| 5. | In the Add File dialog, browse the file system to enter your text file with the key. |
|
| 6. | Fill in the other fields and click Submit. The File appears in the repository. |
| 7. | Select Manage > Server Settings, then click Import in the left-hand panel. |
| 8. | In the right-hand panel, browse the file system to enter the catalog file you want to import. |
|
|
| 9. | Choose the Stored Key radio button and browse the repository to find your secure file. |
| 10. | Select your import options and click Import. |
If the key does not decrypt the catalog file, you will get an error message, otherwise the import proceeds.
Specifying an Import Key on the Command Line
Similar to the import UI, the js-import command-line utility has new options to specify the key needed to decrypt passwords in the catalog, for example, catalogs from older servers with different keys. There are two ways to specify the import key:
| • | Give the hexadecimal bytes of the key. |
| • | Give the alias of a key in the server's keystore (.jrsks). |
|
js-import Options to Specify an Import Key |
|
|
Option |
Explanation |
|
|
Specifies the file path to a zipped input catalog from an older JasperReports Server instance that was configured to use custom keys. |
|
|
The standard import options specifying the import behavior, for example |
|
|
When used with input-zip, this option specifies a key in the server's keystore (.jrsks) to use when decrypting passwords in the import catalog. |
|
|
Lets you specify the hexadecimal representation of a key to be used as a one-time import key to decrypt any passwords in the input-zip. |
|
|
When used with |
The following example shows how to import a catalog with a custom key.
js-import.sh --secret-key "0x1c 0x40 0xb9 0xf6 0xe2 0xd3 0xf9 0xd0 0x5a 0xab 0x84 0xe6 0xd4 0xe8 0x5f 0xed" --input-zip myExport.zip
The following example shows how to import a catalog using a key already saved in the keystore.
js-import.sh --keyalias productionServerKey --input-zip myExport.zip
Importing a Key from the Command Line
If you have many catalogs to import from a server with a custom key, the js-import script has different options to import the key and add it to the local keystore (.jrsks by default). You can then use the example in the previous section to specify the new key by its alias when importing. There are three ways to define the key to import:
| • | Provide the hexadecimal bytes of the key. |
| • | Provide a keystore and the alias (and password) of a key that it contains. |
| • | Request a random key to be generated and associated with an alias (and password) you provide. |
|
js-import Options to Import a Key |
|
|
Option |
Explanation |
|
|
This option specifies a key to be added to the server's keystore. This option should be followed by the hexadecimal representation of the key, or by the |
|
|
This option specifies the path and filename of a keystore file from which to read and copy the key designated by the |
|
|
This option specifies the password for the keystore file from which to read and copy the key designated by the |
|
|
This option triggers the import utility to generate a random key to be added to the server's keystore with the alias and password you specify (in the other options below) so that you can later access and use it. This option is a shortcut for creating a random key in an external keystore and then importing it with the |
|
|
When used with a hexidecimal input-key, it specifies the alias of the new key to be imported. When used with the |
|
|
When used with a hexidecimal input-key, it specifies the password of the new key to be imported. When used with the |
|
|
When used with a hexidecimal input-key, this option defines the algorithm, either AES or DES, for the key being imported in the keystore. When used with the |
|
|
When used with a hexidecimal input-key, this option defines the key length in bits, usually 128 or 256, for the key being imported in the keystore. When used with the --genkey option, this specifies the length of the new key to create. |
|
|
Specify this flag to make the imported key displayed in the list of Custom Keys as shown in Specifying a Custom Key in the Import UI. When omitted, the imported key is not available for UI import operations, only through command-line import operations (using |
|
|
When --visible is specified, this option lets you specify the name of the key to display in the Custom Key selection interface. If --visible is specified without this option, the key alias is displayed in the UI. This option has no effect when --visible is not specified. |
The following example shows how to add a key to the keystore, so it can be used for other import operations:
js-import.sh --input-key "0x59 0xe3 0xd9 0xce 0x7f 0x34 0xab 0x27 0xb8 0xdf 0xc3 0x7e 0x01 0xab
0x4d 0x6c" --keyalias productionKey --keyalg AES --keypass productionKeyPass
--visible --keylabel ProductionServerKey
The following example shows how to copy a key from an external keystore file into the default keystore.
js-import.sh --input-key --keystore ./mystore --storepass password --keyalias productionKey2
--keypass productionKeyPass2 --visible --keylabel ProductionServerKey2
Specifying a Custom Key in the Import UI
After adding custom keys to the keystore from the command line using the --visible option, you can also select the keys in the UI during import operations. The keys are identified by their alias or label if given.
| 1. | Log in as |
| 2. | Select Manage > Server Settings, then click Import in the left-hand panel. |
| 3. | In the right-hand panel, browse the file system to enter the catalog file you want to import. |
|
|
- When the server's keystore contains custom keys, the list of keys appears as the third bullet. Note that key files in the repository do not appear in this list, only custom keys in the keystore. Each key in the list is identified by its label if it was defined on import, otherwise by its alias. Choose this bullet and select your key from the dropdown list.
- Select your import options and click Import.
If the key does not decrypt the catalog file, you get an error message, otherwise the import proceeds.
Specifying an Export Key on the Command Line
As with the export UI, you can specify custom keys when exporting from the command line. For example, you can create an export catalog that can be imported into another server instance that has different keys. There are three ways to specify the export key:
| • | Provide the hexadecimal bytes of the key. |
| • | Give the alias of a key in the server's keystore (.jrsks). |
| • | Request a random key be generated and displayed on the console. |
|
js-export Options to Specify the Export Encryption Key |
|
|
Option |
Explanation |
|
|
Specifies the name of a zipped output catalog that will use the custom keys specified by the other options in this table. The index.xml file in the catalog contains new attributes to handle keys. |
|
|
The standard export options specifying the resources to export and export behavior, for example |
|
|
This option lets you specify the hexadecimal representation of a key to be used as a one-time export key to encrypt any passwords in the output-zip. |
|
|
This option may be specified only with the |
|
|
This option may be specified only with the |
|
|
This option specifies a key in the keystore to use when encrypting passwords in the export catalog, instead of the default import-export key. |
|
|
This option may be specified only with the |
|
|
This option generates a random key using the same algorithm and key size as the server's default import-export key (AES-128), and uses it to encrypt passwords in the export catalog. If the export is successful, the js-export script prints the key's hexadecimal representation and a unique alias for it on the console where it is running. You need to specify the same key when importing the catalog, for example with the |
The following example shows how to export a catalog with passwords encrypted with a custom key:
js-export.sh --uris /public/samples/AccountList --output-zip myExport.zip --secret-key="0x6f 0x00 0xf1 0xbd 0x46 0x1f 0x62 0xa1 0x03 0x56 0x13 0xda 0x07 0x00 0x7c 0x10"
The following example shows how to export a catalog with passwords encrypted by one of the keys in the keystore:
./js-export.sh --uris /public/samples/AccountList --output-zip myExport.zip --keyalias productionServerKey --keypass "mykeypw2"
Exporting a Key from the Command Line
The js-export utility can also be used to export one of the keys from the server's keystore (.jrsks). In addition to exporting repository resources in an export catalog, the following options generate a Java keystore file containing the specified key. The keystore is a secure file protected by the given password that can be used with the keytool utility or with the keystore options of the js-import tool. For more information, see Importing a Key from the Command Line.
|
js-export Options to Export a Key |
|
|
Option |
Explanation |
|
|
When used with the |
|
|
This option may be specified only with the |
|
|
This option generates a random key using the same algoritm and key size as the server's default import-export key (AES-128), and exports it in the specified keystore. If the export includes resources in an export catalog, any passwords it contains will be encrypted with this key. |
|
|
This option specifies the filename of a keystore file to create, in order to export the key designated by the |
|
|
This option specifies the password for the keystore file to be created to hold the exported key. |
|
|
Specifies a new password for the key in the newly created keystore. |
You may specify both an output zip catalog and list of resources to export, as well as a key alias and keystore filename. In the following example of this, the export creates two output files, the zip catalog and the keystore, and any passwords in the catalog are encrypted with the same key that was exported.
js-export.sh --everything --output-zip myExport.zip --destkeystore mystore --deststorepass storepw --genkey
The server that generates this key stores a copy of it in its keystore, and if you import the key to another server, they share the key. If you examine the key with the keytool utility, it has a unique alias name:
keytool -list -v -keystore ./mystore -storetype jceks Enter keystore password: ******* Keystore type: JCEKS Keystore provider: SunJCE Your keystore contains 1 entry Alias name: ced6b744-033d-4516-b293-c4776035a6f1 Creation date: Dec 12, 2019 Entry type: SecretKeyEntry ******************************************* *******************************************
Now you can specify this unique alias name whenever importing or exporting from your two servers, the encryption is mutually compatible, and you will not need to export or import keys anymore.
Recommended Comments
There are no comments to display.