SAP Commerce (Hybris): How to Rotate the Encryption Key

Hybris uses encryption for any attributes marked with encrypted="true". You can find these attributes in the OOTB installation by looking for that string - those are OAuth tokens, various credentials and even all users passwords - the passwords in particular are hashed and then encrypted. You can read more about transparent attribute encryption (which is what this feature is called in Hybris) here: Transparent Attribute Encryption (TAE).

What is Key Rotation?

Key rotation just means generating of a new encryption key and importing it into the system, so Hybris can use it for encryption of sensitive data from that point on.

It is recommended to rotate the key from time to time. PCI DSS standard requires at least an annual rotation.

When we rotate the key, we are never supposed to delete any previous keys. If any data was originally encrypted with the previous key (so up to the point of rotation), then Hybris will need that previous key in order to decrypt it.

Where Are the Keys Stored?

The keys are stored in your config/security directory.

For example, here is my config directory containing two keys:

In addition, in your local.properties, you enumerate all the keys in your system - the previous ones, as well as the current one, and also indicate which key should be used now, e.g.:

symmetric.key.file.1=default-128-bit-aes-key.hybris
symmetric.key.file.2=Generated-256-Bit-AES-Key.hybris
symmetric.key.file.default=2        

Out of the Box Key

When you just initialized the system, you won't have the "security" directory, but make no mistake thinking there is no key! The OOTB key is located here: hybris/bin/platform/ext/core/resources/security/default-128-bit-aes-key.hybris. How do you know? You can find the mention of it in this file hybris/bin/platform/project.properties in the comments.

Before the First Rotation

As we mentioned before, all the keys should be enumerated in your local.properties and assigned a number, so Hybris can decrypt any data in your database, no matter when it was encrypted and with which of the keys.

We should enumerate the OOTB key in our local.properties, so anything encrypted before your first rotation - could be read if needed.

Create the "security" directory under "config" and copy hybris/bin/platform/ext/core/resources/security/default-128-bit-aes-key.hybris to your new config/security.

Put the following lines in your local.properties:

symmetric.key.file.1=default-128-bit-aes-key.hybris
symmetric.key.file.default=1        

Then rebuild and restart Hybris, make sure you can still log in with a few users, to both the administration apps, as well as your storefront.

How to Do the Rotation?

Log in to HAC and go to Maintenance --> Encryption Keys, stay on tab "Generation", select key size = 256, update output file name to reflect that, and click "Generate":

Hybris will generate the key file and will place it to your config/security directory, it will now contain all the previous keys plus the new key. In my case here it contains the original OOTB key plus the new key:

Now edit your local.properties, add the reference to the new key, and update the symmetric.key.file.default property to point to the new key:

symmetric.key.file.1=default-128-bit-aes-key.hybris
symmetric.key.file.2=Generated-256-Bit-AES-Key.hybris
symmetric.key.file.default=2        

Rebuild and restart Hybris, verify that your logins to the administrative applications, as well as to the storefront, still work.

What Happens to the Data Encrypted Before the Rotation?

The data encrypted with the old key - stays the same, but Hybris can still read it, because you are never supposed to delete the old keys.

Hybris has access to all the keys if needed, and you configured that in your local.properties file by enumerating all the keys, both the old ones and the new one.

Rotation in CCv2

In order to rotate the key in your environment hosted on CCv2, you need to first generate the new key locally, and then upload it to CCv2.

In CCv2, go to Security:

Choose tab "Security Files" and click "Create":

Upload your security file, give it the name (usually the same as the file) and description, and click "Create".

You can use the same file for all environments, or for a more secure solution - different file for different environments.

Also, for CCv2, you don't include the symmetric.key.file.* properties into your local.properties, but instead you configure them in your hcs_common:

Conclusion

In this tutorial we rotated the encryption key. Please don't neglect doing this on your production systems, for the best practice in security!