Versions Compared

Old Version 12

changes.mady.by.user Josefin Klang (Deactivated)

Saved on

compared with

New Version Current

changes.mady.by.user Ylva Andersson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated regarding Linux.
Info

This article is valid for Smart ID 24.R1 and laterincludes updates for Identity Manager 5.0.1.

This article describes how to change the secret fields encryption keypair in Smart ID Identity Manager. In addition to changing the keypair and adjusting the secret engine configuration, you must use an application provided by Nexus to update the already existing secrets in the database with the new keys, otherwise Identity Manager cannot decrypt them. The application is referenced as Secret Fields Key Updater in this article.

Example use cases

Some of the use cases where you might need to change the fields encryption keypair are:

  • You started using a production Identity Manager installation while still using the supplied, insecure example keys. Those must be replaced by your own keys and any existing secret fields must be re-keyed with those keys.

  • You started using an Identity Manager installation based on soft-tokens for encrypting secret fields, and you want to improve security by switching to keys generated by a Hardware Security Module (HSM). Any existing keys must be re-keyed with the new keys.

  • The keys for secret field encryption have been compromised and existing secrets need to be re-keyed with new keys.

  • You want to change the keys for encryption of secret fields for any other reason and have existing secret fields in the database.

...

  • You must have access to a Windows host.The same host with a Java version as that is supported for the corresponding Identity Manager release is installed and its java.exe . Its java executable must be in your PATH. For more information, see Identity Manager requirements and interoperability.

  • Java has the Unlimited Strength Jurisdiction Policy Files installedenabled (default since Java 8u151).

  • The new keypair has been generated.

  • For every tenant on the system have access to:

    • tenant ID

    • administrative username and password

...

  1. Extract the zip archive containing the Secret Fields Key Updater.

  2. Go to the extracted Secret Fields Key Updater directory.

  3. Edit the file database.properties as appropriate. For more information on this file, see Install Identity Manager.

Identity Manager database

Code Block
dataSourceType=H2
dataSource.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;instance=<INSTANCE_NAME>;databaseName=<DB_NAME>;AUTO_SERVER=TRUE
dataSource.user=<USER_NAME>
dataSource.password=<USER_PASSWORD>

...

  1. Open the file config/encryption-config.xml.

  2. Update the EncryptedFields and NewEncryptedFields field descriptors and their referenced keys as described below. For more information on this file, see 24.R1: Sign and encrypt engine in Identity Manager.

    • EncryptedFields is the old, to be replaced, descriptor. Adapt its values to match the ones that are currently set up in Identity Manager.
      In this example, EncryptedFields references oldEncCert as its key. Change the referenced key to match the one that is currently referenced in Identity Manager.

    • NewEncryptedFields is the new descriptor, holding the information of the replacement key. Change its values accordingly.
      In this example, NewEncryptedFields references newEncCert as its key. Change the referenced key to match the key that will replace the old one in Identity Manager.

Expand
titleExample

Example: encryption-config.xml

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
  <descriptors>
    <descriptor name="EncryptedFields" version="1">
      <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="oldEncCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
    </descriptor>
    <descriptor name="NewEncryptedFields" version="1">
      <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="newEncCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
    </descriptor>
  </descriptors>
  <keys>
    <key name="oldEncCert">
      <type name="pkcs12" locationValue="classpath:oldEncKeypair.p12" pin="1234567"/>
    </key>
    <key name="newEncCert">
      <type name="pkcs12" locationValue="classpath:newEncKeypair.p12" pin="1234"/>
    </key>
  </keys>
</engineSignEncrypt>

Shutdown and backup

Before you start the migration:

  1. Stop the Identity Manager applications and shut down Tomcat or the respective docker containers by running docker compose downfrom within docker/compose/identitymanager/<webappname>/.

  2. Create a backup of the respective databases.

Migration per tenant

Warningnote

The secret field store in the database is tenant-aware, even though the descriptors and keys are not. The migration must be executed separatelyfor every single tenant before changing keys and descriptors in Identity Manager.

...

Attribute

Description

username

Name of the administrator of the respective tenant. This user will be used to perform the update.

password

The administrator's password.

tenantId

The Tenant ID.

Execute migration for a tenant

  1. Double-check that all preparation steps were executed, especially a database update of the state before migrating the first tenant.

  2. Start the Secret Fields Key Updater by executing :

    1. on Windows, execute the batch file start_migration.bat

    on Windows.

    2. on Linux, make the .sh file executable with chmod +x start_migration.sh and then execute it with ./start_migration.sh

If the application is interrupted or fails, you can restart it at a later time. It will restart from the beginning and not from where it stopped the previous time.

...

When Secret Fields Key Updater is finished, look in the logfile.

  • If you see the The message "SUCCESS: Encrypted Fields Keypair changed!", indicates that the operation was successful. In this case, proceed with the next tenant, if any left, otherwise with the next section.

  • If you see the The message " FAILED: Changing the Encrypted Fields Keypair FAILED with status ... ", indicates that the application has failed. Restore your database from the dump you backup created earlier and contact Nexus.

After migration of all tenants

Make sure update is

...

successful

Make sure the Secret Fields Key Updater successfully ran for every single tenant on the system.

Set up Identity Manager to use the new keypair

  1. Open the file for editing.
    For docker: Open docker/compose/identitymanager/config/signencrypt.xml for editing.
    For WAR file deployment: Open WEB-INF/classes/engineSignEncryptConfig.xml in Identity Manager Operator, Identity Manager Admin, and Identity Manager Tenant for editing.

  2. Change the attributes of the EncryptedFields descriptor and its referenced key to the values needed for the new keypair, as you set them for the NewEncryptedFields descriptor in the migration application. Note that the The descriptor's name must still be EncryptedFields and not NewEncryptedFields for Identity Manager.

  3. For docker: Rundocker compose up from within  docker/compose/identitymanager/<webappname>/ for all Identity Manager applications (Admin, Operator, and Tenant) to recreate the docker containers.
    For WAR file deployment: Start Identity Manager.