SAP Commerce (Hybris): How to Update Master Password for Transparent Attribute Encryption (TAE)

Transparent Attribute Encryption is one of the features of SAP Commerce where it can encrypt certain fields, for the best practice of security. These fields are marked with encrypted="true", you can search for this string in the OOTB solution and you will see some, like OAuth tokens, credentials, and even users' passwords - the passwords in particular are first hashed and then encrypted. You can read more about TAE here: Transparent Attribute Encryption (TAE).

Master Password

The encryption is done using a symmetric cipher, which means that the key to encrypt and decrypt is the same. TAE uses AES (Advanced Encryption Standard).

The encryption keys themselves are protected using the master password.

The default master password is very simple - it is "1234567". To confirm what it is in your system, you can run the following Groovy script from HAC:

import de.hybris.platform.servicelayer.config.ConfigurationService
import de.hybris.platform.util.Config

def configurationService = spring.getBean("configurationService", ConfigurationService)

// Check for TAE master password property
def taeMasterPassword = configurationService.getConfiguration().getString("symmetric.key.master.password", "NOT SET")

println "TAE Master Password (encrypted or stored value): $taeMasterPassword"

// Alternative way: Directly fetch from Config class
def taePasswordFromConfig = Config.getParameter("symmetric.key.master.password")
println "TAE Master Password (Config lookup): $taePasswordFromConfig"        

If it is "1234567", then it needs to be updated to a more complex one.

Your encryption key is already protected by your old master password. So, if you just change the master password, Hybris won't be able to utilize that encryption key to decrypt data, because it won't be able to decrypt the key.

Therefore, you will need to generate the new encryption key for the new password.

Your Data May Get Lost!

Please note that if you just update the master password and regenerate the key, then Hybris won't be able to decrypt any data before that point, because it was encrypted with the encryption key protected by the old password, and it no longer knows what the old password was.

Therefore, one way to do it is to re-initialize the system once you update the master password and regenerate the key, so there is no data that was encrypted before your change, and all further data will be encrypted with the new encryption key and will be readable.

Of course, in production systems, you won't be able to re-initialize the system. You will need to decrypt all the previous encryption keys with the old password, and then re-encrypt them with your new password. I will describe how to do it later on in this article.

Please read this article to the end before any manipulation of master password and key on your system!

Updating Master Password and Generating New Encryption Key

As we mentioned before, once you update the master password, you need to also regenerate the encryption key - that is to do the key rotation.

You cannot update the master password straight in your local.properties and then restart the system so your changes take place. This is because once you restart, Hybris won't be able to decrypt any data, since the current encryption key was encrypted with the old password, and so it cannot decrypt it with the new password - therefore no one will be able to log in, neither to the admin apps nor to your storefront.

To update the master password correctly - log in to HAC locally and from HAC update the property "symmetric.key.master.password" to your desired password (again, remember not to do it in your local.properties just yet). Don't forget to press the checkmark:

Then go to Maintenance --> Encryption Keys, and generate the new key like it is described in SAP Commerce (Hybris): How to Rotate the Encryption Key, including the first rotation if you haven't done it yet, as well as the updates to your local.properties for your new encryption key.

At this point you can also put your new password to your local.properties:

symmetric.key.master.password=<your-new-password>        

After you've done all of the above, you can either stop, rebuild and re-initialize the system, or look at the next section of this article to re-encrypt the previous keys with the new password, so Hybris can access any previously encrypted data.

If you are not inclined to re-initialize the system, then make sure not to stop Hybris without doing what's described in the next section! If you do stop, rebuild and re-run Hybris, then on any login you will face an exception like "de.hybris.platform.persistence.security.PasswordEncoderException: Exception while checking encoded password for user: 8796125921284. Invalid salt and/or hash" for the pre-existing users.

So, read on!

Re-Encrypting the Previous Keys

You will need to run a Groovy script to decrypt your old key(s) using the old password, and then re-encrypt with the new password. SAP has the script in this article: 2311299 - How to change the master password (symmetric.key.master.password). I modified it a little bit for readability and am pasting it in here, just in case they remove the article or change the link (which happens sometimes):

