Concept - Encryption


The ICM sometimes needs to encrypt (and decrypt) data, for example, for persistence or transport. Therefore, the ICM uses a separate library named com.intershop:encryption. This library provides code that implements all the use cases required by the ICM. The library also provides a command-line tool that can be used, for example, to create an encryption configuration from scratch.



Component Overview

The encryption library consists of the following software components to implement the use cases:

The components have the following semantics / purpose:




This is the main component that actually implements the encrypt, decrypt and re-encrypt use cases. To do this, it uses several other components, most notably the KeyManager (to look up the required keys) and the CipherFactory (to look up the matching JCE cipher).


Implements the lookup (and storage) of JCE-Keys.


Implements the lookup of JCE-Cipher instances.


Contains 1 to n EncryptionConfig instances and implements the lookup.


Encapsulates a single encryption config, see Concept - Encryption.


Implements some constrains to be fulfilled, especially regarding the strictMode, see Concept - Encryption.


Encapsulates encrypted data (how it is stored or transported) and contains code to parse and render string representations of encrypted data, see Concept - Encryption.


Implements the instantiation of a KeyManager that chooses the correct implementation based on the strictMode and the existence of the keystore file and the random file, see Concept - Encryption and Concept - Encryption.


Implementation of KeyManager that accesses a JCE-KeyStore that is secured by the keystore file.


NoOp-implementation of KeyManager used if keystore file and/or the random file are missing.


Encapsulates the actual passphrase to access the keystore file.


Encapsulates a passphrase consisting of letters and digits.


Encapsulates the access to the random file.


Global Encryption Configuration

The configuration of the encryption framework consists of the following aspects:

  • Location of the keystore file

  • Location of the random file

  • The strictMode flag, see Concept - Encryption | The Strict Mode

  • Several other configuration values for the several instances of EncryptionConfig

These aspects are reflected in the GlobalEncryptionConfiguration interfaces, which contain appropriate accessor methods in addition to the getConfigurationAccessor method, which returns an instance of ConfigurationAccessor that provides access to all remaining configuration values.

The Strict Mode

Main purpose of the strictMode flag (intershop.encryption.strictMode.enabled) is to ensure that PRD environments do not use the PLAIN encryption. Therefore, the strictMode is enabled by default. An enabled strictMode has the following consequences:

  • If the keystore file is missing, the server start fails.

  • If the random file is missing, the server start fails.

  • When trying to encrypt a value (com.intershop.common.encryption.capi.EncryptionManager#encryptString) with algorithm=PLAIN, the encryption fails with an exception.

On the other hand, a disabled strictMode has the following consequences:

  • The server can start without the keystore file and the random file.

  • The server can start without the file.

    • The KeyManagerFactory uses the NullKeystore.

    • A default EncryptionConfig with algorithm=PLAIN is used.

As a result, PRD environments are forced to use proper encryption, and developers can omit the encryption configuration altogether.

Encryption Configs

The encryption framework supports 0 to n different encryption configs, which contain the following attributes:






Placeholder inside the keys of the properties




Name/ID of the encryption config




Name of the encryption algorithm to use


optional, default=PBEWithHmacSHA512AndAES_256


If true, this config is the default config and will be used for each encryption


optional, default=false

The properties are then organized into groups of 1 to 3 property entries, all using the same placeholder and following the pattern:


Typically the placeholders are numeric values starting with 0.

Example encryption configs properties:

#Intershop Encryption Configuration
#Fri Apr 12 07:19:44 CEST 2024


There is the additional property intershop.encryption.keystore.password, see Concept - Encryption | The Keystore-file for details.

The Keystore-file

The keys to be used for encryption and decryption are stored in a JCEKS keystore. This keystore and the keys within this keystore are encrypted using a passphrase. Therefore, this passphrase is required to open the keystore and look up the keys. The storage of this passphrase is divided into 4 parts:

  • The value of the property intershop.encryption.keystore.password, see com.intershop.common.encryption.internal.KeystorePassphrase#externalPassphrase

  • Content of the random file

  • 90 hard-coded indexes pointing to chars out of the random file content

  • 90 hard-coded chars

Configuration Creation and Manipulation

To create the above mentioned encryption configs, the keystore file, and the random file, a command line tool is provided as a Docker container. The corresponding Docker image is available at DockerHub. For a detailed description of how to use it, refer to Cookbook - Encryption.

Encrypted Data Syntax

For many use cases, encrypted data needs to be stored in a database, for example. This data needs to be decrypted later. So the encrypted data has to be stored in a way that it can be decrypted even if the default encryption config (see Concept - Encryption | Encryption Configs) has been changed. Therefore, the encrypted data contains the following information:




Encryption config ID

1 to n chars out of:

  • Upper- and lowercase letters

  • Digits

  • _


Algorithm name

1 to n chars out of:

  • Upper- and lowercase letters

  • Digits

  • _

  • /

  • .

  • -


Salt used during encryption (optional)

1 to n chars out of (base64-alphabet):

  • Upper- and lowercase letters

  • Digits

  • _

  • +

  • =


Actual data

1 to n chars out of (base64-alphabet):

  • Upper- and lowercase letters

  • Digits

  • _

  • +

  • =


Initialization vector used during encryption (optional)

1 to n chars out of (base64-alphabet):

  • Upper- and lowercase letters

  • Digits

  • _

  • +

  • =


The encryption data as a whole follows the pattern: <id>@<algorithm>:[<salt>|]<data>[|<ivSalt>]


During a typical encryption, see com.intershop.common.encryption.capi.EncryptionManager#encryptString, the following steps are executed:

  1. Look up default encryption config.

  2. Look up the key that matches that encryption config.

  3. Instantiate JCE-Cypher matching that key (using generated salt and initialization vector).

  4. Execute the actual encryption.

  5. Render encrypted data, see Concept - Encryption | Encrypted Data Syntax.


During a typical decryption, see com.intershop.common.encryption.capi.EncryptionManager#decryptString, the following steps are executed:

  1. Parse the encrypted data, see Concept - Encryption | Encrypted Data Syntax.

  2. Look up default encryption config using the ID from the encrypted data.

  3. Look up the key that matches that encryption config.

  4. Instantiate JCE-Cypher matching that key (using salt and initialization vector from the encrypted data).

  5. Execute the actual decryption.


During a typical encryption, see com.intershop.common.encryption.capi.EncryptionManager#reencryptString, the following steps are executed:

  1. Decrypt the data.

  2. Encrypt the data (typically using a new default encryption config).

The Client Side (e.g. icm-as)

The code that uses the encryption library must use the methods of the com.intershop.common.encryption.capi.EncryptionManager. The provided implementation of com.intershop.common.encryption.capi.EncryptionManager is com.intershop.common.encryption.internal.EncryptionManagerImpl, which has dependencies on:

  • EncryptionConfigs

  • EncryptionConstraints

  • KeyManager

  • CipherFactory

Therefore, the code you use must instantiate these components (in icm-as, see com.intershop.beehive.core.internal.modules.EncryptionModule). The most complex part is creating the KeyManager, so this is implemented in com.intershop.common.encryption.internal.KeyManagerFactoryImpl.

It actually executes the following steps:

  • If a keystore file and a random file exist: Return a com.intershop.common.encryption.internal.Keystore that can load the keys from the keystore file.

  • If either the keystore file or the random file is missing:

    • If strictMode is enabled: Let the creation fail with a meaningful exception (make the icm-as-startup fail).

    • If strictMode is disabled: Return a com.intershop.common.encryption.internal.NullKeystore that just is a no-op-implementation (allows to run the icm-as without any encryption config).

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.