Crypto Modules

Crypto modules responsible for delivering cryptographic services, like generation of random bytes, encryption of data, or generation of keys, to CLM. A crypto module must be set as active, in order to use its random generator and encryption certificate to encrypt data in CLM. This is performed over the crypto module table view in the UI and over the CLM-API. There can only be one active crypto module in CLM. As long as no crypto-module is configured (or is misconfigured, or no active crypto module exists) it is not possible to create key pairs in CLM.

Crypto Module Types

There are two types of crypto modules, Built-in and MTG CARA.

Built-in Crypto Module

In the built-in crypto module, the random bytes are generated in software; data is encrypted with a key in software and keys are generated using software-based random byte generation.

In order for the built-in mechanism to work, it is necessary to specify a crypto module password at the configuration properties of CLM. The property is called crypto.module.builtin.password. If no crypto module password is present, then it is not possible to use the key pair generation mode where keys are generated (on the server side). Random bytes are created in software.

If the built-in crypto module is active and its password is present, the random bytes are generated in software. Server-based key generation is then possible and the key pair to use for encryption is also in software. This key pair is protected by the crypto module password.

The use of the built-in crypto module is recommended in cases where CLM is not used in conjunction with MTG CARA but only with other providers. It is also suited for integration or for test systems where security is not a major issue.

Losing or changing the built-in crypto module password would result in non-recoverable private keys.

MTG CARA Crypto Module

In the MTG CARA crypto module a CARA-based certificate provider is used as the basis for the cryptographic operations. The data is encrypted with an encryption root. Depending on the configuration at CARA this may be software-based or HSM-based. Also for the random byte generation it is possible to use either an HSM or software.

If a CARA-based crypto module is present, then the random bytes are generated either in software or in the HSM. Server-based key generation is done in CARA. It is performed in software. It is possible to use either a software or HSM based random number generation. The key pair to use for encryption can be located in software or the HSM.

In order to create an MTG CARA crypto module, you must first choose an existent CARA-based certificate provider. The keys used for decryption are stored in this provider. In order for server-side key generation to function properly, you must first create a root certificate with an RSA key pair. You may choose a software or HSM device to create the key pair. Then, you must add the new VCA property clm.encryption.root.cert.id for the CLM application and place the ID of the newly created encryption root CA.

In the MTG CARA crypto module you may also specify whether an HSM should be used as the entropy source for the generation of key pairs (which takes place in software) and as a random byte generator for passwords and other random data in CLM. The corresponding configuration parameter is called Hardware RNG and has two possible values. The first value is preferred, which states that if an HSM is available and configured in CARA, then it should be used as an entropy source. If it is not available, then a software-based entropy source could be used instead. The second value is mandatory, which states that an HSM must be used as an entropy source. In this case the HSM is always used as the entropy source. If there is no HSM available at CARA, this would result in errors during generation of random data.

Below is an overview of the different configuration possibilities and the corresponding actions taken by MTG CLM.

Table 1. Crypto module configuration possibilities and actions.
Crypto Module Type/Configuration	Key Generation	Entropy Source for Key Generation	Random Data Generation
Built-in	In software in CLM	In software in CLM	In software in CLM
MTG CARA Hardware RNG mandatory CARA with HSM	In software in CARA	HSM	HSM
MTG CARA Hardware RNG mandatory CARA without HSM	Error	Error	Error
MTG CARA Hardware RNG preferred CARA with HSM	In software in CARA	HSM, on error in Software in CARA	HSM, on error in Software in CLM
MTG CARA Hardware RNG preferred CARA without HSM	In software in CARA	Software	Software

If you operate CARA without an HSM, always choose preferred as value for Hardware RNG.

Deleting/losing the keys in the CARA certificate provider would result in non-recoverable private keys.

Standard Crypto Modules Interactions

Available crypto Modules can be viewed and searched in the Administration/Crypto Modules/Show page. There is also a filter an admin can use, to view archived crypto modules only. This filter can be triggered by pressing the Show Archived button in the Actions dropdown list.
New crypto modules can be created in the Administration/Crypto Modules/Create page. After selecting Crypto Module Type, the corresponding configuration options are available, as described in Crypto Module Types. Existing crypto modules cannot be edited.
A crypto module can be archived or unarchived in the Administration/Crypto Modules/Show page. There, by clicking a crypto module’s ID, the user will be redirected to the crypto module details page. By pressing the Archive or Unarchive button, the crypto module will be archived or unarchived. Batch Archive and Batch Undo-Archive actions are also supported by selecting the checkboxes of the desired crypto modules and choosing the Archive All Selected and Undo-Archive All Selected buttons in the Actions dropdown.
An archived crypto module can be deleted in the Crypto Module Details or the Show Crypto Modules Table page. In the Crypto Module Details page after archiving the entity a Delete button will appear. In the Show Crypto Module Table page, by pressing Actions→Show Archived, the table will show the archived entities. Here the crypto modules can be selected, and through Actions→Delete all selected they can be deleted. Furthermore, the user can delete one crypto module at a time by pressing the row actions button and then Delete Crypto Module.

In order for a crypto module to be archived, it must not be set as active. This means that for the current active crypto module to be archived, an admin user should first set another crypto module as active and then archive the previous one.