This article describes how to change the secret fields encryption keypair in Smart ID Identity Manager. The keys are changed using an application provided by Nexus. This application is referenced as Secret Fields Key Updater in this article.
Some of the use cases where you might need to change the fields encryption keypair are:
- You started using a productive 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.
Prerequisites
This is a summary of what must be in place before the migration starts.
- A Windows host.
- The same Java version as for the corresponding Identity Manager release is installed and its java.exe in your PATH. See IDM 23.10.3 - Requirements and interoperability.
- Java has the Unlimited Strength Jurisdiction Policy Files installed.
- The new keypair has been generated.
- For every tenant on the system have access to:
- tenant ID
- administrative username + password
Step-by-step instructions
Preparation
Set up database connection
- Extract the zip archive containing the Secret Fields Key Updater.
- Go to the extracted Secret Fields Key Updater directory.
- Edit the file database.properties as appropriate. For more information on this file, see Install Identity Manager.
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>
Data Encryption key set up
- Open the file config/encryption-config.xml.
- Update the
EncryptedFields
and NewEncryptedFields
field descriptors and their referenced keys as described below. For more information on this file, see 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.
<?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:
- Stop the Identity Manager applications (shut down Tomcat or the respective docker containers by running docker compose down from within docker/compose/identitymanager/<webappname>/).
- Create a backup of the respective databases.
Migration per tenant
Configure migration for a tenant
Edit migrate_general.properties and set the following values:
Attribute | Value | 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
- Double-check that all preparation steps were executed, especially a database update of the state before migrating the first tenant.
- Start the Secret Fields Key Updater by executing the batch file start_migration.bat on Windows.
Log file
During the migration, log files are created in the file logs/idm_migration.log.
If necessary, edit log4j.xml to customize the path of the log messages.
Check for success
- When Secret Fields Key Updater is finished, look in the logfile.
- If you see the message "
SUCCESS: Encrypted Fields Keypair changed!
", the operation was successful. In this case, proceed with the next tenant, if any left, otherwise with the next section. - If you see the message "
FAILED: Changing the Encrypted Fields Keypair FAILED with status
...", the application has failed. Restore your database from the dump you created earlier and contact Nexus.
After migration of all tenants
Make sure update is sucessful
- 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
- For docker:
Open docker/compose/identitymanager/config/signencrypt.xml for editing.
or:
For WAR file deployment:
Open WEB-INF/classes/engineSignEncrypt.xml in Identity Manager Operator, Identity Manager Admin and Identity Manager Tenant for editing. - 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 descriptor's name must still be EncryptedFields
and not NewEncryptedFields
for Identity Manager. - For docker:
Run docker compose up from within docker/compose/identitymanager/<webappname>/ for all Identity Manager applications (Admin, Operator and Tenant) to recreate the docker containers.
or:
For WAR file deployment:
Start Identity Manager.