PSD1142 – Enable AES encryption in PIM

Summary

This PhenixID Solution Document (PSD) is written for PhenixID Identity Manager (IM) 5.4.1 or later.

This PSD describes how to change encryption algorithm for PIM from DES to AES-128 bit encryption with your own key.

System Requirements

• PhenixID IM Web 5.4.1 or later
• PhenixID IM Configurator 5.4.1 or later

Considerations

If you have a new installation of PIM WEB or if you have an existing installation where you have only encrypted the password you can proceed with this PSD.

However, if you have existing data (values in Active Directory for example) encrypted with DES and change to AES, the DES encrypted data can not be decrypted with the AES key. This needs to be solved before continuing, proceed with caution if you decide to continue with this document.

Changing from DES to AES

1. Create an encryption key file
2. Encrypt the password using your key and AES-128 algorithm
3. Enable AES-128 bit by adding a policy in DSEditor.policy
4. Restart IM service. IM will now encrypt and decrypt data using your custom key.

• This document will also explain:
  • how to encrypt the PIM service account password whenever the password is changed
  • best practices on how to keep the AES encryption key secure

1. Create an encryption key file

The encryption key it is just a string in a file made up by you. The key file is used to encrypt and decrypt data.
In this PSD I will create and use a txt-file called MySecretAES128Key.txt with the key Very#Secret(/Key1999

1. Create a txt-file MySecretAES128Key.txt
2. Store the file in, for example, \..\PhenixID\IM\customer\config
3. Add in the file (and the file can only contain this) Very#Secret(/Key1999
4. Save the file

Note. This key file does only need to be present when you start PIM. As soon as service is started you can move the file to a secure location or just delete it and recreate the file with same string when you need it.

2. Encrypt the password using your key

Any value used in by PIM can be used to encrypt with your encryption key. In this section I use the password that will be stored in the LDAP_ADMIN_PW=.

In short you use IM Configurator to encrypt data.

1. Open IM Configurator. (must be 5.4.1 or later.)
2. In the main UI, click Encryption Tool
3. Select, in this case, AES 128
4. In Key File add path and file name to the encryption key you created in previous section.
5. In Value to Encrypt add the password for the service account
6. Click Encrypt button
7. Copy the encrypted value, it should look something like:
   {AES}BXphmAPAQMVf2VevP4qFV9w0nyg4zThkndNH6QqAul1EclhrFcMS9A==
8. Paste into LDAP_ADMIN_PW= in DSEditor.properties. Should look something like:
9. LDAP_ADMIN_PW={AES}BXphmAPAQMVf2VevP4qFV9w0nyg4zThkndNH6QqAul1EclhrFcMS9A==
10. Move to next section before you restart the PIM service to make sure IM web has the policy enabled to your encryption key.

3. Enable AES policy in DSEditor.properties

In short you add a policy with the link to the encryption key file. The policy and value is the trigger for PIM to use AES instead of DES. By default this policy is missing which means IPM uses DES as default encryption method.

1. Open DSEditor.properties (\..\PhenixID\IM\customer\config)
2. Add a new policy called AES_ENCRYPTION_FILE=
   1. For example then line right after the LDAP_ADMIN_PW policy
3. Add the file path and file name to the policy
   AES_ENCRYPTION_FILE=\..\PhenixID\IM/customer/config/MySecretKey.txt
4. Make sure the LDAP_ADMIN_PW= has the AES encrypted password for the service account (how to encrypt a password is explained later in this PSD)
   1. Example:
      LDAP_ADMIN_PW={AES}lkjXwAKyZS7H/dwWhpbpjcTVS5hwmug2gBigAsKYRVV2ksu1o7rJEdw=
5. Save and close the DSEditor.properties file
6. Restart the IM service

Best practices on how to keep the AES encryption key secure

Since PIM needs the key when the service start there are some best practices:

• Keep the server secure. If you keep the key on the server make sure no unauthorised person has permission.
• You can remove the key after PIM service starts. But if you need to restart or for example Windows update restart the service you need to add the key again.