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.
The export of an encrypted configuration is disabled by default.
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.
Any references to engineSignEncryptConfig.xml in the documentation below refers to signencrypt.xml in a docker environment.
Settings for the system properties
- For docker: SYSTEM_PROPERTIES section (inside docker-compose.yml)
- For WAR file deployment: system.properties file
Whenever referring to system.properties for a non-docker environment, the same applies for the SYSTEM_PROPERTIES section inside docker-compose.yml for a docker environment.
Enable encrypted configuration
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.
Open system.properties for editing.
Set the flag
Manage 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.
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.
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 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.
To support automatic sensing for decryption, the zip archive should not have been modified or manipulated after export, especially when signature creation is applied.
You cannot perform manual decryption outside of Smart ID Identity Manager.
To support successful decryption of any already exported encrypted archives, do not change the settings for the existing version number.
If you modify the attributes of the descriptor or replace/modify the key file, you must increase the version number of the descriptor.
When you import an older versioned encrypted configuration file into the system, make sure to update the XML file accordingly.
The docker environment uses signencrypt.xml for the settings, you find the file in the config folder.
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.
To increase the version number of the descriptor, open the section SYSTEM_PROPERTIES in docker-compose.yml and modify the zipEncrypterDecrypter.version:
To increase the version number of the descriptor, open system.properties and modify zipEncrypterDecrypter.version:
Set up an IDM Admin test system before you start.
To remove or reduce the old descriptor settings, for example, for cleanup purposes, do the following:
- In the Configuration File tab, delete the configuration to have a clean database.
- Stop Tomcat.
- Configure engineSignEncryptConfig.xml to include all known versions of the descriptors and the related keys.
- 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.
- Start Tomcat.
Import one configuration file with old encryption setting that you want to renew into this test system.
Reconfigure the zipEncrypterDecrypter.version to match the new descriptor version setting.
- Start Tomcat.
Export the newly encrypted configuration.
To continue with another archive, repeat the entire procedure.
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.
In a complex environment, you should have a separate setup for the configuration archive encryption, that is, with a different key/P12 than the regular secret field encryption. The setup can be shared, for example, with a development or test environment to transfer the production configuration to any other environment in an encrypted manner.
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.
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.
Keep old encryption descriptors
Keep old encryption descriptors, including all versions, and the linked key sections in engineSignEncryptConfig.xml for all configurations that ever were exported with encryption to make a later import of configurations easier. This could help for testing, cloning configuration parts, investigation, issue reproduction and more.