AEM Encryption Service: What, How & Why

Adobe Experience Manager (AEM) provides an encryption service which helps to encrypt text and decrypt the protected text. The support is available in AEM with the bundle name Adobe Granite Crypto Support (com.adobe.granite.crypto).

It can be used to:

1. Encrypt properties configured in OSGI configuration service
2. Meet the need to protect/unprotect text or binary data in the backend logic

Protecting OSGI Configuration

First the question arises why do we need to protect OSGI configuration when not everyone can access the admin config console?

The answer is simple, OSGI configuration may contain passwords or any sensitive information and at the end when the configuration gets saved, they are saved in the repository and can be accessed from /apps. Anyone with access to /apps folder can read them from crx/de console. Keeping them in encrypted form helps, as even if the configuration file is accessible from crx/de, the property can not be decrypted manually.

In order to protect the OSGI configuration, we need to follow these steps:

1. AEM plugins provide a support in felix consoles to decrypt the plain property text, “Crypto support” option is available in under “Main” option in felix console menu or directly access it using url http://<host>:<port>/system/console/crypto
2. Paste the property value in a plain text field and click on the “Protect” button to get the Protected text
3. Use this protected property in any of the OSGI configurations using the configuration manager console or even maintain it in the code base

Unprotect OSGI Configuration

There is no need to explicitly decrypt these protected configurations in java configuration service. AEM out of the box (OOTB) returns the properties in java by decrypting them beforehand.

Protect Plain Text in Java

We can use AEM’s crypto API in our backend logic to protect plain text and binary data in backend logics. We need to use CryptoSupport Service.

Below is the sample code to protect data:

Unprotect Protected Text in Java

We can unprotect protected text and binary data in backend logics using CryptoSupport Service.

Below is the sample code to unprotect data:

Using Crypto Support for Multiple Publisher Environment Setup

In order to support cryptography in multiple publisher AEM instances setup, we need to have the same HMAC key across all instances. This setup is must if:

1. We maintain protected configuration in the code base that is deployed on all publishers.
2. If text protected in one instance reaches another instance for decryption in backend logic.
3. If we enable Encapsulated Token Support in AEM. In this, we will have to sync keys of author instances also with all publisher instances.

If we do not sync the HMAC keys over all instances, we are going to get Crypto Exception com.adobe.granite.crypto.CryptoException exception upon decryption.

Steps to sync keys across all instances for AEM 6.3 or above:

1. Go to /system/console/bundles and search for a bundle with name “Adobe Granite Crypto Bundle Key Provider” i.e ”com.adobe.granite.crypto.file” and note down the bundle number. In below screenshot, bundle number is 20.
    
2. Go to repository in filesystem and go to folder <repository-folder>/crx-quickstart/launchpad/felix/bundle20 and here the bundle folder is bundle20 because the number for the com.adobe.granite.crypto.file is 20 in previous step.
3. Go to data folder and copy two files present i.e hmac and master
4. Now follow the same steps for all the other instances and replace the two files with copied files.
5. Once done refresh Adobe Granite Crypto Support bundle i.e com.adobe.granite.crypto.

Steps to sync keys across all instances for AEM 6.2 or below:

1. Create package of path /etc/key from one of the instance using package manager
2. Install the package created in other instances
3. Restart all the instances where package has been installed

We hope this article helps you.