Crypto Support In AEM (Syncing Keys Among AEM Instances)

Crypto Support is based on keys (hmac and master files) which are unique for each AEM instance. Encrypted text generated for the same plain-text string on one AEM instance will be different from another instance. This can raise alarms in cases where we have the same OSGi configuration values shared among Author and Publish instances under the same topology.

For e.g. /apps/my-project/config.prod/com.day.cq.mailer.DefaultMailService.xml.

Here SMTP password for Default Mail Service will be same across all Prod AEM instances. So, in order to make sure that the same encrypted value works on all Prod instances, we will have to sync hmac and master files among Prod Author and Publish instances.

Locating keys (hmac and master files):
Follow below steps to locate your keys:
1. Navigate to /system/console/bundles and look for the “Adobe Granite Crypto Support” bundle. [Symbolic Name: com.adobe.granite.crypto]

2. Note the bundle ID.

3. Navigate to file system: /crx-quickstart/launchpad/felix/bundle<id>/data [Note: here <id> is the bundle ID from step 2]

4. Open the “storage” file. This file contains just one single line:

a. JCR i.e. files are stored in JCR under /etc/key.

b. Bundle i.e. files are stored on a file system.

Note: If you have always upgraded your AEM instance using in-place upgrade, then these keys are going to be under /etc/key and there’s no harm in keeping these keys under /etc/key even though latest versions of AEM have moved the keys from JCR to file system (crx-quickstart). We had upgraded AEM for one of our clients from 5.6.1 to 6.1 and a few years later again from 6.1 to 6.3. The client is using Crypto Support and their keys are stored in /etc/key. If at all needed, you can move the keys from JCR to the file system and vice versa.

Syncing keys:
If keys are stored under /etc/key:
1. Create a package of /etc/key from the source instance and install this package on the target instance.

2. OR go to CRXDE, select node /etc/key; click on the Replication tab and press the Replication button.

3. Restart target AEM instance.

If keys are stored on the file system:
1. On the source instance, navigate to /system/console/bundles and look for the “Adobe Granite Crypto Bundle Key Provider” bundle. [Symbolic Name: com.adobe.granite.crypto.file]

2. Note the bundle ID.

3. Navigate to file system: /crx-quickstart/launchpad/felix/bundle<id>/data [Note: here <id> is the bundle ID from step 2]

4. Copy hmac and master files from the above directory.

5. Follow steps 1-3 on the target instance.

6. Replace hmac and master files on target instance from the source instance hmac and master (copied in step 4).

7. Restart target AEM instance.

Note: You can avoid restarting instances, rather you can restart the Crypto bundle “com.adobe.granite.crypto”. The catch here is – if you restart the Crypto bundle through the OSGi console, the regular AEM login fails. So, it’s better to restart this bundle through the CURL command.

Stopping the bundle:
curl -u admin:<admin_password>

http://<host>:<port>/system/console/bundles/com/adobe.granite.crypto -F action=stop

Starting the bundle:
curl -u admin:<admin_password>

http://<host>:<port>/system/console/bundles/com.adobe.granite.crypto -F action=start

Issues post hmac/master files sync:
If your target AEM repository had SSO/SAML integration, it will stop working after hmac/master files are synced from the source instance.

SSO/SAML integration works based on the trust store and key store. Passwords for trust store and key store are stored in an encrypted format in the repository under “keystorePassword” at below locations:

1. /etc/truststore
2. /home/users/system/authentication-service/keystore

You just need to the re-encrypt trust store and key store passwords and update “keystorePassword” properties at both the locations. This will resolve the issue.