Skip to main content
Skip table of contents

Encrypt configuration files in Identity Manager

This article is added with Smart ID 23.10.2.

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.

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

    CODE 
    # 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
TEXT 
Nexus-Encrypted-Archive-Name: encrypted_config_zip.bin
Nexus-Encryption-Descriptor-Name: ConfigZipEncrypter
Nexus-Encryption-Descriptor-Version: 1
Nexus-Signature-Descriptor-Name: SignVerifyDescriptor
Nexus-Signature-Descriptor-Version: 2

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

To support automatic sensing for decryption, the zip archive should not have been modified or manipulated after export, especially when signature creation is applied.

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.

Important!

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. 

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

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

    CODE 
    ## default version number is 1, but if it has to be increased, this is the only way
## to provide the version number to be used by the encryption of the configuration
zipEncrypterDecrypter.version=2

WAR file deployment

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

Modify zipEncrypterDecrypter.version
CODE 
## default version number is 1, but if it has to be increased, this is the only way
## to provide the version number to be used by the encryption of the configuration
zipEncrypterDecrypter.version=2

Renew encryption on archives

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:

  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.

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.

Example for engineSignEncryptConfig.xml / signencrypt.xml
XML 
<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
	<descriptors>
		<descriptor name="EncryptedFields" version="1">
			<type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="encCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
		</descriptor>
		<descriptor name="ConfigZipEncrypter" version="1">
			<type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="configZipEncrypterCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
		</descriptor>
		<descriptor name="ConfigZipSigner" version="1">
			<type algorithm="SHA-256" size="" result="" key="configZipSignerCert"/>
		</descriptor> ... </descriptors>
	<keys>
		<key name="encCert">
			<type name="pkcs12" locationValue="classpath:hybridEncKeypair.p12" pin="1234567"/>
		</key>
		<key name="configZipEncrypterCert">
			<type name="pkcs12" locationValue="classpath:hybridEncKeypair.p12" pin="1234567"/>
		</key>
		<key name="configZipSignerCert">
			<type name="pkcs12" locationValue="classpath:sign.p12" pin="1234"/>
		</key> 
...

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close