//---
import java.io.File;
import java.io.FileInputStream;
import javax.crypto.Cipher;
import javax.crypto.spec.PBEKeySpec;
import javax.crypto.spec.PBEParameterSpec;
import javax.crypto.SecretKeyFactory;
import javax.crypto.SecretKey;
import de.hybris.platform.util.config.ConfigIntf;
import de.hybris.platform.core.Constants;
import de.hybris.platform.core.Registry;
import de.hybris.platform.util.encryption.ValueEncryptor;
import de.hybris.platform.util.encryption.EncryptionUtil;
 
//path for the hybris AES Key
def path = "<your-folder>/hybris/config/security/";
def key = "default-128-bit-aes-key.hybris";
//here is the old password
char[] passwordOld = "1234567";
 
//can either type the new password here or get it from local.properties file
char[] passwordNew = "7654321";
//char[] passwordNew = cfg.getParameter(Constants.Encryption.SYMMETRIC_KEY_FILE_MASTERPASSOWRD).toCharArray();
 
def ITERATIONS = 1000;
 
ConfigIntf cfg = Registry.getMasterTenant().getConfig();
String cipherAlgorithm = cfg.getParameter(Constants.Encryption.SYMMETRIC_ALGORITHM);
 
//---------------- read in
File keyOld = new File(path + key);
byte[] saltAndKeyBytes = keyOld.readBytes();
 
//---------------- backup
File keyBackup = new File(path + key + ".bak");
if (keyOld.renameTo(keyBackup)) {
    println("Old key backed up");
}
 
//---------------- decrypt out the real key
 
byte[] salt = new byte[8];
System.arraycopy(saltAndKeyBytes, 0, salt, 0, 8);
 
int length = saltAndKeyBytes.length - 8;
byte[] encryptedKeyBytes = new byte[length];
 
System.arraycopy(saltAndKeyBytes, 8, encryptedKeyBytes, 0, length);
 
PBEKeySpec pbeKeySpec = new PBEKeySpec(passwordOld);
SecretKeyFactory keyFactory = SecretKeyFactory.getInstance(cipherAlgorithm);
SecretKey pbeKey = keyFactory.generateSecret(pbeKeySpec);
PBEParameterSpec pbeParamSpec = new PBEParameterSpec(salt, ITERATIONS);
 
Cipher cipher = Cipher.getInstance(cipherAlgorithm);
 
cipher.init(Cipher.DECRYPT_MODE, pbeKey, pbeParamSpec);
byte[] decryptedKeyBytes = cipher.doFinal(encryptedKeyBytes);
 
//------------------ encrypt the real key with new password
PBEKeySpec pbeKeySpecNew = new PBEKeySpec(passwordNew);
SecretKey pbeKeyNew = keyFactory.generateSecret(pbeKeySpecNew);
cipher.init(Cipher.ENCRYPT_MODE, pbeKeyNew, pbeParamSpec);
byte[] encryptedKeyBytesNew = cipher.doFinal(decryptedKeyBytes);
 
//------------------ combine salt and new encrypted key to form the new Key file
File keyNew = new File(path + key);
keyNew.append(salt);
keyNew.append(encryptedKeyBytesNew);        

You need to run this script on every key that you used to have before you generated the new key with the new password. The program will create the backup of each old key.

In my system there was only one old key - the original OOTB encryption key. So, after I ran this script, here is how my security folder looks:

After this procedure, you can stop, rebuild and re-run Hybris, and you should be able to log in with any previous user to either admin apps or to your storefront, and all previously encrypted data will be accessible.

In CCv2

This procedure does not differ from that you need to do in CCv2. Please also take look at CCv2 steps in SAP Commerce (Hybris): How to Rotate the Encryption Key.

Conclusion

It is very important to change the OOTB master password, as it is very simple and well known. But please exercise care so you don't lose all your encrypted data, and no users can log in!