This article describes how to encrypt configuration files in Smart ID Identity Manager. All necessary information derives from the encrypted container format and there is no database used when encrypting configuration files.

This feature secures the configuration when you:

• Import a configuration file to or from Identity Manager Operator and Identity Manager Admin.

• Import and export dictionaries in the Translations tab in Identity Manager Admin.

• Manage data in the Process Designer and Process Import sections in Identity Manager Admin.

The import uses automatic sensing and inspect the configuration archive when selected for import. To enable decryption, it must be configured correct. If it fails, you will receive an error message. 

Files with the same content

• For docker: signencrypt.xml

• For WAR file deployment: engineSignEncryptConfig.xml

The XML files contain the same content but in different environments. You can only have one of these files and which one depends on the environment that your system is running on. 

Settings for the system properties

• For docker: SYSTEM_PROPERTIES section (inside docker-compose.yml)

• For WAR file deployment: system.properties file

Step-by-step instruction

Enable encrypted configuration for export

If the configuration encryption is disabled and you want to prevent any unencrypted configuration files to be written to any target location, cancel the download popup and enable the configuration encryption before starting an export. This is important if the target location is an SSD and secure erase is only possible for the full disk drive.

For more information, see Sign and encrypt engine in Identity Manager.

WAR file deployment installation

Enable encrypted configuration:

1. Open system.properties for editing.

2. Set the flag zipPacker.encryptZip to 'true'. 

   Enable encryption

   # Encrypt ZIP archives and configuration? zipPacker.encryptZip=true

Docker installation

Enable encrypted configuration:

The same property setting is applicable on docker. For more information about setting up SYSTEM_PROPERTIES in a docker installation, see Set properties for Identity Manager Admin and Set properties for Identity Manager Operator.

Export encrypted configuration

The encrypted zip archive contains descriptors.info. The file is a part of the encryption mechanism and provides useful hints on the underlying encrypted zip archive, see the example below.

The descriptor name and version for encryption and (optionally) signing in descriptors.info provides information before importing data or uploading configurations into the application. You can verify the given information against the settings in engineSignEncryptConfig.xml.

Example descriptors.info

• Nexus-Encrypted-Archive-Name: Identifies the file name of the encrypted configuration as a binary file, you cannot manually modify the file.

• Nexus-Encryption-Descriptor-Name: Identifies which descriptor that was used for encrypting the configuration archive.

• Nexus-Encryption-Descriptor-Version: Identifies which descriptor version that was used for encrypting the configuration archive.

• Nexus-Signature-Descriptor-Name: Optional when signing is enabled - identifies which descriptor that was used for signing the configuration archive.

• Nexus-Signature-Descriptor-Version: Optional when signing is enabled - identifies which descriptor version that was used for signing the configuration archive.

Import decrypted configuration

The encrypted configuration zip archive has the wrapped symmetric key inside. The asymmetric key for unwrapping and decrypting must be defined in engineSignEncryptConfig.xml. The settings in engineSignEncryptConfig.xml and the key container file (for example, the .p12 file) defined in the descriptor of the XML file must be shared across instances.

Automatic decryption

Automatic sensing of necessary decryption is enabled regardless of the zipPacker.encryptZip property in system.properties when you import a configuration zip archive, for example, a configuration/translation/process/... zip archive. You can always import unencrypted configuration archives. You can import encrypted configuration archives if the settings in engineSignEncryptConfig.xml are available and correct and the property zipEncrypterDecrypter.version in system.properties matches the Nexus-Encryption-Descriptor-Version in descriptors.info of the archive.

You must also verify the settings against descriptors.info of the archive you want to import.

Manual decryption

You cannot perform manual decryption outside of Smart ID Identity Manager.

Increase the descriptor version number

To support successful decryption of any already exported encrypted archives, do not change the settings for the existing version number.

When you import an older versioned encrypted configuration file into the system, make sure to update the XML file accordingly. 

Docker installation

The docker environment uses signencrypt.xml for the settings, you find the file in the config folder.

1. Check the docker-compose.yml of the Smart ID Identity Manager Admin and Identity Manager Operator instance for the reference of signencrypt.xml in the "volumes" section.
   
   

   Example: Location of signencrypt.xml

   ... environment: ... - 'SYSTEM_PROPERTIES={ ... }' ... volumes: - "../config/signencrypt.xml:/usr/local/tomcat/webapps/ROOT/WEB-INF/classes/engineSignEncryptConfig.xml:ro" ...

    

2. To increase the version number of the descriptor, open the section SYSTEM_PROPERTIES in docker-compose.yml and modify the zipEncrypterDecrypter.version:

   Modify zipEncrypterDecrypter.version

WAR file deployment

To increase the version number of the descriptor, open system.properties and modify zipEncrypterDecrypter.version:

Modify zipEncrypterDecrypter.version

Renew encryption on archives

To remove or reduce the old descriptor settings, for example, for cleanup purposes, do the following:

1. In the Configuration File tab, delete the configuration to have a clean database.

2. Stop Tomcat.

3. Configure engineSignEncryptConfig.xml to include all known versions of the descriptors and the related keys.

4. Look up the Nexus-Encryption-Descriptor-Version in descriptors.info file of the archive you want to import next and configure the property zipEncrypterDecrypter.version in system.properties with that version number.

5. Start Tomcat.

6. Import one configuration file with old encryption setting that you want to renew into this test system.

7. Stop Tomcat.

8. Reconfigure the zipEncrypterDecrypter.version to match the new descriptor version setting.

9. Start Tomcat.

10. Export the newly encrypted configuration.

To continue with another archive, repeat the entire procedure.

Modify settings in engineSignEncryptConfig.xml

The encryption of configuration archives in the easiest setup could use equal settings like the regular secret field encryption, for example, see the descriptors "EncryptedFields" and "ConfigZipEncrypter" below.

You must set a separate descriptor with its own version and its own key attribute that also references a new key element. For more information, see the descriptor "ConfigZipEncrypter" and key "configZipEncrypterCert" below.

Example for engineSignEncryptConfig.xml / signencrypt.xml

To ensure compatibility for environments that should import an encrypted configuration archive, all environments must have the same descriptor with the same version and the same key in its setup. Make sure that the descriptor and key naming is unique across the environments exchanging the encrypted configuration.

To enable transfer of encrypted configuration archives between environments, in both directions, the setup must be adjusted. The same descriptor and key can be used in both environments,. For production usage, consider PIN encryption in the file.

The descriptor and key naming for creation of the signature should be unique to share them across the different applications or instances that should load the signed and encrypted configuration archive.