How to Sync HMAC in AEM ?

Crypto Support in AEM (Syncing HMAC among AEM instances)

AEM OOTB provides a feature where we can encrypt the secured and confidential data through OOTB AEM Crypto Support and store it in a code repository in the form of OSGi configuration.

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/project/

Here DB password for Default DB 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.

Vital Points to know before HMAC SYNC 

Sync of HMAC/keys will break the AEM SSL and rest the keystore & trust store of target AEM server. hence make sure - 

1- If your instance is SSL enabled. Make sure you have the required certificates to re configure the SSL.
2- if your instance has SSO/SAML enabled , make sure you have required certs for all these, As you my end up in reconfiguring it. 
3- Check trust store of your AEM to make sure you have backup of all the certs , as reconfiguration may needed post HMAC SYNC. 

How to Replicate HMAC Keys with Instance SSL

Since AEM 6.3, the key material is no longer stored in the repository, but on the actual filesystem. With this in mind, the best way to replicate the keys is to copy them from the filesystem of the source instance to that of the target instance(s) you want to replicate the keys to. 

In 1 line, you have to take the HMAC & MASTER files from author /crx-quickstart/launchpad/felix/bundle25 put on Publish servers and restart AEM, and re-configure the SSL, Detailed steps are mentioned below - 
  1. Locate the bundle containing the HMAC key
    • Access source instance file system. 
    • Navigate to bundles folder ( cd /crx-quickstart/launchpad/felix/ )
    • find the HMAC KEY bundle ( find . -name hmac )
    • Navigate to this bundle folder( cd /crx-quickstart/launchpad/felix/bundle<id>/data/
  2. To allow the hmac and master files to be downloaded with ssh, copy the files to a location where your user has read access. For example your home directory on the instance:
    • cp hmac  /home/myhome/hmac-author
    • cp master /home/myhome/master-author
  3. Download these files on your local machine.
  4. Upload the files to your home dir on the publisher/target instance. 
  5. ssh to publisher/target instance
  6. Locate the bundle containing the HMAC key on publish/target instance.
    • Follow Step 1 
  7. Move the old hmac and master files to a save directory (home dir works well again). Do not simply rename the original files in the directory. Having more than one set of key files in the directory will interfere with normal AEM startup.
  8. Copy the new files into the bundle data directory.
    • cp hmac-author  <<fullpath>>/crx-quickstart/launchpad/felix/bundle<id>/data/hmac 
    • cp master-author <<fullpath>>//crx-quickstart/launchpad/felix/bundle<id>/data/master
  9. In crxde, rename truststore and ssl keystore in case they need to be restored
    • /etc/truststore
    • /home/users/system/security/ssl-service/keystore
  10. Stop and then restart AEM on publisher/target instance , and verify AEM comes up normally. The restart will create a new /etc/truststore.
  11. Re-configure the SSL and check & install the required certs as needed.  OR you can try to reset password. 
In case you have trust store & keystore password with you , you can reset them, 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  need to the re-encrypt trust store and key store passwords ( /system/console/crypto ) and update “keystorePassword” properties at both the locations. This may resolve the issue.

You can get more details on How to encrypt data in AEM 

How to validate the keys: 

You can run a command in terminal “md5sum hmac” under the data folder and can help to match the key with all the servers to validate if the same key exists for all the servers. 


  1. Thanks for the detailed steps. Not even Adobe has such good article.

  2. Is this syncing of hmac and master files are required only one time for a server? Means once above steps are done we can use same encrypted passwords for any configurations that would work on both author and publish?


Post a Comment

Popular Posts

how to clear dispatcher cache in aem ?

AdobeDispatcherHacks ".statfile"

AEM Security Headers

How Does S3 works with AEM ?

How to Increase Apache Request Per Second ?

Configure/Decoding AEM AuditLogs

Dispatcher flush from AEM UI

curl command AEM package filter addition creation

How to configure s3 in AEM ?